Log evidence (14:00-14:02 UTC, 2026-04-28)
+ +``` +14:00:30 Model opencode-go/mimo-v2.5-pro failed, trying next (429) +14:00:31 Trying model 2/5: opencode-go/kimi-k2.6 +14:01:18 Model opencode-go/kimi-k2.6 failed, trying next (429) +14:01:18 Trying model 3/5: opencode-go/qwen3.6-plus +14:02:10 Model opencode-go/qwen3.6-plus succeeded (146978ms, 1 fallbacks) +``` + +All accounts returned 429 "Subscription quota exceeded" for each model in sequence. Total cascade: ~2 minutes before a working path was found. + +Additional evidence: overnight harness (2026-04-29)
+ +``` +03:40:50 429 mimo-v2.5-pro "Subscription quota exceeded" +03:40:56 429 mimo-v2.5-pro "Subscription quota exceeded" +03:51:03 429 mimo-v2.5-pro "Subscription quota exceeded" +03:51:09 429 mimo-v2.5-pro "Subscription quota exceeded" +03:51:15 429 mimo-v2.5-pro "Subscription quota exceeded" +... +06:48:39 429 mimo-v2.5-pro "Subscription quota exceeded" +``` + +All 429s are from the same provider. The combo never reached the cross-provider fallback (glm). Every request cycled through all 3 accounts × all opencode-go targets before giving up. + +
+
+
+---
+
+## Streak Tracker
+
+**File:** `src/lib/gamification/streaks.ts`
+
+### Data Model
+
+Streaks are stored in the `key_value` table (shared utility table) under
+namespaced keys:
+
+| Key | Value | Description |
+| ----------------------------- | -------------------------------- | ------------------ |
+| `gamification:streak:{keyId}` | `{current},{longest},{lastDate}` | Active streak data |
+
+### Logic
+
+```typescript
+export async function updateStreak(
+ apiKeyId: string
+): Promise<{ current: number; longest: number; milestone: boolean }>;
+```
+
+1. Read streak record from `key_value`.
+2. Parse `{current}`, `{longest}`, `{lastDate}` (ISO date string).
+3. If `lastDate === today` — no change (already counted today).
+4. If `lastDate === yesterday` — increment `current`; update `longest` if needed.
+5. If `lastDate < yesterday` — reset `current = 1` (streak broken).
+6. Write updated record.
+7. Check milestones: 7, 14, 30, 60, 90, 180, 365 days. If crossed, set
+ `milestone = true` (caller awards XP and checks badges).
+
+### Edge Cases
+
+- **Timezone**: streaks use UTC dates (`new Date().toISOString().slice(0, 10)`).
+ This is intentional — a single canonical timezone prevents gaming via
+ timezone hopping.
+- **New users**: no streak record exists; first request creates it with
+ `current=1, longest=1, lastDate=today`.
+- **Multiple requests per day**: only the first request of the UTC day
+ increments the streak.
+
+---
+
+## Leaderboard
+
+**File:** `src/lib/gamification/leaderboard.ts`
+
+### Scopes
+
+| Scope | Period | Description |
+| --------------- | ------- | --------------------------------------------- |
+| `global` | `all` | All-time cumulative XP |
+| `weekly` | `week` | XP earned in current UTC week (Mon-Sun) |
+| `monthly` | `month` | XP earned in current UTC month |
+| `tokens_shared` | `all` | Total tokens transferred to others |
+| `contributions` | `all` | Combos created + providers used + skills used |
+
+### Rank Computation
+
+Ranks are **computed at read time**, not stored. This avoids stale rank data
+and eliminates the need for periodic rank recalculation jobs.
+
+```typescript
+export async function getLeaderboard(
+ scope: LeaderboardScope,
+ period: string,
+ limit: number,
+ offset: number
+): Promise<{ entries: LeaderboardEntry[]; total: number }>;
+```
+
+Query pattern:
+
+```sql
+SELECT api_key_id, score,
+ RANK() OVER (ORDER BY score DESC) as rank
+FROM leaderboard
+WHERE scope = ? AND period = ?
+ORDER BY score DESC
+LIMIT ? OFFSET ?
+```
+
+### Period Rotation
+
+Weekly and monthly leaderboards rotate automatically:
+
+1. **Archive**: at period boundary, copy current entries to
+ `leaderboard_archive` with the period label.
+2. **Reset**: delete entries for the expired period.
+3. **Trigger**: checked on every `updateLeaderboard()` call; the first request
+ of a new period triggers the rotation.
+
+This ensures weekly boards reset every Monday 00:00 UTC and monthly boards
+reset on the 1st of each month.
+
+### SSE Real-Time Updates
+
+**Endpoint:** `GET /api/gamification/stream`
+
+```
+Client → GET /api/gamification/stream
+ → SSE connection established
+ → Server sends top-10 leaderboard snapshot immediately
+ → Every 5 seconds: push updated top-10 if changed
+ → Every 15 seconds: heartbeat comment (": heartbeat\n\n")
+ → Client disconnects → cleanup (remove listener)
+```
+
+Event format:
+
+```
+event: leaderboard
+data: {"scope":"global","entries":[...]}
+
+event: leaderboard
+data: {"scope":"weekly","entries":[...]}
+
+: heartbeat
+```
+
+The SSE manager tracks connected clients per scope and only sends updates
+when the leaderboard data has actually changed since the last push.
+
+---
+
+## Token Sharing
+
+**File:** `src/lib/gamification/sharing.ts`
+
+### Double-Entry Ledger
+
+Every transfer creates two rows in `token_ledger`:
+
+| Row | `from_key_id` | `to_key_id` | `amount` |
+| ------ | ------------- | ----------- | -------- |
+| Debit | sender | receiver | +amount |
+| Credit | receiver | sender | -amount |
+
+Wait — the convention is:
+
+| Row | `from_key_id` | `to_key_id` | `amount` | Meaning |
+| ------- | ------------- | ----------- | -------- | ------------------- |
+| Send | sender | receiver | +amount | Outflow from sender |
+| Receive | receiver | sender | +amount | Inflow to receiver |
+
+Balance is computed as:
+
+```sql
+SELECT
+ COALESCE(SUM(CASE WHEN to_key_id = ? THEN amount ELSE 0 END), 0)
+ - COALESCE(SUM(CASE WHEN from_key_id = ? THEN amount ELSE 0 END), 0)
+ AS balance
+FROM token_ledger
+WHERE from_key_id = ? OR to_key_id = ?
+```
+
+### Transfer Flow
+
+```typescript
+export async function transferTokens(
+ fromKeyId: string,
+ toKeyId: string,
+ amount: number,
+ idempotencyKey: string
+): Promise<{ success: boolean; balance: number }>;
+```
+
+1. **Validate**: `amount > 0`, `fromKeyId !== toKeyId`.
+2. **Idempotency**: check if `idempotency_key` already exists in ledger.
+ If yes, return cached result.
+3. **Transaction** (single SQLite transaction):
+ a. Compute sender balance.
+ b. If `balance < amount`, abort (insufficient funds).
+ c. Insert send row (`from=sender, to=receiver, amount`).
+ d. Insert receive row (`from=receiver, to=sender, amount`).
+4. **Rate limit**: check transfer rate for sender (max 10 transfers/min).
+5. **Event**: emit `token_share` gamification event for XP + badge evaluation.
+6. Return `{ success: true, balance: newBalance }`.
+
+### Rate Limiting
+
+- Max 10 transfers per minute per API key.
+- Max 10,000 tokens per single transfer.
+- Max 100,000 tokens transferred per day per API key.
+
+---
+
+## Invite & Redeem Tokens
+
+**File:** `src/lib/gamification/invites.ts`
+
+### Code Format
+
+- **Code**: 8-character alphanumeric (e.g., `A3K9-X7M2`), human-readable,
+ displayed to the user.
+- **Token**: 32-byte random token, stored as SHA-256 hash. Used for
+ programmatic redemption (e.g., URL links).
+
+### Storage
+
+| Column | Value |
+| ------------ | ---------------------------- |
+| `code` | `A3K9X7M2` (unique, indexed) |
+| `token_hash` | SHA-256(raw_token) |
+
+The raw token is returned to the user exactly once at creation time. OmniRoute
+never stores or displays it again — only the hash persists.
+
+### Self-Referral Prevention
+
+When a user redeems a code, the system checks:
+
+1. The code belongs to a different `api_key_id`.
+2. The redeeming user has not previously redeemed any code from the same
+ referrer (joins on `invite_tokens` + redemption log).
+
+If either check fails, the redemption is rejected with a clear error message.
+
+### Expiry & Limits
+
+- Default `max_uses`: 10 (configurable at creation).
+- Default `expires_at`: 30 days from creation.
+- Expired or exhausted codes return HTTP 410 Gone.
+
+---
+
+## Community Server Federation
+
+**File:** `src/lib/gamification/servers.ts`
+
+### Connect
+
+A community server is registered via an invite token issued by the remote
+server. The local instance:
+
+1. Receives the invite token (e.g., pasted into dashboard).
+2. Calls `POST /api/gamification/federation/leaderboard` on the remote server
+ to validate the token and fetch the current leaderboard.
+3. Stores the server record with `status: connected`.
+
+### Sync Model
+
+Federation uses **overwrite sync**, not additive:
+
+```
+Local Instance Community Server
+ │ │
+ ├── push score ───────────────►│ POST /federation/score
+ │ { api_key_id, score } │ (server validates token hash)
+ │ │
+ ├── pull leaderboard ─────────►│ GET /federation/leaderboard
+ │◄── top-N entries ────────────┤ (overwrites local cache)
+ │ │
+ └── health check ─────────────►│ GET /federation/health
+ (every 60s, timeout 5s) │
+```
+
+### Auth
+
+Federation requests include:
+
+```
+Authorization: Bearer Full badge list
+ +| Badge | Category | Rarity | Criteria | +| ------------------- | ------------ | --------- | ---------------------------- | +| First Steps | usage | common | 1 request | +| Getting Warmed Up | usage | common | 100 requests | +| Power User | usage | uncommon | 1,000 requests | +| Centurion | usage | rare | 10,000 requests | +| OmniPower | usage | legendary | 100,000 requests | +| Provider Hopper | contribution | common | Use 5 different providers | +| Provider Master | contribution | uncommon | Use 20 different providers | +| Combo Architect | contribution | uncommon | Create 5 combos | +| Combo Grandmaster | contribution | rare | Create 25 combos | +| First Share | sharing | common | 1 token transfer | +| Generous | sharing | uncommon | 10 token transfers | +| Philanthropist | sharing | rare | Transfer 10,000 tokens total | +| Referrer | sharing | common | 1 successful referral | +| Network Builder | sharing | uncommon | 10 successful referrals | +| Week Warrior | streak | uncommon | 7-day streak | +| Monthly Devoted | streak | rare | 30-day streak | +| Unstoppable | streak | legendary | 365-day streak | +| Early Adopter | rare | legendary | Join during beta period | +| Compression Pioneer | rare | uncommon | Use compression 100 times | +| Skill Collector | rare | rare | Use 10 different skills | +| Model Explorer | contribution | uncommon | Use 15 different models | + +
+ {toasts.map((toast, i) => (
+
+ );
+}
diff --git a/src/app/(dashboard)/dashboard/gamification/admin/page.tsx b/src/app/(dashboard)/dashboard/gamification/admin/page.tsx
new file mode 100644
index 0000000000..dbb7cbb08e
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/gamification/admin/page.tsx
@@ -0,0 +1,77 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card } from "@/shared/components";
+
+interface Anomaly {
+ apiKeyId: string;
+ xpLastHour: number;
+ zScore: number;
+}
+
+export default function GamificationAdminPage() {
+ const [anomalies, setAnomalies] = useState
+ 🏆
+
+ ))}
+
+
+ Badge Unlocked!
+ {toast.badgeName}
+
+
+
+
+ );
+}
diff --git a/src/app/(dashboard)/dashboard/leaderboard/page.tsx b/src/app/(dashboard)/dashboard/leaderboard/page.tsx
new file mode 100644
index 0000000000..08d3884809
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/leaderboard/page.tsx
@@ -0,0 +1,200 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { Card } from "@/shared/components";
+
+type LeaderboardScope = "global" | "weekly" | "monthly" | "tokens_shared";
+
+interface LeaderboardEntry {
+ apiKeyId: string;
+ score: number;
+}
+
+const SCOPE_LABELS: Record
+
+
+ Gamification Admin
+Monitor anomalies and system health
+Flagged Anomalies
+ {loading ? ( +Loading...
+ ) : anomalies.length === 0 ? (
+ No anomalies detected
+ ) : (
+
+
+
+
+
+ )}
+ | API Key | +XP (1h) | +Z-Score | +Status | +
|---|---|---|---|
| {a.apiKeyId.slice(0, 16)}... | +{a.xpLastHour.toLocaleString()} | +{a.zScore.toFixed(2)} | ++ + Suspicious + + | +
+ {/* Scope selector */}
+
+
+ )}
+
+ {error &&
+
+ )}
+
+ {entries.length === 0 && !error && (
+
+
+ )}
+
+ )}
+
+ );
+}
diff --git a/src/app/(dashboard)/dashboard/profile/page.tsx b/src/app/(dashboard)/dashboard/profile/page.tsx
new file mode 100644
index 0000000000..10ed9dd0d3
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/profile/page.tsx
@@ -0,0 +1,299 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { Card, Badge } from "@/shared/components";
+import {
+ xpForLevel,
+ calculateLevel,
+ cumulativeXpForLevel,
+ getLevelTier,
+ getLevelTitle,
+} from "@/lib/gamification/xp";
+
+interface UserLevel {
+ apiKeyId: string;
+ totalXp: number;
+ currentLevel: number;
+ updatedAt: string;
+}
+
+interface BadgeDef {
+ id: string;
+ name: string;
+ description: string | null;
+ icon: string | null;
+ category: string | null;
+ rarity: string;
+ criteria: string | null;
+ hidden: number;
+ createdAt: string;
+}
+
+interface UserBadge {
+ apiKeyId: string;
+ badgeId: string;
+ unlockedAt: string;
+ badgeName?: string;
+ badgeDescription?: string | null;
+ badgeIcon?: string | null;
+ badgeCategory?: string | null;
+ badgeRarity?: string;
+}
+
+const TIER_CONFIG: Record
+ {(Object.keys(SCOPE_LABELS) as LeaderboardScope[]).map((s) => (
+
+ ))}
+
+
+ {/* Your Rank */}
+ {myRank !== null && (
+
+
+
+
+ Your Rank
+#{myRank}
+
+
+ Scope
+{SCOPE_LABELS[scope]}
+{error}
}
+
+ {loading ? (
+
+
+ ) : (
+ <>
+ {/* Podium — Top 3 */}
+ {top3.length > 0 && (
+ Loading leaderboard...
+
+ {top3.map((entry, idx) => (
+
+
+
+ ))}
+
+ )}
+
+ {/* Rest of leaderboard table */}
+ {rest.length > 0 && (
+
+
+ {MEDAL_EMOJI[idx]}
+
+
+ + {entry.apiKeyId.slice(0, 8)}... +
+{entry.score.toLocaleString()}
++ {scope === "tokens_shared" ? "tokens shared" : "points"} +
+{idx + 1}
+
+
+
+
+
+ | Rank | +Name | +Score | +
|---|---|---|
| {idx + 4} | +{entry.apiKeyId.slice(0, 12)}... | ++ {entry.score.toLocaleString()} + | +
+ No entries yet for this scope. Start using OmniRoute to earn points!
+
+
+
+ );
+ }
+
+ const level = userLevel?.currentLevel ?? 1;
+ const totalXp = userLevel?.totalXp ?? 0;
+ const currentLevelCumulative = cumulativeXpForLevel(level);
+ const nextLevelCumulative = cumulativeXpForLevel(level + 1);
+ const xpInCurrentLevel = totalXp - currentLevelCumulative;
+ const xpForNext = nextLevelCumulative - currentLevelCumulative;
+ const xpProgress = xpForNext > 0 ? (xpInCurrentLevel / xpForNext) * 100 : 0;
+ const tier = getLevelTier(level);
+ const tierConfig = TIER_CONFIG[tier] || TIER_CONFIG.bronze;
+ const earnedIds = new Set(earnedBadges.map((b) => b.badgeId));
+
+ return (
+ Loading profile...
+
+ {/* Level & XP Card */}
+
+
+
+ {/* Streak display */}
+ {streak > 0 && (
+
+
+ )}
+
+ {/* Badges Grid */}
+
+ );
+}
diff --git a/src/app/(dashboard)/dashboard/tokens/page.tsx b/src/app/(dashboard)/dashboard/tokens/page.tsx
new file mode 100644
index 0000000000..b369ae21b6
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/tokens/page.tsx
@@ -0,0 +1,554 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { Card } from "@/shared/components";
+
+interface TokenLedgerEntry {
+ id: number;
+ fromApiKeyId: string;
+ toApiKeyId: string;
+ amount: number;
+ reason: string | null;
+ idempotencyKey: string | null;
+ createdAt: string;
+}
+
+interface InviteItem {
+ id: string;
+ code: string;
+ serverUrl: string | null;
+ maxUses: number;
+ useCount: number;
+ expiresAt: string | null;
+ revokedAt: string | null;
+ createdAt: string;
+}
+
+interface ServerConnection {
+ id: string;
+ name: string;
+ url: string;
+ status: string;
+ lastSyncAt: string | null;
+ errorMessage: string | null;
+}
+
+export default function TokensPage() {
+ // Balance & History
+ const [balance, setBalance] = useState(0);
+ const [history, setHistory] = useState
+
+
+
+
+
+ {level}
+
+
+
+ {getLevelTitle(level)}
+
+
+ {tierConfig.label} Tier
+
+ {streak > 0 && (
+
+ 🔥 {streak} day streak
+
+ )}
+
+
+
+
+
+ Level {level} → {level + 1}
+
+
+ {xpInCurrentLevel.toLocaleString()} / {xpForNext.toLocaleString()} XP
+
+
+
+
+
+ + {totalXp.toLocaleString()} total XP earned +
+
+
+ 🔥
+
+
+ {streak} Day Streak
++ Keep using OmniRoute daily to maintain your streak! +
+
+
+
+ ) : (
+
+
+ {/* Badge Detail Modal */}
+ {selectedBadge && (
+ + Badges ({earnedBadges.length} / {allBadges.length}) +
+ + {allBadges.length === 0 ? ( +
+ No badges available yet. Keep using OmniRoute to unlock achievements!
+
+
+ {allBadges.map((badge) => {
+ const isEarned = earnedIds.has(badge.id);
+ const earnedInfo = earnedBadges.find((b) => b.badgeId === badge.id);
+ const rarityColor = RARITY_COLORS[badge.rarity] || RARITY_COLORS.common;
+
+ return (
+
+ );
+ })}
+
+ )}
+
+
+ )}
+
+
+
+
+
+ {selectedBadge.description && (
+
+ {selectedBadge.icon || "🏅"}
+
+
+
+
+ {selectedBadge.name}
+ + {selectedBadge.rarity} + +{selectedBadge.description}
+ )} + + {selectedBadge.category && ( ++ Category: {selectedBadge.category} +
+ )} + + {selectedBadge.criteria && ( +
+
+ )}
+
+ {earnedIds.has(selectedBadge.id) && (
+ How to earn
+{selectedBadge.criteria}
+
+ ✓ Earned on{" "}
+ {new Date(
+ earnedBadges.find((b) => b.badgeId === selectedBadge.id)?.unlockedAt || ""
+ ).toLocaleDateString()}
+
+ )}
+
+
+
+
+
+ {/* Balance */}
+
+
+
+ {/* Transfer Form */}
+
+
+
+
+ {/* Transaction History */}
+
+ {historyLoading ? (
+
+
+ {/* Invite Panel */}
+
+
+
+ {/* Server Panel */}
+
+
+
+ );
+}
diff --git a/src/app/api/gamification/anomalies/route.ts b/src/app/api/gamification/anomalies/route.ts
new file mode 100644
index 0000000000..79c2144be3
--- /dev/null
+++ b/src/app/api/gamification/anomalies/route.ts
@@ -0,0 +1,19 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CORS_HEADERS, handleCorsOptions } from "@/shared/utils/cors";
+import { getAnomalies } from "@/lib/gamification/antiCheat";
+import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
+
+export async function OPTIONS() {
+ return handleCorsOptions();
+}
+
+/**
+ * GET /api/gamification/anomalies — Admin anomaly list
+ */
+export async function GET(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ const anomalies = await getAnomalies();
+ return NextResponse.json({ anomalies }, { headers: CORS_HEADERS });
+}
diff --git a/src/app/api/gamification/federation/leaderboard/route.ts b/src/app/api/gamification/federation/leaderboard/route.ts
new file mode 100644
index 0000000000..d65da53496
--- /dev/null
+++ b/src/app/api/gamification/federation/leaderboard/route.ts
@@ -0,0 +1,28 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CORS_HEADERS, handleCorsOptions } from "@/shared/utils/cors";
+import { type LeaderboardScope, getTopN } from "@/lib/gamification/leaderboard";
+
+export async function OPTIONS() {
+ return handleCorsOptions();
+}
+
+/**
+ * GET /api/gamification/federation/leaderboard — Serve leaderboard for federation
+ */
+export async function GET(request: NextRequest) {
+ const url = new URL(request.url);
+ const scope: LeaderboardScope = (url.searchParams.get("scope") || "global") as LeaderboardScope;
+ const limit = Number(url.searchParams.get("limit") || 100);
+
+ const entries = await getTopN(scope, limit);
+
+ return NextResponse.json(
+ {
+ entries: entries.map((e: any) => ({
+ apiKeyId: e.apiKeyId,
+ score: e.score,
+ })),
+ },
+ { headers: CORS_HEADERS }
+ );
+}
diff --git a/src/app/api/gamification/federation/score/route.ts b/src/app/api/gamification/federation/score/route.ts
new file mode 100644
index 0000000000..e72cef5064
--- /dev/null
+++ b/src/app/api/gamification/federation/score/route.ts
@@ -0,0 +1,54 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CORS_HEADERS, handleCorsOptions } from "@/shared/utils/cors";
+import { updateScore } from "@/lib/gamification/leaderboard";
+import { z } from "zod";
+
+export async function OPTIONS() {
+ return handleCorsOptions();
+}
+
+/**
+ * POST /api/gamification/federation/score — Receive score from connected instance
+ */
+export async function POST(request: NextRequest) {
+ const authHeader = request.headers.get("Authorization");
+ if (!authHeader?.startsWith("Bearer ")) {
+ return NextResponse.json(
+ { error: "Missing authorization" },
+ { status: 401, headers: CORS_HEADERS }
+ );
+ }
+
+ // Validate token against connected community servers
+ const token = authHeader.slice(7);
+ const crypto = await import("crypto");
+ const tokenHash = crypto.createHash("sha256").update(token).digest("hex");
+ const { getDbInstance } = await import("@/lib/db/core");
+ const db = getDbInstance();
+ const server = db
+ .prepare("SELECT id FROM community_servers WHERE api_key_hash = ? AND status = 'connected'")
+ .get(tokenHash) as { id: string } | undefined;
+
+ if (!server) {
+ return NextResponse.json(
+ { error: "Invalid or unauthorized token" },
+ { status: 403, headers: CORS_HEADERS }
+ );
+ }
+
+ const body = await request.json();
+ const schema = z.object({
+ apiKeyId: z.string(),
+ score: z.number(),
+ scope: z.enum(["global", "weekly", "monthly"]).default("global"),
+ });
+
+ const parsed = schema.safeParse(body);
+ if (!parsed.success) {
+ return NextResponse.json({ error: "Invalid request" }, { status: 400, headers: CORS_HEADERS });
+ }
+
+ await updateScore(parsed.data.apiKeyId, parsed.data.scope, parsed.data.score);
+
+ return NextResponse.json({ success: true }, { headers: CORS_HEADERS });
+}
diff --git a/src/app/api/gamification/invite/redeem/route.ts b/src/app/api/gamification/invite/redeem/route.ts
new file mode 100644
index 0000000000..80d7fe71c8
--- /dev/null
+++ b/src/app/api/gamification/invite/redeem/route.ts
@@ -0,0 +1,48 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CORS_HEADERS, handleCorsOptions } from "@/shared/utils/cors";
+import { redeemInvite } from "@/lib/gamification/invites";
+import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
+import { z } from "zod";
+
+export async function OPTIONS() {
+ return handleCorsOptions();
+}
+
+export async function POST(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ let body: unknown;
+ try {
+ body = await request.json();
+ } catch {
+ return NextResponse.json(
+ { error: "Invalid JSON body" },
+ { status: 400, headers: CORS_HEADERS }
+ );
+ }
+
+ const schema = z.object({
+ code: z.string().min(1),
+ apiKeyId: z.string().min(1),
+ });
+
+ const parsed = schema.safeParse(body);
+ if (!parsed.success) {
+ return NextResponse.json(
+ { error: "Invalid request", details: parsed.error.issues },
+ { status: 400, headers: CORS_HEADERS }
+ );
+ }
+
+ const result = await redeemInvite(parsed.data.code, parsed.data.apiKeyId);
+
+ if (!result.success) {
+ return NextResponse.json({ error: result.error }, { status: 400, headers: CORS_HEADERS });
+ }
+
+ return NextResponse.json(
+ { success: true, serverUrl: result.serverUrl },
+ { headers: CORS_HEADERS }
+ );
+}
diff --git a/src/app/api/gamification/invite/route.ts b/src/app/api/gamification/invite/route.ts
new file mode 100644
index 0000000000..d1d95e1098
--- /dev/null
+++ b/src/app/api/gamification/invite/route.ts
@@ -0,0 +1,77 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CORS_HEADERS, handleCorsOptions } from "@/shared/utils/cors";
+import { createInvite, listInvites, revokeInvite } from "@/lib/gamification/invites";
+import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
+import { z } from "zod";
+
+export async function OPTIONS() {
+ return handleCorsOptions();
+}
+
+export async function GET(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ const url = new URL(request.url);
+ const apiKeyId = url.searchParams.get("apiKeyId");
+ if (!apiKeyId) {
+ return NextResponse.json(
+ { error: "apiKeyId required" },
+ { status: 400, headers: CORS_HEADERS }
+ );
+ }
+
+ const invites = await listInvites(apiKeyId);
+ return NextResponse.json({ invites }, { headers: CORS_HEADERS });
+}
+
+export async function POST(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ let body: unknown;
+ try {
+ body = await request.json();
+ } catch {
+ return NextResponse.json(
+ { error: "Invalid JSON body" },
+ { status: 400, headers: CORS_HEADERS }
+ );
+ }
+
+ const schema = z.object({
+ apiKeyId: z.string().min(1),
+ serverUrl: z.string().optional(),
+ maxUses: z.number().positive().default(1),
+ });
+
+ const parsed = schema.safeParse(body);
+ if (!parsed.success) {
+ return NextResponse.json(
+ { error: "Invalid request", details: parsed.error.issues },
+ { status: 400, headers: CORS_HEADERS }
+ );
+ }
+
+ const { code, token } = await createInvite(
+ parsed.data.apiKeyId,
+ parsed.data.serverUrl,
+ parsed.data.maxUses
+ );
+
+ return NextResponse.json({ code, token }, { status: 201, headers: CORS_HEADERS });
+}
+
+export async function DELETE(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ const url = new URL(request.url);
+ const inviteId = url.searchParams.get("id");
+ if (!inviteId) {
+ return NextResponse.json({ error: "id required" }, { status: 400, headers: CORS_HEADERS });
+ }
+
+ await revokeInvite(inviteId);
+ return NextResponse.json({ success: true }, { headers: CORS_HEADERS });
+}
diff --git a/src/app/api/gamification/leaderboard/route.ts b/src/app/api/gamification/leaderboard/route.ts
new file mode 100644
index 0000000000..33159af39c
--- /dev/null
+++ b/src/app/api/gamification/leaderboard/route.ts
@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CORS_HEADERS, handleCorsOptions } from "@/shared/utils/cors";
+import {
+ getTopN,
+ getRank,
+ getNeighbors,
+ type LeaderboardScope,
+} from "@/lib/gamification/leaderboard";
+import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
+
+export async function OPTIONS() {
+ return handleCorsOptions();
+}
+
+export async function GET(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ const url = new URL(request.url);
+ const scope = (url.searchParams.get("scope") || "global") as LeaderboardScope;
+ const limit = Number(url.searchParams.get("limit") || 50);
+ const apiKeyId = url.searchParams.get("apiKeyId");
+
+ const entries = await getTopN(scope, Math.min(limit, 200));
+ let myRank: number | null = null;
+ let neighbors = null;
+
+ if (apiKeyId) {
+ myRank = await getRank(apiKeyId, scope);
+ neighbors = await getNeighbors(apiKeyId, scope);
+ }
+
+ return NextResponse.json({ entries, myRank, neighbors }, { headers: CORS_HEADERS });
+}
diff --git a/src/app/api/gamification/notifications/route.ts b/src/app/api/gamification/notifications/route.ts
new file mode 100644
index 0000000000..6c51e9a9b2
--- /dev/null
+++ b/src/app/api/gamification/notifications/route.ts
@@ -0,0 +1,33 @@
+import { NextRequest } from "next/server";
+import { CORS_HEADERS } from "@/shared/utils/cors";
+import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
+import { createBadgeNotificationStream } from "@/lib/gamification/notifications";
+
+/**
+ * GET /api/gamification/notifications?apiKeyId=xxx — SSE badge unlock notifications
+ */
+export async function GET(request: NextRequest) {
+ const authErr = await requireManagementAuth(request);
+ if (authErr) return authErr;
+
+ const url = new URL(request.url);
+ const apiKeyId = url.searchParams.get("apiKeyId");
+
+ if (!apiKeyId) {
+ return new Response(JSON.stringify({ error: "apiKeyId required" }), {
+ status: 400,
+ headers: { ...CORS_HEADERS, "Content-Type": "application/json" },
+ });
+ }
+
+ const stream = createBadgeNotificationStream(apiKeyId, request.signal);
+
+ return new Response(stream, {
+ headers: {
+ ...CORS_HEADERS,
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache",
+ Connection: "keep-alive",
+ },
+ });
+}
diff --git a/src/app/api/gamification/rotate/route.ts b/src/app/api/gamification/rotate/route.ts
new file mode 100644
index 0000000000..ea2bc207e9
--- /dev/null
+++ b/src/app/api/gamification/rotate/route.ts
@@ -0,0 +1,31 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CORS_HEADERS, handleCorsOptions } from "@/shared/utils/cors";
+import { rotateScope } from "@/lib/gamification/leaderboard";
+import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
+import { z } from "zod";
+
+export async function OPTIONS() {
+ return handleCorsOptions();
+}
+
+/**
+ * POST /api/gamification/rotate — Manually trigger leaderboard rotation
+ */
+export async function POST(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ const body = await request.json();
+ const schema = z.object({
+ scope: z.enum(["weekly", "monthly"]),
+ });
+
+ const parsed = schema.safeParse(body);
+ if (!parsed.success) {
+ return NextResponse.json({ error: "Invalid request" }, { status: 400, headers: CORS_HEADERS });
+ }
+
+ await rotateScope(parsed.data.scope);
+
+ return NextResponse.json({ success: true, scope: parsed.data.scope }, { headers: CORS_HEADERS });
+}
diff --git a/src/app/api/gamification/servers/route.ts b/src/app/api/gamification/servers/route.ts
new file mode 100644
index 0000000000..aee3884807
--- /dev/null
+++ b/src/app/api/gamification/servers/route.ts
@@ -0,0 +1,63 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CORS_HEADERS, handleCorsOptions } from "@/shared/utils/cors";
+import { connectServer, disconnectServer, listServers } from "@/lib/gamification/servers";
+import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
+import { z } from "zod";
+
+export async function OPTIONS() {
+ return handleCorsOptions();
+}
+
+/**
+ * GET /api/gamification/servers — List connected servers
+ */
+export async function GET(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ const servers = await listServers();
+ return NextResponse.json({ servers }, { headers: CORS_HEADERS });
+}
+
+/**
+ * POST /api/gamification/servers — Connect to a server
+ */
+export async function POST(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ const body = await request.json();
+ const schema = z.object({
+ name: z.string().min(1),
+ url: z.string().url(),
+ apiKey: z.string().min(1),
+ });
+
+ const parsed = schema.safeParse(body);
+ if (!parsed.success) {
+ return NextResponse.json(
+ { error: "Invalid request", details: parsed.error.issues },
+ { status: 400, headers: CORS_HEADERS }
+ );
+ }
+
+ const server = await connectServer(parsed.data.name, parsed.data.url, parsed.data.apiKey);
+ return NextResponse.json({ server }, { status: 201, headers: CORS_HEADERS });
+}
+
+/**
+ * DELETE /api/gamification/servers — Disconnect from a server
+ */
+export async function DELETE(request: NextRequest) {
+ const authError = await requireManagementAuth(request);
+ if (authError) return authError;
+
+ const url = new URL(request.url);
+ const serverId = url.searchParams.get("id");
+ if (!serverId) {
+ return NextResponse.json({ error: "id required" }, { status: 400, headers: CORS_HEADERS });
+ }
+
+ await disconnectServer(serverId);
+ return NextResponse.json({ success: true }, { headers: CORS_HEADERS });
+}
diff --git a/src/app/api/gamification/stream/route.ts b/src/app/api/gamification/stream/route.ts
new file mode 100644
index 0000000000..c7eb56d155
--- /dev/null
+++ b/src/app/api/gamification/stream/route.ts
@@ -0,0 +1,81 @@
+/**
+ * SSE Leaderboard Stream — /api/gamification/stream
+ *
+ * Pushes live leaderboard updates to connected clients via Server-Sent Events.
+ * Supports all leaderboard scopes (global, weekly, monthly, tokens_shared, contributions).
+ */
+
+import { NextRequest } from "next/server";
+import { type LeaderboardScope, getTopN } from "@/lib/gamification/leaderboard";
+import { CORS_HEADERS } from "@/shared/utils/cors";
+import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
+
+const VALID_SCOPES: ReadonlySet
+
+
+
+ Token Balance
+{balance.toLocaleString()}
+🪙
+ Loading...
+ ) : history.length === 0 ? (
+ No transactions yet
+ ) : (
+
+
+
+
+
+ )}
+ | Type | +From | +To | +Amount | +Reason | +Date | +
|---|---|---|---|---|---|
| + + {isSent ? "Sent" : "Received"} + + | ++ {entry.fromApiKeyId.slice(0, 8)}... + | +{entry.toApiKeyId.slice(0, 8)}... | ++ {isSent ? "-" : "+"} + {entry.amount.toLocaleString()} + | +{entry.reason || "-"} | ++ {new Date(entry.createdAt).toLocaleDateString()} + | +
+
+
+
+
+ {newInviteCode && (
+
+
+ setInviteMaxUses(e.target.value)}
+ min="1"
+ className="w-full px-3 py-2 rounded-lg bg-background border border-border text-sm focus:outline-none focus:ring-1 focus:ring-violet-500"
+ />
+
+
+
+ Invite code created: {newInviteCode}
+
+ )}
+
+ {/* Redeem */}
+
+
+ {redeemMsg && (
+
+ {redeemMsg.text}
+
+ )}
+
+ {/* Active Invites */}
+ {invites.length > 0 && (
+
+
+ )}
+ Your Active Invites
+
+ {invites.map((inv) => (
+
+
+
+ ))}
+
+ {inv.code}
+
+ {inv.useCount}/{inv.maxUses} uses
+
+ {inv.revokedAt && REVOKED}
+
+ {!inv.revokedAt && (
+
+ )}
+
+
+
+ {servers.length === 0 ? (
+
+
+ No servers connected. Connect to a community server to share leaderboards.
+
+ ) : (
+
+ {servers.map((server) => (
+
+ )}
+
+
+ ))}
+
+
+
+
+
+ {server.name}
+ + {server.status} + +{server.url}
+ {server.errorMessage && ( +{server.errorMessage}
+ )} + {server.lastSyncAt && ( ++ Last sync: {new Date(server.lastSyncAt).toLocaleString()} +
+ )} +