Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
/**
* Characterization — src/lib/gamification (rail 3.8.55, pre-v4 extraction to @omniroute/mod-*).
*
* Pins the PUBLIC surface and the observable behaviour (XP curve, levels/tiers, the award
* pipeline's points + badges for a fixed fixture, streaks, anti-cheat, sharing, invites,
* servers) as it is today, so the v4 extraction can be proven byte-for-byte. Quirks are pinned,
* not fixed — their names start with "characterization: … currently …". Surface snapshots are
* literal lists: update them consciously, never by regeneration.
*
* External consumers (the real boundary): open-sse/handlers/chatCore/gamificationEvent.ts and
* src/lib/radar/intelSync.ts (emitGamificationEvent), open-sse/mcp-server/tools/
* gamificationTools.ts (leaderboard/xp/streaks/sharing/invites/servers/antiCheat),
* src/app/api/gamification/** and the dashboard profile page (xp helpers). Note: every
* consumer imports the individual modules — none imports the index.ts barrel.
*/
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-char-gamification-"));
process.env.DATA_DIR = TEST_DATA_DIR;
const core = await import("../../src/lib/db/core.ts");
const gamificationDb = await import("../../src/lib/db/gamification.ts");
const MODULES = {
index: await import("../../src/lib/gamification/index.ts"),
antiCheat: await import("../../src/lib/gamification/antiCheat.ts"),
badges: await import("../../src/lib/gamification/badges.ts"),
events: await import("../../src/lib/gamification/events.ts"),
invites: await import("../../src/lib/gamification/invites.ts"),
leaderboard: await import("../../src/lib/gamification/leaderboard.ts"),
notifications: await import("../../src/lib/gamification/notifications.ts"),
servers: await import("../../src/lib/gamification/servers.ts"),
sharing: await import("../../src/lib/gamification/sharing.ts"),
streaks: await import("../../src/lib/gamification/streaks.ts"),
xp: await import("../../src/lib/gamification/xp.ts"),
};
const { antiCheat, badges, events, invites, leaderboard, notifications, servers, sharing } =
MODULES;
const { streaks, xp } = MODULES;
test.after(() => {
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
const todayUtc = () => new Date().toISOString().split("T")[0];
const yesterdayUtc = () => new Date(Date.now() - 86_400_000).toISOString().split("T")[0];
// ─── (a) Surface snapshots ───────────────────────────────────────────────────
test("surface: gamification runtime exports (barrel + every module)", () => {
const surface = Object.fromEntries(
Object.entries(MODULES).map(([name, mod]) => [name, Object.keys(mod).sort()])
);
assert.deepEqual(surface, {
index: [
"BUILTIN_BADGES",
"XP_REWARDS",
"calculateLevel",
"connectServer",
"consumeBadgeUnlocks",
"createBadgeNotificationStream",
"createInvite",
"cumulativeXpForLevel",
"disconnectServer",
"emitGamificationEvent",
"getAggregateStreak",
"getAnomalies",
"getBalance",
"getHistory",
"getLevelTier",
"getLevelTitle",
"getNeighbors",
"getRank",
"getStreak",
"getTopN",
"listServers",
"recordBadgeUnlock",
"redeemInviteCode",
"rotateScope",
"transferTokens",
"updateScore",
"updateStreak",
"validateScoreChange",
"xpForLevel",
"xpToNextLevel",
],
antiCheat: ["getAnomalies", "validateScoreChange"],
badges: ["BUILTIN_BADGES", "evaluateBadges", "seedBuiltinBadges"],
events: ["emitGamificationEvent"],
invites: ["createInvite", "listInvites", "redeemInvite", "revokeInvite"],
leaderboard: ["getNeighbors", "getRank", "getTopN", "rotateScope", "updateScore"],
notifications: ["consumeBadgeUnlocks", "createBadgeNotificationStream", "recordBadgeUnlock"],
servers: [
"connectServer",
"disconnectServer",
"healthCheck",
"listServers",
"pushScore",
"syncLeaderboard",
],
sharing: ["getBalance", "getHistory", "transferTokens"],
streaks: ["advanceStreak", "getAggregateStreak", "getStreak", "updateStreak"],
xp: [
"XP_REWARDS",
"calculateLevel",
"cumulativeXpForLevel",
"getLevelTier",
"getLevelTitle",
"xpForLevel",
"xpToNextLevel",
],
});
// The barrel re-exports the module functions themselves (same references).
assert.equal(MODULES.index.emitGamificationEvent, events.emitGamificationEvent);
assert.equal(MODULES.index.redeemInviteCode, invites.redeemInvite);
});
test("surface: XP_REWARDS table", () => {
assert.deepEqual(xp.XP_REWARDS, {
request: 1,
provider_switch: 5,
model_switch: 3,
combo_create: 10,
combo_use: 2,
token_share: 1,
invite_redeem: 50,
daily_login: 5,
streak_bonus: 2,
badge_unlock: 10,
});
});
test("surface: BUILTIN_BADGES catalogue (id, category, rarity, criteria type, hidden)", () => {
const catalogue = badges.BUILTIN_BADGES.map((b) => [
b.id,
b.category,
b.rarity,
JSON.parse(b.criteria ?? "null")?.type,
b.hidden,
]);
assert.deepEqual(catalogue, [
["first-token", "usage", "common", "action_count", 0],
["token-consumer", "usage", "uncommon", "action_count", 0],
["token-machine", "usage", "rare", "action_count", 0],
["token-whale", "usage", "legendary", "action_count", 0],
["generous", "sharing", "common", "action_count", 0],
["philanthropist", "sharing", "uncommon", "action_count", 0],
["token-santa", "sharing", "rare", "action_count", 0],
["community-hero", "sharing", "legendary", "action_count", 0],
["explorer", "contribution", "uncommon", "unique_count", 0],
["polyglot", "contribution", "rare", "unique_count", 0],
["architect", "contribution", "uncommon", "action_count", 0],
["speedster", "contribution", "rare", "threshold", 0],
["resilient", "contribution", "rare", "threshold", 0],
["radar-supporter", "contribution", "rare", "action_count", 0],
["daily-user", "streak", "common", "streak", 0],
["weekly-warrior", "streak", "uncommon", "streak", 0],
["monthly-master", "streak", "rare", "streak", 0],
["unstoppable", "streak", "legendary", "streak", 0],
["early-adopter", "rare", "legendary", "first", 0],
["bug-hunter", "rare", "rare", "action_count", 0],
["contributor", "rare", "rare", "action_count", 0],
["community-leader", "rare", "rare", "rank", 0],
["secret-badge", "rare", "legendary", "hidden", 1],
]);
});
// ─── (b) Contracts — pure XP / level math ────────────────────────────────────
test("xp: curve, cumulative thresholds and level inversion", () => {
assert.deepEqual(
[1, 2, 3, 10, 50, 100].map((l) => [l, xp.xpForLevel(l), xp.cumulativeXpForLevel(l)]),
[
[1, 0, 0],
[2, 282, 282],
[3, 519, 801],
[10, 3162, 14164],
[50, 35355, 724749],
[100, 100000, 4049979],
]
);
assert.deepEqual(
[0, 281, 282, 283, 800, 5000, 1_000_000, -5].map((v) => [
v,
xp.calculateLevel(v),
xp.xpToNextLevel(v),
]),
[
[0, 1, 282],
[281, 1, 1],
[282, 2, 519],
[283, 2, 518],
[800, 2, 1],
[5000, 6, 1040],
[1_000_000, 56, 2661],
[-5, 1, 287],
]
);
});
test("xp: level titles and tiers at every boundary", () => {
assert.deepEqual(
[0, 10, 11, 25, 26, 50, 51, 75, 76, 1000].map((l) => [
l,
xp.getLevelTitle(l),
xp.getLevelTier(l),
]),
[
[0, "Beginner", "bronze"],
[10, "Beginner", "bronze"],
[11, "Explorer", "silver"],
[25, "Explorer", "silver"],
[26, "Expert", "gold"],
[50, "Expert", "gold"],
[51, "Master", "platinum"],
[75, "Master", "platinum"],
[76, "Legend", "diamond"],
[1000, "Legend", "diamond"],
]
);
});
test("xp: non-finite totals consistently start from level 1 with 282 XP remaining", () => {
assert.equal(xp.calculateLevel(Number.NaN), 1);
assert.equal(xp.calculateLevel(Number.POSITIVE_INFINITY), 1);
assert.equal(xp.xpToNextLevel(Number.NaN), 282);
assert.equal(xp.xpToNextLevel(Number.POSITIVE_INFINITY), 282);
});
// ─── (b) Contracts — award pipeline (deterministic fixture) ──────────────────
test("emitGamificationEvent(request) on a fresh key: 1 XP + first-token badge (+10)", async () => {
await events.emitGamificationEvent({ apiKeyId: "fx-fresh", action: "request" });
const level = gamificationDb.getXp("fx-fresh");
assert.deepEqual([level?.totalXp, level?.currentLevel], [11, 1]);
assert.equal(gamificationDb.hasBadge("fx-fresh", "first-token"), true);
assert.equal(await leaderboard.getRank("fx-fresh", "global"), 1);
const scores = (await leaderboard.getTopN("global")).map((r) => [r.apiKeyId, r.score]);
assert.deepEqual(scores, [["fx-fresh", 11]]);
for (const scope of ["weekly", "monthly"] as const) {
assert.deepEqual(
(await leaderboard.getTopN(scope)).map((r) => [r.apiKeyId, r.score]),
[["fx-fresh", 11]]
);
}
assert.deepEqual(await streaks.getStreak("fx-fresh"), {
currentStreak: 1,
longestStreak: 1,
lastActiveDate: todayUtc(),
streakStartDate: todayUtc(),
});
// Badge toast buffer: definitions are not seeded here, so name falls back to the id.
const toasts = notifications.consumeBadgeUnlocks("fx-fresh");
assert.deepEqual(
toasts.map(({ unlockedAt: _u, ...rest }) => rest),
[
{
badgeId: "first-token",
badgeName: "first-token",
badgeDescription: "",
badgeIcon: "award",
badgeRarity: "common",
},
]
);
assert.deepEqual(notifications.consumeBadgeUnlocks("fx-fresh"), [], "consume drains the buffer");
// A second request the same UTC day: +1 XP, no new badge, no streak bonus.
await events.emitGamificationEvent({ apiKeyId: "fx-fresh", action: "request" });
assert.equal(gamificationDb.getXp("fx-fresh")?.totalXp, 12);
assert.equal((await streaks.getStreak("fx-fresh")).currentStreak, 1);
});
test("emitGamificationEvent(request) extending a 2-day streak: streak bonus 2×3 + daily-user", async () => {
const db = core.getDbInstance();
db.prepare("INSERT OR REPLACE INTO key_value (namespace, key, value) VALUES (?, ?, ?)").run(
"gamification:streaks",
"fx-streak",
JSON.stringify({
currentStreak: 2,
longestStreak: 2,
lastActiveDate: yesterdayUtc(),
streakStartDate: "2000-01-01",
})
);
await events.emitGamificationEvent({ apiKeyId: "fx-streak", action: "request" });
// 1 (request) + 6 (streak_bonus 2×3) + 10 (daily-user) + 10 (first-token) = 27.
assert.equal(gamificationDb.getXp("fx-streak")?.totalXp, 27);
assert.equal(gamificationDb.hasBadge("fx-streak", "daily-user"), true);
assert.equal(gamificationDb.hasBadge("fx-streak", "first-token"), true);
assert.deepEqual(await streaks.getStreak("fx-streak"), {
currentStreak: 3,
longestStreak: 3,
lastActiveDate: todayUtc(),
streakStartDate: "2000-01-01",
});
notifications.consumeBadgeUnlocks("fx-streak");
});
test("emitGamificationEvent(combo_create / radar_supporter): XP-only vs recognition-only", async () => {
await events.emitGamificationEvent({ apiKeyId: "fx-combo", action: "combo_create" });
assert.equal(gamificationDb.getXp("fx-combo")?.totalXp, 10);
assert.equal((await streaks.getStreak("fx-combo")).currentStreak, 0, "only `request` streaks");
await events.emitGamificationEvent({ apiKeyId: "fx-radar", action: "radar_supporter" });
assert.equal(gamificationDb.getXp("fx-radar"), null, "recognition earns no XP");
assert.equal(gamificationDb.hasBadge("fx-radar", "radar-supporter"), true);
assert.equal(await leaderboard.getRank("fx-radar", "global"), 0, "and no leaderboard row");
notifications.consumeBadgeUnlocks("fx-radar");
});
test("characterization: evaluateBadges (no production caller) unlocks first/rank badges", async () => {
await badges.seedBuiltinBadges();
await badges.seedBuiltinBadges(); // idempotent
const count = core
.getDbInstance()
.prepare("SELECT COUNT(*) AS n FROM badge_definitions")
.get() as {
n: number;
};
assert.equal(count.n, 23);
// fx-fresh already holds first-token; it is inside the 30-day window and ranked.
assert.deepEqual(await badges.evaluateBadges("fx-fresh", "request"), [
"early-adopter",
"community-leader",
]);
});
// ─── (c) Errors / invalid input ──────────────────────────────────────────────
test("emitGamificationEvent: empty apiKeyId is a silent no-op", async () => {
const before = (await leaderboard.getTopN("global")).length;
await assert.doesNotReject(events.emitGamificationEvent({ apiKeyId: "", action: "request" }));
assert.equal((await leaderboard.getTopN("global")).length, before);
});
test("emitGamificationEvent: unknown action leaves the leaderboard unchanged", async () => {
await events.emitGamificationEvent({
apiKeyId: "fx-unknown",
action: "not-an-action" as "request",
});
assert.equal(gamificationDb.getXp("fx-unknown"), null);
const row = (await leaderboard.getTopN("global")).find((r) => r.apiKeyId === "fx-unknown");
assert.equal(row, undefined);
});
test("validateScoreChange: >1000 XP/min is rejected with a reason; small awards allowed", async () => {
assert.deepEqual(await antiCheat.validateScoreChange("fx-ac", "request", 1001), {
allowed: false,
reason: "Rate limit exceeded: 1001 > 1000 XP/min",
});
assert.deepEqual(await antiCheat.validateScoreChange("fx-ac", "request", 1), { allowed: true });
assert.ok(Array.isArray(await antiCheat.getAnomalies()));
});
test("transferTokens: validation errors and insufficient balance", async () => {
assert.deepEqual(await sharing.transferTokens("a", "a", 5), {
success: false,
idempotencyKey: "",
error: "Cannot transfer to yourself",
});
assert.deepEqual(await sharing.transferTokens("a", "b", 0), {
success: false,
idempotencyKey: "",
error: "Amount must be positive",
});
const broke = await sharing.transferTokens("a", "b", 5, undefined, "idem-1");
assert.deepEqual(broke, {
success: false,
idempotencyKey: "idem-1",
error: "insufficient_balance",
});
assert.equal(await sharing.getBalance("a"), 0);
assert.deepEqual(await sharing.getHistory("a"), []);
});
test("transferTokens: NaN is rejected before reaching the SQLite ledger", async () => {
const result = await sharing.transferTokens("a", "b", Number.NaN, undefined, "idem-nan");
assert.deepEqual(result, {
success: false,
idempotencyKey: "",
error: "Amount must be positive",
});
});
test("invites: create → redeem rules → revoke", async () => {
const invite = await invites.createInvite("creator", "https://srv.example", 1);
assert.match(invite.code, /^[A-Za-z0-9]{8}$/);
assert.match(invite.token, /^[A-Za-z0-9_-]{43}$/);
assert.deepEqual(await invites.redeemInvite("nope1234", "x"), {
success: false,
error: "Invalid invite code",
});
assert.deepEqual(await invites.redeemInvite(invite.code, "creator"), {
success: false,
error: "Cannot redeem your own invite",
});
assert.deepEqual(await invites.redeemInvite(invite.code, "guest"), {
success: true,
serverUrl: "https://srv.example",
});
assert.deepEqual(await invites.redeemInvite(invite.code, "guest-2"), {
success: false,
error: "Invite has been fully redeemed",
});
const second = await invites.createInvite("creator");
const listed = await invites.listInvites("creator");
const secondRow = listed.find((i) => i.code === second.code)!;
assert.deepEqual([secondRow.serverUrl, secondRow.maxUses, secondRow.useCount], [null, 1, 0]);
assert.equal(await invites.revokeInvite(secondRow.id), true);
assert.deepEqual(await invites.redeemInvite(second.code, "guest"), {
success: false,
error: "Invite has been revoked",
});
});
test("characterization: revokeInvite currently returns true for an unknown invite id", async () => {
assert.equal(await invites.revokeInvite("does-not-exist"), true);
});
test("servers: connect → list (no key hash exposed) → disconnect", async () => {
const conn = await servers.connectServer("Peer", "https://peer.example", "peer-key");
assert.deepEqual(
{ ...conn, id: typeof conn.id },
{
id: "string",
name: "Peer",
url: "https://peer.example",
status: "connected",
lastSyncAt: null,
errorMessage: null,
}
);
const listed = await servers.listServers();
const mine = listed.find((s) => s.id === conn.id) as Record<string, unknown> | undefined;
assert.ok(mine);
assert.equal("apiKeyHash" in mine, false);
await servers.disconnectServer(conn.id);
});
test("badges: malformed criteria do not abort valid awards or hidden prerequisite evaluation", async () => {
// The malformed definition remains stored but is ignored consistently in both paths.
core
.getDbInstance()
.prepare(
`INSERT INTO badge_definitions (id, name, description, icon, category, rarity, criteria, hidden)
VALUES ('char-broken', 'Broken', '', 'x', 'usage', 'common', 'not json', 0)`
)
.run();
gamificationDb.addXp("fx-criteria-recovery", "request", 1);
const unlocked = await badges.evaluateBadges("fx-criteria-recovery", "request");
assert.ok(unlocked.includes("first-token"));
assert.equal(gamificationDb.hasBadge("fx-criteria-recovery", "first-token"), true);
assert.equal(gamificationDb.hasBadge("fx-criteria-recovery", "char-broken"), false);
});