@23blocks/block-rewards

Rewards block for the 23blocks SDK - rewards, coupons, loyalty programs, and badges.


Installation

``bash
npm install @23blocks/block-rewards @23blocks/transport-http
`

Overview

This package provides rewards and loyalty program functionality including:

- Rewards - Reward definitions and redemptions
- Coupons - Discount codes and validation
- Loyalty - Points programs and transactions
- Badges - Achievement badges and gamification

Quick Start

`typescript
import { createHttpTransport } from '@23blocks/transport-http';
import { createRewardsBlock } from '@23blocks/block-rewards';

const transport = createHttpTransport({
baseUrl: 'https://api.yourapp.com',
headers: () => {
const token = localStorage.getItem('access_token');
return token ? { Authorization: Bearer ${token} } : {};
},
});

const rewards = createRewardsBlock(transport, {
apiKey: 'your-api-key',
});

// Get user's loyalty balance
const loyalty = await rewards.loyalty.getBalance('user-id');
console.log('Points:', loyalty.points, 'Tier:', loyalty.tier);

// Validate a coupon
const validation = await rewards.coupons.validate({
code: 'SAVE20',
cartTotal: 100,
});
`

Services

$3

`typescript
// List available rewards
const { data: rewardList } = await rewards.rewards.list({
status: 'active',
type: 'points_redemption',
});

// Get reward by ID
const reward = await rewards.rewards.get('reward-id');

// Create reward
const newReward = await rewards.rewards.create({
name: 'Free Coffee',
description: 'Redeem 100 points for a free coffee',
type: 'points_redemption',
pointsCost: 100,
status: 'active',
validFrom: '2024-01-01',
validTo: '2024-12-31',
});

// Update reward
await rewards.rewards.update('reward-id', {
pointsCost: 80,
});

// Delete reward
await rewards.rewards.delete('reward-id');

// Redeem reward
const redemption = await rewards.rewards.redeem({
rewardId: 'reward-id',
userId: 'user-id',
});
console.log('Redemption code:', redemption.code);

// List redemptions
const { data: redemptions } = await rewards.rewards.listRedemptions({
userId: 'user-id',
status: 'pending',
});
`

$3

`typescript
// List coupons
const { data: couponList } = await rewards.coupons.list({
status: 'active',
});

// Get coupon by ID
const coupon = await rewards.coupons.get('coupon-id');

// Get coupon by code
const coupon = await rewards.coupons.getByCode('SAVE20');

// Create coupon
const newCoupon = await rewards.coupons.create({
code: 'SUMMER24',
description: 'Summer sale discount',
discountType: 'percentage',
discountValue: 20,
minOrderAmount: 50,
maxUses: 1000,
maxUsesPerUser: 1,
validFrom: '2024-06-01',
validTo: '2024-08-31',
status: 'active',
});

// Update coupon
await rewards.coupons.update('coupon-id', {
maxUses: 2000,
});

// Delete coupon
await rewards.coupons.delete('coupon-id');

// Validate coupon
const validation = await rewards.coupons.validate({
code: 'SUMMER24',
cartTotal: 100,
userId: 'user-id',
});

if (validation.valid) {
console.log('Discount:', validation.discountAmount);
} else {
console.log('Invalid:', validation.error);
}

// Apply coupon
const application = await rewards.coupons.apply({
code: 'SUMMER24',
orderId: 'order-id',
userId: 'user-id',
});
`

$3

`typescript
// Get user's loyalty status
const loyalty = await rewards.loyalty.getBalance('user-id');
console.log('Points:', loyalty.points);
console.log('Tier:', loyalty.tier);
console.log('Lifetime points:', loyalty.lifetimePoints);

// Get loyalty tiers
const tiers = await rewards.loyalty.getTiers();
tiers.forEach((tier) => {
console.log(tier.name, tier.minPoints, tier.benefits);
});

// Add points
await rewards.loyalty.addPoints({
userId: 'user-id',
points: 50,
reason: 'purchase',
referenceId: 'order-123',
});

// Redeem points
await rewards.loyalty.redeemPoints({
userId: 'user-id',
points: 100,
reason: 'reward_redemption',
referenceId: 'redemption-456',
});

// List transactions
const { data: transactions } = await rewards.loyalty.listTransactions({
userId: 'user-id',
limit: 50,
});

transactions.forEach((tx) => {
console.log(tx.type, tx.points, tx.reason, tx.createdAt);
});
`

$3

`typescript
// List available badges
const { data: badgeList } = await rewards.badges.list();

// Get badge by ID
const badge = await rewards.badges.get('badge-id');

// Create badge
const newBadge = await rewards.badges.create({
name: 'Early Adopter',
description: 'Joined during beta',
imageUrl: 'https://example.com/badges/early-adopter.png',
criteria: {
type: 'registration_date',
beforeDate: '2024-01-01',
},
});

// Update badge
await rewards.badges.update('badge-id', {
description: 'Updated description',
});

// Delete badge
await rewards.badges.delete('badge-id');

// Award badge to user
await rewards.badges.award({
badgeId: 'badge-id',
userId: 'user-id',
awardedAt: new Date().toISOString(),
});

// List user's badges
const { data: userBadges } = await rewards.badges.listUserBadges({
userId: 'user-id',
});

userBadges.forEach((ub) => {
console.log(ub.badge.name, ub.awardedAt);
});

// Revoke badge
await rewards.badges.revoke('user-badge-id');
`

Types

`typescript
import type {
Reward,
RewardType,
RewardRedemption,
Coupon,
DiscountType,
CouponValidationResult,
Loyalty,
LoyaltyTier,
LoyaltyTransaction,
Badge,
UserBadge,
CreateRewardRequest,
RedeemRewardRequest,
CreateCouponRequest,
ValidateCouponRequest,
AddPointsRequest,
CreateBadgeRequest,
AwardBadgeRequest,
} from '@23blocks/block-rewards';
`

$3

- percentage - Percentage discount (e.g., 20% off)
- fixed - Fixed amount discount (e.g., $10 off)
- free_shipping - Free shipping

$3

- points_redemption - Redeem with loyalty points
- coupon_reward - Receive a coupon code
- product_reward - Receive a free product
- experience_reward - Access to exclusive experience

Related Packages

- @23blocks/block-products - Product catalog
- @23blocks/block-sales - Orders and checkout
- @23blocks/angular - Angular integration
- @23blocks/react - React integration
- @23blocks/sdk` - Full SDK package

License

MIT - Copyright (c) 2024 23blocks