Leaderboards in headless gamification

curl https://api.bricqs.com/api/v1/gamify/leaderboards/top_scorers/rank/user_123 \
  -H "Authorization: Bearer bq_live_xxxxx"

# Response (200 OK)
{
  "participant_id": "user_123",
  "rank": 2,
  "score": 4500,
  "total_participants": 1250,
  "percentile": 99.8
}

GET    /api/v1/gamify/leaderboards
GET    /api/v1/gamify/leaderboards/{leaderboard_code}
POST   /api/v1/gamify/leaderboards
       { "code": "top_scorers", "name": "Top Scorers", "metric": "points_balance",
         "default_period": "monthly", "cache_ttl_seconds": 30 }
PATCH  /api/v1/gamify/leaderboards/{leaderboard_code}
       { "cache_ttl_seconds": 60 }
DELETE /api/v1/gamify/leaderboards/{leaderboard_code}

import { LeaderboardPanel } from "@/components/LeaderboardPanel";

async function loadPodium(code: string) {
  const res = await fetch(
    `https://api.bricqs.com/api/v1/gamify/leaderboards/${code}?limit=3`,
    {
      headers: { Authorization: `Bearer ${process.env.BRICQS_API_KEY}` },
      next: { revalidate: 30 },
    }
  );
  return res.json();
}

export default async function LeaderboardPage() {
  const podium = await loadPodium("top_scorers");

  return (
    <main>
      <section className="podium">
        {podium.entries.map((e: any) => (
          <article key={e.participant_id}>
            <h3>#{e.rank} {e.display_name}</h3>
            <p>{e.score.toLocaleString()} points</p>
          </article>
        ))}
      </section>
      <LeaderboardPanel engagementId={process.env.NEXT_PUBLIC_ENGAGEMENT_ID!} code="top_scorers" />
    </main>
  );
}

"use client";
import { useEffect, useState } from "react";

export function MyRankChip({
  code,
  participantId,
}: {
  code: string;
  participantId: string;
}) {
  const [rank, setRank] = useState<{ rank: number; percentile: number } | null>(null);

  useEffect(() => {
    async function load() {
      const res = await fetch(
        `/api/bricqs/leaderboards/${code}/rank/${participantId}`
        // server-side proxy so the API key stays off the client
      );
      setRank(await res.json());
    }
    load();
  }, [code, participantId]);

  if (!rank) return null;
  return (
    <span className="inline-flex items-center gap-1 rounded-full bg-amber-50 px-2 py-0.5 text-xs">
      Rank #{rank.rank} (top {(100 - rank.percentile).toFixed(1)}%)
    </span>
  );
}

"use client";
import { useEffect, useRef } from "react";
import { useLeaderboard } from "@bricqs/sdk-react";

export function PeriodRolloverBanner({ engagementId, code }: { engagementId: string; code: string }) {
  const { entries } = useLeaderboard({ engagementId, code });
  const lastSeenKey = useRef<string | null>(null);

  useEffect(() => {
    // The hook surfaces period_key on each entry; pick it from the first
    const currentKey = (entries[0] as any)?.period_key ?? null;
    if (currentKey && lastSeenKey.current && currentKey !== lastSeenKey.current) {
      // Period rolled over; show a one-time banner
      showToast("A new week starts now. Your rank resets.");
    }
    lastSeenKey.current = currentKey;
  }, [entries]);

  return null;
}

await fetch("https://api.bricqs.com/api/v1/gamify/leaderboards", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRICQS_ADMIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    code: "top_scorers_may_2026_cohort",
    name: "Top Scorers (May 2026 cohort)",
    metric: "points_balance",
    default_period: "monthly",
    segment: { signup_month: "2026-05" },  // only participants who signed up in May
  }),
});