Loyalty tiers in headless gamification

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

# Response (200 OK)
{
  "participant_id": "user_42",
  "current_tier": {
    "code": "gold",
    "name": "Gold",
    "level": 3,
    "color": "#FFD700",
    "achieved_at": "2026-02-01T10:00:00Z"
  },
  "next_tier": {
    "code": "platinum",
    "name": "Platinum",
    "points_required": 10000,
    "points_remaining": 8500
  },
  "tier_history": [
    { "code": "bronze", "name": "Bronze", "achieved_at": "2026-01-01T..." },
    { "code": "silver", "name": "Silver", "achieved_at": "2026-01-15T..." },
    { "code": "gold",   "name": "Gold",   "achieved_at": "2026-02-01T..." }
  ]
}

curl -X POST https://api.bricqs.com/api/v1/gamify/tiers/assign \
  -H "Authorization: Bearer bq_live_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vip-promo-2026-q2-user_42" \
  -d '{
    "participant_id": "user_42",
    "tier_code": "platinum",
    "reason": "VIP promotion (2026 Q2)"
  }'

# Response (200 OK)
{
  "participant_id": "user_42",
  "tier_code": "platinum",
  "tier_name": "Platinum",
  "level": 4,
  "previous_tier_code": "gold"
}

GET    /api/v1/gamify/tiers
GET    /api/v1/gamify/tiers/{tier_code}
POST   /api/v1/gamify/tiers
       { "code": "gold", "name": "Gold", "level": 3, "criteria": { "min_points": 5000 }, ... }
PATCH  /api/v1/gamify/tiers/{tier_code}
       { "name": "Gold Elite" }
DELETE /api/v1/gamify/tiers/{tier_code}

// In your contract-signing webhook
await fetch("https://api.bricqs.com/api/v1/gamify/tiers/assign", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRICQS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `enterprise-contract-${contract.id}`,
  },
  body: JSON.stringify({
    participant_id: contract.account_owner_id,
    tier_code: "platinum",
    reason: `Enterprise contract ${contract.id}`,
  }),
});

"use client";
import { useTier } from "@bricqs/sdk-react";

const MIN_LEVEL_GOLD = 3;

export function GoldOrAboveOnly({
  engagementId,
  children,
}: {
  engagementId: string;
  children: React.ReactNode;
}) {
  const { tierLevel, isLoading } = useTier({ engagementId });
  if (isLoading) return null;
  if (tierLevel == null || tierLevel < MIN_LEVEL_GOLD) {
    return <UpgradeCta />;
  }
  return <>{children}</>;
}

// POST /webhooks/bricqs, subscribed to tier.changed.v1
export async function POST(req: Request) {
  const event = await verifyAndParse(req); // your signature check

  const { new_tier, previous_tier } = event.payload;

  // Only run for upgrades, not downgrades
  if (rankOf(new_tier) <= rankOf(previous_tier)) {
    return new Response(null, { status: 200 });
  }

  await Promise.all([
    sendTierUpgradeEmail(event.participant_id, new_tier),
    syncTierToCrm(event.participant_id, new_tier),
    allocateWelcomeReward(event.participant_id, new_tier),
  ]);

  return new Response(null, { status: 200 });
}

// List inactive participants from your own analytics
const stale = await db.query(`
  SELECT participant_id FROM user_activity
  WHERE last_seen_at < NOW() - INTERVAL '12 months'
    AND current_tier_level > 1
`);

for (const { participant_id } of stale.rows) {
  await fetch("https://api.bricqs.com/api/v1/gamify/tiers/assign", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BRICQS_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `inactivity-decay-${participant_id}-${monthKey()}`,
    },
    body: JSON.stringify({
      participant_id,
      tier_code: "bronze",
      reason: "Inactivity decay",
    }),
  });
}