API Reference

UseLoyaltyWidget.init({
  publicKey: string;
  externalId: string;
  timestamp: number;
  signature: string;
  apiUrl?: string;
  theme?: WidgetTheme;
  language?: WidgetLanguage;
  member?: MemberData;
  onReady?: () => void;
  onError?: (error: Error) => void;
  onWelcomeBonus?: (points: number) => void;
}): void

// Open on button click
document.querySelector('#rewards-btn').addEventListener('click', () => {
  UseLoyaltyWidget.open();
});

// React example
<button onClick={() => window.UseLoyaltyWidget.open()}>
  View Rewards
</button>

UseLoyaltyWidget.close();

// Toggle button
document.querySelector('#toggle-btn').addEventListener('click', () => {
  UseLoyaltyWidget.toggle();
});

UseLoyaltyWidget.destroy();

// React cleanup example
useEffect(() => {
  return () => {
    window.UseLoyaltyWidget?.destroy();
  };
}, []);

POST /api/widget/init

{
  "origin": "https://your-site.com"
}

X-Widget-Auth: base64({"publicKey", "externalId", "timestamp", "signature", "member"})

{
  "project": {
    "name": "My Store",
    "widgetSettings": { ... }
  },
  "member": {
    "id": "mem_123",
    "externalId": "user_456",
    "name": "John Doe",
    "email": "john@example.com",
    "points": 1500,
    "totalPointsEarned": 2500,
    "currentStreak": 5,
    "longestStreak": 12
  },
  "activeMultipliers": [
    {
      "name": "Double Points Week",
      "multiplier": 2,
      "endsAt": "2024-01-28T00:00:00Z"
    }
  ],
  "welcomeBonus": 100
}

GET /api/widget/profile

{
  "id": "mem_123",
  "externalId": "user_456",
  "name": "John Doe",
  "email": "john@example.com",
  "avatarUrl": "https://...",
  "points": 1500,
  "totalPointsEarned": 2500,
  "currentStreak": 5,
  "longestStreak": 12,
  "lastCheckinAt": "2024-01-19T10:00:00Z",
  "memberSince": "2023-06-15T00:00:00Z"
}

PATCH /api/widget/profile

{
  "name": "John Smith",
  "avatarUrl": "https://new-avatar.com/img.jpg"
}

GET /api/widget/rewards

{
  "rewards": [
    {
      "id": "rwd_123",
      "name": "10% Discount",
      "description": "Get 10% off your next order",
      "imageUrl": "https://...",
      "pointsCost": 500,
      "type": "COUPON",
      "stockRemaining": 100,
      "userClaims": 0,
      "maxClaimsPerUser": 1,
      "minLevel": 2,
      "levelRequired": false,
      "canClaim": true,
      "affordableIn": 0
    }
  ]
}

POST /api/widget/rewards

{
  "rewardId": "rwd_123"
}

{
  "success": true,
  "claim": {
    "id": "clm_456",
    "reward": { ... },
    "pointsSpent": 500,
    "couponCode": "SAVE10-ABC123"
  },
  "member": {
    "points": 1000
  }
}

GET /api/widget/badges

{
  "earned": [
    {
      "id": "bdg_123",
      "name": "Early Adopter",
      "description": "Joined during beta",
      "imageUrl": "https://...",
      "rarity": "RARE",
      "awardedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "available": [
    {
      "id": "bdg_456",
      "name": "Power User",
      "description": "Complete 50 quests",
      "imageUrl": "https://...",
      "rarity": "EPIC"
    }
  ]
}

GET /api/widget/games

{
  "games": [
    {
      "id": "game_spin",
      "name": "Spin the Wheel",
      "type": "SPIN_WHEEL",
      "pointsCost": 0,
      "maxPlaysPerUser": null,
      "dailyPlaysLimit": 1,
      "cooldownMinutes": 1440,
      "prizes": [
        { "name": "10 Points", "value": 10, "weight": 50 },
        { "name": "50 Points", "value": 50, "weight": 30 },
        { "name": "100 Points", "value": 100, "weight": 15 },
        { "name": "500 Points", "value": 500, "weight": 5 }
      ]
    },
    {
      "id": "game_checkin",
      "name": "Daily Check-in",
      "type": "DAILY_CHECKIN",
      "pointsCost": 0,
      "streakBonuses": [
        { "day": 7, "bonus": 50 },
        { "day": 30, "bonus": 200 }
      ]
    }
  ]
}

POST /api/widget/games/:id/play

{
  "success": true,
  "result": {
    "prize": {
      "name": "50 Points",
      "value": 50
    },
    "pointsAwarded": 100,
    "basePoints": 50,
    "multiplier": 2,
    "multiplierEventName": "Double Points Week"
  },
  "member": {
    "points": 1600
  }
}

GET /api/widget/games/:id/checkin

{
  "canCheckin": true,
  "currentStreak": 5,
  "longestStreak": 12,
  "lastCheckinAt": "2024-01-19T10:00:00Z",
  "todayReward": 10,
  "streakBonus": null,
  "nextStreakBonus": {
    "day": 7,
    "bonus": 50,
    "daysAway": 2
  }
}

POST /api/widget/games/:id/checkin

{
  "success": true,
  "pointsAwarded": 10,
  "streakBonus": 0,
  "newStreak": 6,
  "member": {
    "points": 1610,
    "currentStreak": 6
  }
}

POST /api/widget/promo-code

{
  "code": "SUMMER2024"
}

{
  "success": true,
  "pointsAwarded": 100,
  "message": "Promo code redeemed successfully!"
}

GET /api/widget/referral

{
  "referralCode": "REF-A7X9K2",
  "shareLink": "https://yourapp.com/ref/REF-A7X9K2",
  "stats": {
    "totalReferrals": 15,
    "pendingReferrals": 3,
    "convertedReferrals": 12,
    "totalPointsEarned": 1200
  },
  "rewards": {
    "referrerReward": 100,
    "refereeReward": 50
  }
}

POST /api/widget/referral/code

{
  "referralCode": "REF-B8Y0L3",
  "shareLink": "https://yourapp.com/ref/REF-B8Y0L3"
}

GET /api/widget/social-share

{
  "platforms": ["twitter", "facebook", "linkedin", "whatsapp", "email"],
  "pointsPerShare": 10,
  "maxSharesPerDay": 5,
  "cooldownMinutes": 60,
  "todayShares": 2,
  "canShare": true
}

POST /api/widget/social-share

{
  "platform": "twitter",
  "shareType": "referral"
}

{
  "success": true,
  "pointsAwarded": 20,
  "multiplier": 2,
  "cooldownEndsAt": "2024-01-20T11:00:00Z"
}

{
  "error": "Error type",
  "message": "Human readable message"
}

X-Widget-Auth: base64({
  "publicKey": "pk_...",
  "externalId": "user_123",
  "timestamp": 1704067200000,
  "signature": "hmac_signature",
  "member": { ... }
})