`, favicon, and body of `Root()` to\nmatch your app's existing `index.html`, and stamp anything else your shell\nreferences directly (images, css) with `immutableFileUrl()`.\n\n1. Create `frontend/root.tsx`:\n\n```tsx\n/** @jsxImportSource npm:hono@4/jsx */\nimport { raw } from \"npm:hono@4/html\";\nimport { immutableFileUrl } from \"https://esm.town/v/std/utils/index.ts\";\n\n// The HTML shell for the app. It is never cached, so immutableFileUrl can stamp\n// the current val version into each asset URL — the browser caches those\n// immutably, and publishing the val changes the URLs, refetching exactly once.\nexport function Root() {\n return (\n <>\n {raw(\"<!DOCTYPE html>\")}\n <html lang=\"en\">\n <head>\n <meta charSet=\"UTF-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>React Hono Val Town Starter

[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_297":298,"_299":300},"routes/_app.x.$handle.$name",{"_11":12,"_13":14,"_15":-7,"_18":19,"_17":-7,"_223":-5,"_20":224,"_22":225,"_226":227,"_228":229,"_26":230,"_24":231,"_232":-5,"_233":-5,"_234":60,"_235":236,"_237":57,"_238":-5,"_239":-5,"_240":241},"routes/_app.x.$handle.$name.code.$",{"_11":12,"_13":14,"_15":16,"_17":-7,"_18":19,"_20":21,"_22":23,"_24":25,"_26":27,"_28":-5,"_29":-5,"_30":-5,"_31":-5,"_32":-5},"handle","IceyDomain","name","card-redeem","branchName","main","version","path","index.ts","project",{"_33":165,"_13":14,"_45":166,"_167":-5,"_168":60,"_169":170,"_171":170,"_172":173,"_174":-5,"_175":176,"_177":38,"_178":57,"_179":-5,"_180":-5,"_181":86,"_182":183,"_184":185,"_186":187,"_188":189,"_190":-5,"_191":192,"_193":192,"_194":195,"_196":195,"_197":195,"_198":192,"_199":192,"_200":201,"_202":203,"_204":205,"_206":60},"tree",[51,52,53,54,55],"file",{"_33":34,"_35":36,"_37":38,"_13":19,"_39":40,"_41":42,"_17":43,"_44":-5,"_45":46,"_47":48,"_49":14,"_18":50},"contents",[],"upstream","pull","ahead","behind","envVars","id","c80bbaa3-ce12-471b-a294-a807b21c85e5","branchId","57a6487e-c99e-4332-92e2-6d15ca868b6a","fileId","01a0af41-2f44-7689-90a1-221a99b90e3a","content","import { parseVal, serveImmutableFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport { Hono } from \"npm:hono\";\nimport { Root } from \"./frontend/root.tsx\";\nimport {\n activateCard,\n fmtCents,\n generateCards,\n getAccount,\n getCard,\n listAccounts,\n listCards,\n listTxns,\n redeemCard,\n refund,\n stats,\n toCents,\n topUp,\n voidCard,\n} from \"./cards.ts\";\n\nconst app = new Hono();\n\n// ---------------------------------------------------------------------------\n// Error handling: thrown errors become clean JSON.\n// ---------------------------------------------------------------------------\nfunction handle(fn: () => Promise) {\n return fn()\n .then((data) => Response.json(data))\n .catch((e: unknown) => {\n const msg = e instanceof Error ? e.message : String(e);\n return Response.json({ error: msg }, { status: 400 });\n });\n}\n\n// ---------------------------------------------------------------------------\n// Admin auth. Every /api/admin/* route requires the ADMIN_TOKEN secret, sent as\n// either `Authorization: Bearer ` or `X-Admin-Token: `.\n// ---------------------------------------------------------------------------\nconst ADMIN_TOKEN = Deno.env.get(\"ADMIN_TOKEN\");\n\n/** Constant-time string compare, so the token can't be guessed byte-by-byte. */\nfunction safeEqual(a: string, b: string): boolean {\n if (a.length !== b.length) return false;\n let diff = 0;\n for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);\n return diff === 0;\n}\n\napp.use(\"/api/admin/*\", async (c, next) => {\n if (!ADMIN_TOKEN) {\n return c.json(\n {\n error:\n \"Admin API is not configured: set the ADMIN_TOKEN environment variable on this val.\",\n },\n 500,\n );\n }\n const auth = c.req.header(\"authorization\") ?? \"\";\n const bearer = auth.replace(/^Bearer\\s+/i, \"\").trim();\n const token = bearer || c.req.header(\"x-admin-token\") || \"\";\n if (!token || !safeEqual(token, ADMIN_TOKEN)) {\n return c.json({ error: \"Unauthorized — a valid admin token is required.\" }, 401);\n }\n await next();\n});\n\n// ---------------------------------------------------------------------------\n// PUBLIC API — the customer's side. The card code itself is the credential.\n// ---------------------------------------------------------------------------\n\n// Look up a card (so the redeem page can show its value before claiming)\napp.get(\"/api/cards/:code\", (c) =>\n handle(async () => {\n const card = await getCard(c.req.param(\"code\"));\n if (!card) throw new Error(\"Card not found — check the code\");\n return { card };\n }));\n\n// Redeem a card's FULL value into an account\napp.post(\"/api/cards/:code/redeem\", async (c) => {\n const body = await c.req.json().catch(() => ({}));\n return handle(async () => {\n const name = String(body.account ?? body.name ?? \"\").trim();\n const result = await redeemCard(c.req.param(\"code\"), name);\n return {\n ...result,\n message: `Redeemed ${fmtCents(result.amountCents)} to ${result.account.name}`,\n };\n });\n});\n\n// Check an account's balance\napp.get(\"/api/accounts/:name\", (c) =>\n handle(async () => {\n const account = await getAccount(c.req.param(\"name\"));\n return { account: account ?? { name: c.req.param(\"name\"), balance: 0, created_at: \"\" } };\n }));\n\n// ---------------------------------------------------------------------------\n// ADMIN API — protected. Generating, activating, and voiding cards.\n// ---------------------------------------------------------------------------\n\napp.get(\"/api/admin/stats\", () => handle(async () => await stats()));\n\napp.post(\"/api/admin/cards/generate\", async (c) => {\n const body = await c.req.json().catch(() => ({}));\n return handle(async () => {\n const amountCents = body.amountCents != null\n ? Number(body.amountCents)\n : toCents(Number(body.amount ?? 25));\n const cards = await generateCards({\n count: Number(body.count ?? 10),\n amountCents,\n batch: body.batch,\n prefix: body.prefix,\n note: body.note,\n });\n return { created: cards.length, cards };\n });\n});\n\napp.get(\"/api/admin/cards\", (c) =>\n handle(async () => {\n const batch = c.req.query(\"batch\") || undefined;\n const limit = Number(c.req.query(\"limit\") ?? 50);\n return { cards: await listCards(limit, batch) };\n }));\n\napp.post(\"/api/admin/cards/:code/activate\", async (c) => {\n const body = await c.req.json().catch(() => ({}));\n return handle(async () => {\n const amountCents = body.amountCents != null\n ? Number(body.amountCents)\n : body.amount != null\n ? toCents(Number(body.amount))\n : undefined;\n return { card: await activateCard(c.req.param(\"code\"), amountCents) };\n });\n});\n\napp.post(\"/api/admin/cards/:code/topup\", async (c) => {\n const body = await c.req.json().catch(() => ({}));\n return handle(async () => {\n const amountCents = body.amountCents != null\n ? Number(body.amountCents)\n : toCents(Number(body.amount));\n return { card: await topUp(c.req.param(\"code\"), amountCents) };\n });\n});\n\napp.post(\"/api/admin/cards/:code/refund\", async (c) => {\n const body = await c.req.json().catch(() => ({}));\n return handle(async () => {\n const amountCents = body.amountCents != null\n ? Number(body.amountCents)\n : toCents(Number(body.amount));\n return { card: await refund(c.req.param(\"code\"), amountCents) };\n });\n});\n\napp.post(\"/api/admin/cards/:code/void\", (c) =>\n handle(async () => ({ card: await voidCard(c.req.param(\"code\")) })));\n\napp.get(\"/api/admin/txns\", (c) =>\n handle(async () => {\n const code = c.req.query(\"code\") || undefined;\n return { txns: await listTxns(code, Number(c.req.query(\"limit\") ?? 100)) };\n }));\n\napp.get(\"/api/admin/accounts\", (c) =>\n handle(async () => ({ accounts: await listAccounts(Number(c.req.query(\"limit\") ?? 50)) })));\n\n// ---------------------------------------------------------------------------\n// Frontend\n// ---------------------------------------------------------------------------\n\n// Serve the (never-cached) HTML shell at the root /\napp.get(\"/\", (c) => c.html(Root()));\n\n// Serve frontend files at the version-addressed URLs Root() stamps, cached immutably\napp.get(\"/__immutable/*\", (c) => serveImmutableFile(c.req.path));\n\n// View source redirect\napp.get(\"/source\", (c) => c.redirect(parseVal().links.self.val));\n\n// Unwrap and rethrow Hono errors as the original error\n// If you delete this, all errors will be \"Internal Server Error\"\napp.onError((err) => Promise.reject(err));\n\n// HTTP vals expect an exported \"fetch handler\"\n// This is how you \"run the server\" in Val Town with Hono\nexport default app.fetch;","fileType","http",2,"parentId","createdAt",["D",1789647352891],"branchVersion",13,"label",[19],{"_33":90,"_13":91,"_37":92,"_44":-5,"_35":36,"_47":69,"_56":57,"_45":93,"_17":86,"_41":94,"_39":-5,"_59":60,"_49":-5,"_61":95,"_18":96},{"_33":82,"_13":83,"_37":84,"_44":-5,"_35":36,"_47":69,"_56":57,"_45":85,"_17":86,"_41":24,"_39":87,"_59":60,"_49":-5,"_61":88,"_18":89},{"_33":74,"_13":75,"_37":76,"_44":-5,"_35":36,"_47":77,"_56":57,"_45":78,"_17":43,"_41":24,"_39":79,"_59":60,"_49":-5,"_61":80,"_18":81},{"_33":64,"_13":65,"_37":66,"_44":-5,"_35":36,"_47":67,"_56":57,"_45":68,"_17":69,"_41":70,"_39":71,"_59":60,"_49":-5,"_61":72,"_18":73},{"_33":34,"_13":19,"_37":38,"_44":-5,"_35":36,"_47":48,"_56":57,"_45":58,"_17":43,"_41":42,"_39":40,"_59":60,"_49":14,"_61":62,"_18":63},"latest",true,["D",1789647352891],"deleted",false,"children",[],[19],"54076026-0e02-4ef6-975e-13cbbd055270","cards.ts","04e5b21e-b290-11f1-b02b-1607ee4eb77e",12,["D",1789647340470],1,"script","// ---------------------------------------------------------------------------\n// Gift-card engine — Xbox/Roblox style.\n//\n// The QR code only ever contains a random CODE. The card's value lives here, in\n// the database, behind the server. Redeeming a card claims its FULL value and\n// credits it to a customer account. One card, one redemption.\n// ---------------------------------------------------------------------------\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\n\n// Money is stored in CENTS as integers — never floats.\nexport type CardStatus = \"inactive\" | \"active\" | \"redeemed\" | \"void\";\n\nexport type Card = {\n code: string;\n balance: number; // cents, current (0 once redeemed)\n initial: number; // cents, face value\n status: CardStatus;\n batch: string | null;\n note: string | null;\n created_at: string;\n activated_at: string | null;\n redeemed_at: string | null;\n redeemed_by: string | null;\n};\n\nexport type Account = {\n name: string;\n balance: number; // cents\n created_at: string;\n};\n\nexport type Txn = {\n id: number;\n code: string;\n kind: \"activate\" | \"redeem\" | \"refund\" | \"topup\" | \"void\";\n amount: number; // cents, signed\n balance_after: number;\n account: string | null;\n created_at: string;\n};\n\n// ----------------------------- Schema -----------------------------\nlet schemaReady: Promise | null = null;\n\nexport function ensureSchema(): Promise {\n if (!schemaReady) {\n schemaReady = (async () => {\n await sqlite.batch([\n {\n sql: `CREATE TABLE IF NOT EXISTS cards (\n code TEXT PRIMARY KEY,\n balance INTEGER NOT NULL DEFAULT 0,\n initial INTEGER NOT NULL DEFAULT 0,\n status TEXT NOT NULL DEFAULT 'inactive',\n batch TEXT,\n note TEXT,\n created_at TEXT NOT NULL,\n activated_at TEXT\n )`,\n },\n {\n sql: `CREATE TABLE IF NOT EXISTS accounts (\n name TEXT PRIMARY KEY,\n balance INTEGER NOT NULL DEFAULT 0,\n created_at TEXT NOT NULL\n )`,\n },\n {\n sql: `CREATE TABLE IF NOT EXISTS card_txns (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n code TEXT NOT NULL,\n kind TEXT NOT NULL,\n amount INTEGER NOT NULL,\n balance_after INTEGER NOT NULL,\n store TEXT,\n created_at TEXT NOT NULL\n )`,\n },\n { sql: `CREATE INDEX IF NOT EXISTS idx_txn_code ON card_txns (code)` },\n { sql: `CREATE INDEX IF NOT EXISTS idx_cards_batch ON cards (batch)` },\n ]);\n\n // Idempotent migrations (the tables above may pre-date these columns).\n const migrations = [\n \"ALTER TABLE cards ADD COLUMN redeemed_at TEXT\",\n \"ALTER TABLE cards ADD COLUMN redeemed_by TEXT\",\n \"ALTER TABLE card_txns ADD COLUMN account TEXT\",\n ];\n for (const sql of migrations) {\n try {\n await sqlite.execute(sql);\n } catch {\n // column already exists — fine\n }\n }\n })();\n }\n return schemaReady;\n}\n\n// --------------------------- Code generation ---------------------------\n// Unambiguous alphabet: no I, O, 0, 1 — so a human can read a card aloud.\nconst ALPHABET = \"ABCDEFGHJKLMNPQRSTUVWXYZ23456789\";\n\nfunction randomCode(prefix: string, groups = 3, size = 4): string {\n const bytes = new Uint8Array(groups * size);\n crypto.getRandomValues(bytes);\n const chars = Array.from(bytes, (b) => ALPHABET[b % ALPHABET.length]);\n const parts: string[] = [];\n for (let i = 0; i < groups; i++) {\n parts.push(chars.slice(i * size, (i + 1) * size).join(\"\"));\n }\n return `${prefix}-${parts.join(\"-\")}`;\n}\n\nfunction now(): string {\n return new Date().toISOString();\n}\n\n// --------------------------- Lifecycle ---------------------------\n\n/**\n * Create a batch of cards. They start INACTIVE and worth nothing — a stolen box\n * of unactivated cards is worthless until activated.\n */\nexport async function generateCards(opts: {\n count: number;\n amountCents: number;\n batch?: string;\n prefix?: string;\n note?: string;\n}): Promise {\n await ensureSchema();\n const count = Math.min(Math.max(1, Math.floor(opts.count)), 500);\n const prefix = (opts.prefix || \"NBL\").toUpperCase().slice(0, 8);\n const batch = opts.batch || `B${Date.now().toString(36).toUpperCase()}`;\n const created: Card[] = [];\n\n for (let i = 0; i < count; i++) {\n for (let attempt = 0; attempt < 5; attempt++) {\n const code = randomCode(prefix);\n const res = await sqlite.execute({\n sql: `INSERT OR IGNORE INTO cards\n (code, balance, initial, status, batch, note, created_at)\n VALUES (?, 0, ?, 'inactive', ?, ?, ?)`,\n args: [code, opts.amountCents, batch, opts.note ?? null, now()],\n });\n if (res.rowsAffected > 0) {\n created.push({\n code,\n balance: 0,\n initial: opts.amountCents,\n status: \"inactive\",\n batch,\n note: opts.note ?? null,\n created_at: now(),\n activated_at: null,\n redeemed_at: null,\n redeemed_by: null,\n });\n break;\n }\n }\n }\n return created;\n}\n\nexport async function getCard(code: string): Promise {\n await ensureSchema();\n const res = await sqlite.execute({\n sql: \"SELECT * FROM cards WHERE code = ?\",\n args: [normalize(code)],\n });\n return (res.rows[0] as Card | undefined) ?? null;\n}\n\nexport async function listCards(limit = 50, batch?: string): Promise {\n await ensureSchema();\n const res = batch\n ? await sqlite.execute({\n sql: \"SELECT * FROM cards WHERE batch = ? ORDER BY created_at DESC LIMIT ?\",\n args: [batch, limit],\n })\n : await sqlite.execute({\n sql: \"SELECT * FROM cards ORDER BY created_at DESC LIMIT ?\",\n args: [limit],\n });\n return res.rows as unknown as Card[];\n}\n\n/** Make a card live: give it its face value so it can be redeemed. */\nexport async function activateCard(code: string, amountCents?: number): Promise {\n await ensureSchema();\n const c = normalize(code);\n const card = await getCard(c);\n if (!card) throw new Error(\"Card not found\");\n if (card.status === \"void\") throw new Error(\"This card has been voided\");\n if (card.status === \"redeemed\") throw new Error(\"This card has already been redeemed\");\n if (card.status === \"active\") throw new Error(\"This card is already active\");\n\n const value = amountCents ?? card.initial;\n const ts = now();\n await sqlite.batch([\n {\n sql: `UPDATE cards SET status = 'active', balance = ?, initial = ?, activated_at = ?\n WHERE code = ? AND status = 'inactive'`,\n args: [value, value, ts, c],\n },\n {\n sql: `INSERT INTO card_txns (code, kind, amount, balance_after, account, created_at)\n VALUES (?, 'activate', ?, ?, NULL, ?)`,\n args: [c, value, value, ts],\n },\n ]);\n return (await getCard(c))!;\n}\n\nexport type RedeemResult = {\n card: Card;\n account: Account;\n amountCents: number;\n};\n\n/**\n * Redeem a card's FULL value into a customer account — one card, one claim.\n *\n * The claim is the atomic guard: a single conditional UPDATE flips the card from\n * `active` to `redeemed`. If two people submit the same code at once, only one\n * UPDATE can match, so only one gets the value.\n */\nexport async function redeemCard(code: string, accountName: string): Promise {\n await ensureSchema();\n const c = normalize(code);\n const name = accountName.trim();\n if (!name) throw new Error(\"Enter the account to redeem into\");\n if (name.length > 60) throw new Error(\"Account name is too long\");\n\n const card = await getCard(c);\n if (!card) throw new Error(\"Card not found — check the code\");\n if (card.status === \"void\") throw new Error(\"This card has been voided\");\n if (card.status === \"redeemed\") throw new Error(\"This card has already been redeemed\");\n if (card.status === \"inactive\") throw new Error(\"This card hasn't been activated yet\");\n if (card.balance <= 0) throw new Error(\"This card has no value left\");\n\n const amount = card.balance;\n const ts = now();\n\n // 1. Atomically claim the card.\n const claim = await sqlite.execute({\n sql: `UPDATE cards\n SET status = 'redeemed', balance = 0, redeemed_at = ?, redeemed_by = ?\n WHERE code = ? AND status = 'active'`,\n args: [ts, name, c],\n });\n if (claim.rowsAffected === 0) {\n throw new Error(\"This card was already redeemed\");\n }\n\n // 2. Credit the account + log the txn together. If this fails, put the card\n // back so its value isn't lost.\n try {\n await sqlite.batch([\n {\n sql: `INSERT INTO accounts (name, balance, created_at) VALUES (?, ?, ?)\n ON CONFLICT(name) DO UPDATE SET balance = balance + ?`,\n args: [name, amount, ts, amount],\n },\n {\n sql: `INSERT INTO card_txns (code, kind, amount, balance_after, account, created_at)\n VALUES (?, 'redeem', ?, 0, ?, ?)`,\n args: [c, amount, name, ts],\n },\n ]);\n } catch (e) {\n await sqlite.execute({\n sql: `UPDATE cards SET status = 'active', balance = ?, redeemed_at = NULL, redeemed_by = NULL\n WHERE code = ?`,\n args: [amount, c],\n });\n throw e;\n }\n\n return {\n card: (await getCard(c))!,\n account: (await getAccount(name))!,\n amountCents: amount,\n };\n}\n\nexport async function getAccount(name: string): Promise {\n await ensureSchema();\n const res = await sqlite.execute({\n sql: \"SELECT * FROM accounts WHERE name = ?\",\n args: [name.trim()],\n });\n return (res.rows[0] as Account | undefined) ?? null;\n}\n\nexport async function listAccounts(limit = 50): Promise {\n await ensureSchema();\n const res = await sqlite.execute({\n sql: \"SELECT * FROM accounts ORDER BY balance DESC LIMIT ?\",\n args: [limit],\n });\n return res.rows as unknown as Account[];\n}\n\nexport async function topUp(code: string, amountCents: number): Promise {\n return adjust(code, amountCents, \"topup\");\n}\n\nexport async function refund(code: string, amountCents: number): Promise {\n return adjust(code, amountCents, \"refund\");\n}\n\nasync function adjust(\n code: string,\n amountCents: number,\n kind: \"topup\" | \"refund\",\n): Promise {\n await ensureSchema();\n const c = normalize(code);\n if (!Number.isInteger(amountCents) || amountCents <= 0) {\n throw new Error(\"Amount must be a positive number of cents\");\n }\n const card = await getCard(c);\n if (!card) throw new Error(\"Card not found\");\n if (card.status === \"void\") throw new Error(\"This card has been voided\");\n\n await sqlite.execute({\n sql: \"UPDATE cards SET balance = balance + ? WHERE code = ?\",\n args: [amountCents, c],\n });\n const after = (await getCard(c))!;\n await sqlite.execute({\n sql: `INSERT INTO card_txns (code, kind, amount, balance_after, account, created_at)\n VALUES (?, ?, ?, ?, NULL, ?)`,\n args: [c, kind, amountCents, after.balance, now()],\n });\n return after;\n}\n\nexport async function voidCard(code: string): Promise {\n await ensureSchema();\n const c = normalize(code);\n const card = await getCard(c);\n if (!card) throw new Error(\"Card not found\");\n\n await sqlite.batch([\n { sql: \"UPDATE cards SET status = 'void', balance = 0 WHERE code = ?\", args: [c] },\n {\n sql: `INSERT INTO card_txns (code, kind, amount, balance_after, account, created_at)\n VALUES (?, 'void', ?, 0, NULL, ?)`,\n args: [c, -card.balance, now()],\n },\n ]);\n return (await getCard(c))!;\n}\n\nexport async function listTxns(code?: string, limit = 100): Promise {\n await ensureSchema();\n const res = code\n ? await sqlite.execute({\n sql: \"SELECT * FROM card_txns WHERE code = ? ORDER BY id DESC LIMIT ?\",\n args: [normalize(code), limit],\n })\n : await sqlite.execute({\n sql: \"SELECT * FROM card_txns ORDER BY id DESC LIMIT ?\",\n args: [limit],\n });\n return res.rows as unknown as Txn[];\n}\n\nexport async function stats(): Promise<{\n total: number;\n active: number;\n inactive: number;\n redeemed: number;\n outstandingCents: number;\n accounts: number;\n creditedCents: number;\n}> {\n await ensureSchema();\n const cards = await sqlite.execute({\n sql: `SELECT\n COUNT(*) AS total,\n SUM(CASE WHEN status = 'active' THEN 1 ELSE 0 END) AS active,\n SUM(CASE WHEN status = 'inactive' THEN 1 ELSE 0 END) AS inactive,\n SUM(CASE WHEN status = 'redeemed' THEN 1 ELSE 0 END) AS redeemed,\n SUM(CASE WHEN status = 'active' THEN balance ELSE 0 END) AS outstanding\n FROM cards`,\n });\n const accounts = await sqlite.execute({\n sql: \"SELECT COUNT(*) AS n, SUM(balance) AS credited FROM accounts\",\n });\n const c = cards.rows[0] as Record;\n const a = accounts.rows[0] as Record;\n return {\n total: Number(c.total ?? 0),\n active: Number(c.active ?? 0),\n inactive: Number(c.inactive ?? 0),\n redeemed: Number(c.redeemed ?? 0),\n outstandingCents: Number(c.outstanding ?? 0),\n accounts: Number(a.n ?? 0),\n creditedCents: Number(a.credited ?? 0),\n };\n}\n\n/** Accept codes with spaces, lowercase, or missing dashes. */\nexport function normalize(code: string): string {\n return code.trim().toUpperCase().replace(/\\s+/g, \"\");\n}\n\n// --------------------------- Money helpers ---------------------------\nexport function toCents(dollars: number | string): number {\n const n = typeof dollars === \"string\" ? Number(dollars) : dollars;\n if (!Number.isFinite(n) || n < 0) throw new Error(\"Invalid amount\");\n return Math.round(n * 100);\n}\n\nexport function fmtCents(cents: number): string {\n return `$${(cents / 100).toFixed(2)}`;\n}",[],[65],"bc5fd57a-b718-450e-9af7-42c16a1228d5","README.md","01a0af41-2f44-7689-90a1-1c808e231f8d",17,["D",1789647713180],"# 💳 Gift Card System\n\nAn Xbox/Roblox-style **gift card** backend with a QR **redeem page** and a\ntoken-protected **admin** screen for generating and printing cards. Built on Val\nTown (Hono + SQLite).\n\n**Live:** \n\n## The flow\n\nA customer buys a card, then redeems it into their account. There's no cashier\nand no amount to choose — a card's **full value** goes to the account, once.\n\n```mermaid\ngraph LR\n A[\"1. Admin generates batch
(INACTIVE, $0)\"] --> B[\"2. Print cards
(QR = code only)\"]\n B --> C[\"3. Admin activates
(card goes live)\"]\n C --> D[\"4. Customer scans/enters code\"]\n D --> E[\"5. Full value → their account\"]\n```\n\n## The core idea: a card is a *key*, not a *wallet*\n\nThe QR code contains **only a random code** (e.g. `NBL-4GJ9-4FG4-KRUE`) — never a\nvalue. The value lives in SQLite, behind the server. A screenshot or photocopy of\na card is worthless without the matching database row.\n\n## Why it's safe\n\n| Rule | Where |\n| --- | --- |\n| Random (non-sequential) codes | `randomCode()` in `cards.ts` |\n| Values only on the server | `cards` table; the client never computes money |\n| **One card, one redemption** | atomic `UPDATE ... WHERE status = 'active'` |\n| Activation gate | inactive cards can't be redeemed |\n| Void / lost-card kill switch | `status = 'void'` |\n| Full audit trail | every change writes to `card_txns` |\n| Integer cents (no float drift) | `toCents()` / `fmtCents()` |\n| **Admin routes require a token** | `ADMIN_TOKEN` + `Authorization: Bearer` |\n\nThe atomic claim is the important one: redeeming flips the card from `active` to\n`redeemed` in a single conditional `UPDATE`. If two people submit the same code\nat the same instant, only one can match the row — so only one gets the value.\n\n## Authentication\n\nEverything under **`/api/admin/*`** requires the `ADMIN_TOKEN` secret:\n\n```bash\ncurl -H \"Authorization: Bearer $ADMIN_TOKEN\" https://card-redeem.val.run/api/admin/stats\n```\n\nThe token is compared in **constant time**. Requests without it (or with the\nwrong one) get a `401`.\n\nThe admin UI prompts for the token once and keeps it in `sessionStorage` for that\nbrowser tab only — it's never baked into the JavaScript bundle.\n\n👉 Set/change it here: https://www.val.town/x/IceyDomain/card-redeem/environment-variables?key=ADMIN_TOKEN\n\n## API\n\nBase URL: `https://card-redeem.val.run`\n\n### Public — the customer's side\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/api/cards/:code` | Look up a card (shows its value) |\n| `POST` | `/api/cards/:code/redeem` | Redeem the full value → `{ account }` |\n| `GET` | `/api/accounts/:name` | Check an account's balance |\n\n### Admin — token required\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/api/admin/stats` | Totals + credited amounts |\n| `POST` | `/api/admin/cards/generate` | Create a batch (`count`, `amount`, `prefix`, `note`) |\n| `GET` | `/api/admin/cards` | List recent cards (`?batch=` `&limit=`) |\n| `POST` | `/api/admin/cards/:code/activate` | Make a card live |\n| `POST` | `/api/admin/cards/:code/topup` | Add value |\n| `POST` | `/api/admin/cards/:code/refund` | Refund |\n| `POST` | `/api/admin/cards/:code/void` | Void a card |\n| `GET` | `/api/admin/txns` | Recent transactions (`?code=`) |\n| `GET` | `/api/admin/accounts` | Accounts + balances |\n\nAmounts accept dollars (`amount: 25`) or exact cents (`amountCents: 2500`).\n\n```bash\nTOKEN=your_admin_token\n\n# Generate 50 × $25 cards (they start INACTIVE)\ncurl -X POST https://card-redeem.val.run/api/admin/cards/generate \\\n -H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' \\\n -d '{\"count\":50,\"amount\":25,\"prefix\":\"NBL\"}'\n\n# Activate one when it ships\ncurl -X POST https://card-redeem.val.run/api/admin/cards/NBL-4GJ9-4FG4-KRUE/activate \\\n -H \"Authorization: Bearer $TOKEN\"\n\n# A customer redeems it (no token needed — the code is the credential)\ncurl -X POST https://card-redeem.val.run/api/cards/NBL-4GJ9-4FG4-KRUE/redeem \\\n -H 'Content-Type: application/json' -d '{\"account\":\"icey_player\"}'\n```\n\n## The UI\n\n- **📷 Redeem** — scan the QR (camera via `jsQR`) or type the code, then claim the\n full value into an account. Shows the resulting balance.\n- **⚙️ Admin** — token-gated. Generate batches, render printable QR codes,\n activate cards, void cards, and see stats + accounts.\n\n## Files\n\n```\nindex.ts ← Hono server: public + admin API, frontend\ncards.ts ← The card engine (schema + lifecycle)\nfrontend/\n root.tsx ← HTML shell\n index.tsx ← React entrypoint\n components/\n App.tsx ← Tab shell\n Redeem.tsx ← QR scanner + claim flow\n Admin.tsx ← Token-gated generate / print / activate\n api.ts ← API client + types\n```\n\n## Pointing your own app at it\n\nYour Nebula frontend can call this API directly — the card logic stays here,\nwhere it can't be read out of your JavaScript. CORS is open\n(`access-control-allow-origin: *`):\n\n```ts\n// Look up a card's value\nconst res = await fetch(\"https://card-redeem.val.run/api/cards/\" + code);\nconst { card } = await res.json();\n\n// Redeem it into the signed-in user's account\nawait fetch(`https://card-redeem.val.run/api/cards/${code}/redeem`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ account: currentUser }),\n});\n```\n\n## ⚠️ Before real money\n\nThis is a working foundation. A production system would also add:\n\n- **Real user accounts** — right now an account is just a name, so anyone could\n redeem into anyone's name. Wire this to your own auth and pass a verified\n account id.\n- **Rate limiting** on lookups, so codes can't be brute-forced.\n- **Idempotency keys** on redeem, so a network retry can't double-claim.\n- **Signed codes** (HMAC) so a fake code can be rejected without a DB hit.",[],[75],"c9a644e8-51ac-452f-a73c-57220fd87ef2","CHANGELOG.md","01a0af41-2f44-7689-90a1-1b65a816daa2",["D",1789646679801],0,"# Changelog\n\n## 2026-07-30 — Immutable asset caching\n\nFrontend files are now served at version-addressed URLs\n(`/__immutable/45/frontend/index.tsx`) with\n`Cache-Control: public, max-age=31536000, immutable`, so repeat visits load the\nwhole client graph from the browser cache — roughly 3× faster (~665ms → ~157ms\nmeasured). Publishing your val bumps its version, which changes every URL, so\ncaches invalidate automatically. Old-version URLs return 404 after a publish\n(like Next.js build assets); a reload picks up the new version.\n\nWhat changed in the template:\n\n- `frontend/index.html` → [`frontend/root.tsx`](/frontend/root.tsx): the HTML\n shell is now JSX and stamps asset URLs with `immutableFileUrl()`\n- [`index.ts`](/index.ts): serves `Root()` at `/`, and one\n `app.get(\"/__immutable/*\", (c) => serveImmutableFile(c.req.path))` route\n serves all frontend files\n\n### Upgrading an existing remix\n\nYour copy of this template doesn't update automatically. Two options:\n\n**Minimal (most of the benefit):** point both routes at `serveImmutableFile` —\nyour existing bare URLs redirect into versioned space, the new route serves\nthem, and the whole module graph gets cached (costs one redirect per page view):\n\n```ts\nimport { serveImmutableFile } from \"https://esm.town/v/std/utils/index.ts\";\n\napp.get(\"/__immutable/*\", (c) => serveImmutableFile(c.req.path));\napp.get(\"/frontend/**/*\", (c) => serveImmutableFile(c.req.path)); // was serveFile\n```\n\n**Full upgrade (also removes the redirect):** three self-contained steps —\nno other files needed. Adjust the ``, favicon, and body of `Root()` to\nmatch your app's existing `index.html`, and stamp anything else your shell\nreferences directly (images, css) with `immutableFileUrl()`.\n\n1. Create `frontend/root.tsx`:\n\n```tsx\n/** @jsxImportSource npm:hono@4/jsx */\nimport { raw } from \"npm:hono@4/html\";\nimport { immutableFileUrl } from \"https://esm.town/v/std/utils/index.ts\";\n\n// The HTML shell for the app. It is never cached, so immutableFileUrl can stamp\n// the current val version into each asset URL — the browser caches those\n// immutably, and publishing the val changes the URLs, refetching exactly once.\nexport function Root() {\n return (\n <>\n {raw(\"<!DOCTYPE html>\")}\n <html lang=\"en\">\n <head>\n <meta charSet=\"UTF-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>React Hono Val Town Starter\n