Points systems with expiry

curl -X POST https://api.bricqs.com/api/v1/gamify/points/deduct \
  -H "Authorization: Bearer bq_live_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reward:r_99:claim" \
  -d '{
    "participant_id": "user_42",
    "amount": 50,
    "reason": "Redeemed free coffee"
  }'

# Response (200 OK)
{
  "transaction_id": "txn_b3c4d5e6-...",
  "participant_id": "user_42",
  "amount": -50,
  "new_balance": 1050
}

# Insufficient balance returns 400 with the structured envelope:
{
  "error": {
    "type": "insufficient_balance",
    "code": "INSUFFICIENT_POINTS",
    "message": "Insufficient points. Available: 30, requested: 50.",
    "details": { "available": 30, "requested": 50 },
    "request_id": "req_abc123..."
  }
}

# Current balance
curl https://api.bricqs.com/api/v1/gamify/participants/user_42/points \
  -H "Authorization: Bearer bq_live_xxxxx"

# Response (200 OK)
{
  "participant_id": "user_42",
  "balance": 1050,        // spendable
  "total_earned": 1750,   // lifetime, NEVER decrements
  "total_spent": 700      // lifetime spent (excludes expiry)
}

# Transaction history (paginated)
curl "https://api.bricqs.com/api/v1/gamify/participants/user_42/points/transactions?page=1&page_size=50" \
  -H "Authorization: Bearer bq_live_xxxxx"

# Response includes every ledger row, including points_expiry counter-debits.

curl -X POST https://api.bricqs.com/api/v1/gamify/points/award-batch \
  -H "Authorization: Bearer bq_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "awards": [
      { "participant_id": "user_42", "amount": 100, "idempotency_key": "monthly_2026_05:42" },
      { "participant_id": "user_43", "amount": 100, "idempotency_key": "monthly_2026_05:43" }
    ]
  }'

# Response (200 OK)
{
  "processed": 2,
  "failed": 0,
  "results": [
    { "participant_id": "user_42", "transaction_id": "txn_...", "new_balance": 1150 },
    { "participant_id": "user_43", "transaction_id": "txn_...", "new_balance": 350 }
  ]
}

export async function POST(req: Request) {
  const order = await verifyAndParse(req); // your signature check

  const pointsEarned = Math.floor(order.total / 10); // 1 pt per $0.10
  if (pointsEarned === 0) return new Response(null, { status: 200 });

  await fetch("https://api.bricqs.com/api/v1/gamify/points/award", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BRICQS_API_KEY}`,
      "Content-Type": "application/json",
      // Derived from the order id, same order, same key, idempotent.
      "Idempotency-Key": `order:${order.id}:loyalty_award`,
    },
    body: JSON.stringify({
      participant_id: order.customer_id,
      amount: pointsEarned,
      reason: `Order #${order.number}`,
      metadata: { order_id: order.id, order_total: order.total },
    }),
  });

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

function ninetyDaysFromNow(): string {
  const d = new Date();
  d.setUTCDate(d.getUTCDate() + 90);
  return d.toISOString();
}

await fetch("https://api.bricqs.com/api/v1/gamify/points/award", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order:${order.id}:loyalty_award`,
  },
  body: JSON.stringify({
    participant_id: order.customer_id,
    amount: pointsEarned,
    expires_at: ninetyDaysFromNow(),  // ← the FIFO bit
    reason: `Order #${order.number} (90-day expiry)`,
  }),
});

curl -X POST https://api.bricqs.com/api/v1/gamify/rewards/r_99/claim \
  -H "Authorization: Bearer bq_live_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: redeem:user_42:r_99:2026-05-23" \
  -d '{
    "participant_id": "user_42",
    "points_deduction": true       // ← atomic deduct + claim
  }'

# Response (200 OK)
{
  "claim_id": "clm_...",
  "participant_id": "user_42",
  "reward_name": "Free Coffee",
  "reward_type": "coupon",
  "code_value": "COFFEE-A7B2C1",
  "expires_at": "2026-08-23T00:00:00Z",
  "points_deducted": 50,
  "new_balance": 1000
}

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

// The SDK hook surfaces balance + totalEarned + currentTier. For the
// lifetime-spent number, hit the REST endpoint directly, it returns
// total_spent (lifetime debits caused by redemption) alongside balance
// and total_earned. Compute the "expired" bucket as the residual.
export function PointsBalanceCard({
  engagementId,
  participantId,
  apiBase,
  apiKey,
}: {
  engagementId: string;
  participantId: string;
  apiBase: string;
  apiKey: string;
}) {
  const { balance, totalEarned } = usePoints({ engagementId });
  const [totalSpent, setTotalSpent] = useState(0);

  useEffect(() => {
    fetch(`${apiBase}/api/v1/gamify/participants/${participantId}/points`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    })
      .then((r) => r.json())
      .then((d) => setTotalSpent(d.total_spent ?? 0));
  }, [apiBase, apiKey, participantId]);

  const expired = Math.max(0, totalEarned - balance - totalSpent);

  return (
    <div className="rounded-2xl border p-6 space-y-3">
      <div>
        <div className="text-4xl font-extrabold tabular-nums">{balance}</div>
        <div className="text-sm text-slate-500">Spendable points</div>
      </div>
      <dl className="grid grid-cols-3 gap-3 text-xs text-slate-500 pt-3 border-t">
        <div>
          <dt className="font-semibold">Lifetime earned</dt>
          <dd className="tabular-nums">{totalEarned}</dd>
        </div>
        <div>
          <dt className="font-semibold">Spent on rewards</dt>
          <dd className="tabular-nums">{totalSpent}</dd>
        </div>
        <div title="Points that passed their expiry without being spent">
          <dt className="font-semibold">Expired</dt>
          <dd className="tabular-nums">{expired}</dd>
        </div>
      </dl>
    </div>
  );
}

# 1. Mint (from the dashboard, or via POST /api-keys?mode=test)
#    The test environment is provisioned automatically on first mint.

# 2. Use the test key in your test environment
export BRICQS_API_KEY=bq_test_xxxxx

# 3. Wipe test data between integration runs
curl -X POST https://api.bricqs.com/api/v1/admin/test-tenant/reset \
  -H "Authorization: Bearer bq_live_xxxxx_admin"

# Reset wipes participant data: balances, transactions, claims,
# activity history. Definitions (badges, tiers, rewards) and the
# test API key are preserved so you do not have to re-seed.