Rewards in headless gamification

curl https://api.bricqs.com/api/v1/gamify/participants/user_42/rewards \
  -H "Authorization: Bearer bq_live_xxxxx"

# Response (200 OK)
{
  "participant_id": "user_42",
  "rewards": [
    {
      "claim_id": "claim_uuid_456",
      "reward_name": "10% Off Coupon",
      "reward_type": "coupon",
      "code_value": "SAVE10-ABC123",
      "claimed_at": "2026-05-24T11:42:00Z",
      "expires_at": "2026-06-23T..."
    }
  ],
  "total_claimed": 1
}

GET    /api/v1/gamify/rewards
POST   /api/v1/gamify/rewards
       { "name": "10% Off", "type": "coupon", "points_cost": 500, "max_claims_per_user": 1 }
PATCH  /api/v1/gamify/rewards/{reward_id}
       { "points_cost": 400 }
DELETE /api/v1/gamify/rewards/{reward_id}

# Inventory
POST   /api/v1/gamify/rewards/{reward_id}/codes
       { "codes": ["SAVE10-ABC123", "SAVE10-DEF456", ...] }

export async function redeemCoupon(participantId: string, rewardId: string, orderId: string) {
  const res = await fetch(
    `https://api.bricqs.com/api/v1/gamify/rewards/${rewardId}/claim`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.BRICQS_API_KEY}`,
        "Content-Type": "application/json",
        // Tying the key to the order means a checkout retry collapses
        // to one claim, but a deliberate new redemption (different order)
        // gets a fresh code.
        "Idempotency-Key": `order-${orderId}-reward-${rewardId}`,
      },
      body: JSON.stringify({
        participant_id: participantId,
        points_deduction: true,
      }),
    }
  );

  if (!res.ok) {
    const error = await res.json();
    // Map structured errors to user-visible messages
    if (error.type === "insufficient_points") return { ok: false, reason: "low_balance" };
    if (error.type === "inventory_exhausted") return { ok: false, reason: "sold_out" };
    if (error.type === "max_claims_exceeded") return { ok: false, reason: "limit" };
    throw new Error(`unexpected reward error: ${error.code}`);
  }

  const claim = await res.json();
  return { ok: true, code: claim.code_value, newBalance: claim.new_balance };
}

// Run every 30 minutes
const res = await fetch(
  "https://api.bricqs.com/api/v1/gamify/rewards",
  { headers: { Authorization: `Bearer ${process.env.BRICQS_API_KEY}` } }
);
const { rewards } = await res.json();

for (const r of rewards) {
  if (r.available_codes != null && r.available_codes < 50) {
    await slack.send({
      channel: "#rewards-ops",
      text: `Reward "${r.name}" has only ${r.available_codes} codes left.`,
    });
  }
}

// Gift a birthday coupon to every participant with a birthday today
const birthdays = await db.query(`
  SELECT user_id FROM users WHERE birthday_md = date_format(NOW(), '%m-%d')
`);

for (const { user_id } of birthdays.rows) {
  await fetch(
    `https://api.bricqs.com/api/v1/gamify/rewards/${BIRTHDAY_REWARD_ID}/claim`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.BRICQS_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `birthday-${user_id}-${new Date().getFullYear()}`,
      },
      body: JSON.stringify({
        participant_id: user_id,
        points_deduction: false,
      }),
    }
  );
}

async function loadCatalog() {
  const res = await fetch("https://api.bricqs.com/api/v1/gamify/rewards", {
    headers: { Authorization: `Bearer ${process.env.BRICQS_API_KEY}` },
    next: { revalidate: 300 }, // 5 minutes
  });
  return res.json();
}

export default async function RewardsCatalog() {
  const { rewards } = await loadCatalog();
  return (
    <ul>
      {rewards.map((r: any) => (
        <li key={r.id}>
          <h3>{r.name}</h3>
          <p>{r.points_cost ?? 0} points</p>
          {r.available_codes != null && r.available_codes < 10 && (
            <p className="text-amber-700">Only {r.available_codes} left!</p>
          )}
          <ClaimButton rewardId={r.id} />
        </li>
      ))}
    </ul>
  );
}