Badges in headless gamification

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

# Optional query params:
#   ?earned_only=true                 -> only return earned badges
#   ?badge_codes=first_quiz,power_user -> filter to specific codes

# Response (200 OK)
{
  "participant_id": "user_42",
  "total": 12,                  // total badges defined
  "earned_count": 3,            // how many this user has earned
  "badges": [
    {
      "code": "first_quiz",
      "name": "First Quiz",
      "icon": "https://cdn.example.com/badges/first-quiz.png",
      "rarity": "common",
      "category": "onboarding",
      "earned": true,
      "earned_at": "2026-05-20T11:42:00Z"
    },
    {
      "code": "power_user",
      "name": "Power User",
      "icon": "https://cdn.example.com/badges/power-user.png",
      "rarity": "epic",
      "category": "loyalty",
      "earned": false,
      "earned_at": null
    }
    // ...
  ]
}

# List all badge definitions
GET    /api/v1/gamify/badges

# Get one
GET    /api/v1/gamify/badges/{badge_id}

# Create
POST   /api/v1/gamify/badges
       { "code": "first_quiz", "name": "First Quiz", "rarity": "common", ... }

# Update
PATCH  /api/v1/gamify/badges/{badge_id}
       { "name": "Quiz Beginner" }   // partial update

# Delete (soft-delete: existing awards are preserved)
DELETE /api/v1/gamify/badges/{badge_id}

curl -X POST https://api.bricqs.com/api/v1/rules \
  -H "Authorization: Bearer bq_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Award first_quiz badge on passing quiz",
    "trigger_event": "behavior.quiz_completed.v1",
    "conditions": [
      { "field": "properties.score", "op": "gte", "value": 70 }
    ],
    "actions": [
      {
        "type": "unlock_badge",
        "config": { "badge_code": "first_quiz" }
      }
    ]
  }'

# Rules can also be created and edited from the dashboard UI.

curl -X POST https://api.bricqs.com/api/v1/progression/milestones \
  -H "Authorization: Bearer bq_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ten_referrals",
    "name": "10 Successful Referrals",
    "metric_type": "referral_count",
    "threshold": 10,
    "scope": "global"
  }'

# When the participant hits 10 referrals, the milestone emits:
#   progression.milestone_reached.v1
#   payload includes milestone_code, current_value, threshold

// Step 2: your webhook handler subscribed to progression.milestone_reached.v1
export async function POST(req: Request) {
  const event = await verifyAndParse(req); // your signature check

  // Filter to just the milestone we care about
  if (event.payload.milestone_code !== "ten_referrals") {
    return new Response(null, { status: 200 });
  }

  await fetch("https://api.bricqs.com/api/v1/gamify/badges/award", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BRICQS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      participant_id: event.participant_id,
      badge_code: "referral_champion",
    }),
  });

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

// In your order webhook handler
await fetch("https://api.bricqs.com/api/v1/gamify/badges/award", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRICQS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    participant_id: order.user_id,
    badge_code: "first_order",
    metadata: { order_id: order.id, order_value: order.total },
  }),
});

// Retries are safe by default. Badge awards are idempotent on the
// composite of (participant_id, badge_code). A second POST returns
// the original award with already_earned: true; nothing is recorded
// twice and earned_at preserves the first award's timestamp.

"use client";
import { useEffect, useRef } from "react";
import { useBadgesHeadless } from "@bricqs/sdk-react";
import { celebrateBadge } from "./celebrate";

export function SurpriseBadgeWatcher({ engagementId }: { engagementId: string }) {
  const { earned } = useBadgesHeadless({ engagementId });
  const seen = useRef(new Set<string>());

  useEffect(() => {
    for (const b of earned) {
      if (seen.current.has(b.code)) continue;
      seen.current.add(b.code);
      // Only celebrate if this is a fresh award (not an initial-load hydration).
      if (b.earned_at && Date.now() - new Date(b.earned_at).getTime() < 5000) {
        celebrateBadge(b);
      }
    }
  }, [earned]);

  return null;
}

const RARITY_STYLES: Record<string, string> = {
  common:    "border-slate-200",
  uncommon:  "border-emerald-300",
  rare:      "border-blue-400 shadow-blue-100 shadow-md",
  epic:      "border-purple-500 shadow-purple-200 shadow-lg",
  legendary: "border-amber-400 shadow-amber-200 shadow-xl animate-pulse-slow",
};

export function BadgeChip({ badge }: { badge: Badge }) {
  return (
    <div className={`rounded-xl border-2 p-3 ${RARITY_STYLES[badge.rarity]}`}>
      <img src={badge.icon} alt={badge.name} className="w-10 h-10" />
      <div className="text-sm font-semibold mt-2">{badge.name}</div>
    </div>
  );
}