Badges

GET /api/v1/badges

const badges = await useLoyalty.badges.list();

GET /api/v1/badges/:badgeId

const badge = await useLoyalty.badges.get("badge_early_adopter");

{
  "id": "badge_early_adopter",
  "name": "Early Adopter",
  "description": "Joined during the beta period",
  "imageUrl": "https://cdn.example.com/badges/early-adopter.png",
  "rarity": "RARE",
  "criteria": { "joinedBefore": "2024-03-01" }
}

GET /api/v1/members/:externalId/badges/:badgeId

const earned = await useLoyalty.badges.getMemberBadge(
  "user_123",
  "badge_early_adopter",
);
// { ...badge, earnedAt: "2024-01-20T10:30:00Z" }

GET /api/v1/members/:externalId/badges

{
  "badges": [
    {
      "id": "badge_early_adopter",
      "name": "Early Adopter",
      "description": "Joined during the beta period",
      "imageUrl": "https://cdn.example.com/badges/early-adopter.png",
      "rarity": "RARE",
      "awardedAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "badge_first_purchase",
      "name": "First Purchase",
      "description": "Made your first purchase",
      "imageUrl": "https://cdn.example.com/badges/first-purchase.png",
      "rarity": "COMMON",
      "awardedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 2
}

POST /api/v1/members/:externalId/badges

{
  "badgeId": "badge_vip_member"
}

{
  "success": true,
  "badge": {
    "id": "badge_vip_member",
    "name": "VIP Member",
    "description": "Reached VIP status",
    "imageUrl": "https://cdn.example.com/badges/vip.png",
    "rarity": "LEGENDARY",
    "awardedAt": "2024-01-20T16:00:00Z"
  },
  "member": {
    "externalId": "user_123",
    "badgeCount": 3
  }
}

DELETE /api/v1/members/:externalId/badges

{
  "badgeId": "badge_vip_member"
}

{
  "success": true,
  "message": "Badge removed successfully"
}

async function awardBadge(userId: string, badgeId: string) {
  const response = await fetch(
    `https://app.useloyalty.app/api/v1/members/${userId}/badges`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.USELOYALTY_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ badgeId }),
    },
  );

  if (response.status === 409) {
    // Member already has this badge
    return { alreadyAwarded: true };
  }

  return response.json();
}

// Award milestone badges
async function checkMilestones(userId: string) {
  const member = await getMember(userId);

  // Purchase milestones
  if (member.purchaseCount >= 10 && !hasBadge(member, "badge_10_purchases")) {
    await awardBadge(userId, "badge_10_purchases");
  }

  // Points milestones
  if (
    member.totalPointsEarned >= 10000 &&
    !hasBadge(member, "badge_10k_points")
  ) {
    await awardBadge(userId, "badge_10k_points");
  }

  // Streak milestones
  if (member.longestStreak >= 30 && !hasBadge(member, "badge_30_day_streak")) {
    await awardBadge(userId, "badge_30_day_streak");
  }
}

async function getBadgeCollection(userId: string) {
  const response = await fetch(
    `https://app.useloyalty.app/api/v1/members/${userId}/badges`,
    {
      headers: {
        Authorization: `Bearer ${process.env.USELOYALTY_API_KEY}`,
      },
    },
  );

  const data = await response.json();

  // Group by rarity for display
  const grouped = {
    legendary: data.badges.filter((b) => b.rarity === "LEGENDARY"),
    epic: data.badges.filter((b) => b.rarity === "EPIC"),
    rare: data.badges.filter((b) => b.rarity === "RARE"),
    uncommon: data.badges.filter((b) => b.rarity === "UNCOMMON"),
    common: data.badges.filter((b) => b.rarity === "COMMON"),
  };

  return grouped;
}

// Integrate with your event system
async function onUserAction(userId: string, action: string, data: any) {
  switch (action) {
    case "purchase":
      await checkPurchaseBadges(userId, data);
      break;
    case "review":
      await checkReviewBadges(userId, data);
      break;
    case "referral_converted":
      await checkReferralBadges(userId, data);
      break;
  }
}

async function checkPurchaseBadges(userId: string, purchase: any) {
  const stats = await getUserPurchaseStats(userId);

  const milestones = [
    { count: 1, badge: "badge_first_purchase" },
    { count: 10, badge: "badge_10_purchases" },
    { count: 50, badge: "badge_50_purchases" },
    { count: 100, badge: "badge_100_purchases" },
  ];

  for (const milestone of milestones) {
    if (stats.totalPurchases >= milestone.count) {
      await awardBadge(userId, milestone.badge).catch(() => {
        // Already awarded, ignore
      });
    }
  }
}

async function awardBadgeWithNotification(userId: string, badgeId: string) {
  try {
    const result = await awardBadge(userId, badgeId);

    if (result.success) {
      // Send notification
      await sendNotification(userId, {
        type: "badge_earned",
        title: "New Badge Earned!",
        message: `You earned the "${result.badge.name}" badge!`,
        imageUrl: result.badge.imageUrl,
        data: {
          badgeId: result.badge.id,
          rarity: result.badge.rarity,
        },
      });

      // Track analytics
      await trackAnalytics("badge_earned", {
        userId,
        badgeId: result.badge.id,
        badgeName: result.badge.name,
        rarity: result.badge.rarity,
      });
    }

    return result;
  } catch (error) {
    if (error.status === 409) {
      // Already has badge, not an error
      return { alreadyAwarded: true };
    }
    throw error;
  }
}

{
  "error": "Conflict",
  "message": "Member already has this badge"
}

// Safe to call multiple times
async function ensureBadge(userId: string, badgeId: string) {
  try {
    await awardBadge(userId, badgeId);
  } catch (error) {
    if (error.status !== 409) {
      throw error; // Re-throw non-duplicate errors
    }
  }
}

// Good
const badges = {
  badge_first_purchase: "First Purchase",
  badge_loyal_customer: "Loyal Customer",
  badge_review_champion: "Review Champion",
};

// Avoid
const badges = {
  badge_1: "Badge 1",
  badge_a: "Achievement A",
};

// Track badge tiers
const purchaseBadges = [
  { threshold: 1, id: "badge_purchase_1", name: "Shopper" },
  { threshold: 10, id: "badge_purchase_10", name: "Regular" },
  { threshold: 50, id: "badge_purchase_50", name: "VIP" },
  { threshold: 100, id: "badge_purchase_100", name: "Legend" },
];

async function awardPurchaseBadges(userId: string, purchaseCount: number) {
  for (const badge of purchaseBadges) {
    if (purchaseCount >= badge.threshold) {
      await ensureBadge(userId, badge.id);
    }
  }
}