NWP-201: issue virtual cards from the console

[MariMax]

Ticket

Closes NWP-201

What changed

Ops can issue virtual cards in the console instead of asking the platform team in Slack.

• Issuing: the Issue card drawer on /cards takes a nickname, a merchant, a spend limit and an optional merchant category lock. The card's currency is the merchant's settlement currency. The drawer shows it, sends it, and the server rejects any other.
• Card numbers: the server generates a 16-digit number on the 4242 test BIN with a Luhn check digit. The number is shown once, on the success screen. After that the card is only ever •••• <last4>.
• List: freeze, unfreeze and cancel (with a confirm step), all without reloading the page.
• Detail page: the full card record, spend against the limit, and a history of every status change.

The plan is docs/specs/NWP-201-issue-cards.md, and the code follows it.

How I verified it

• npm test passes: Test Files 7 passed (7) · Tests 69 passed (69).
  • src/lib/cards.test.ts: 1,000 generated numbers match ^4242\d{12}$ and pass Luhn. Every legal and illegal status transition is covered. spendProgress is tested at the 80% boundary.
  • src/data/cards.test.ts: every rejection the ticket lists, plus a merchant/currency mismatch, and the exact 5,000,000 boundary. The stored card never contains the number or any 16-digit run. A repeated idempotency key never issues twice or reveals the number again. cancelled is terminal.
  • src/data/metrics.test.ts: daily volume under TZ=America/New_York. It fails on the original metrics.ts; I checked by running it against that file.
• New behavior is covered by a test.
• Checked it in the browser, on a fresh dev server.
• npx tsc --noEmit and npx next lint are clean.
• curl against the running server:
  • A valid POST → 201 with number.
  • The same Idempotency-Key again → 409 "This card was already issued. Its number is not shown again."
  • Each bad request → 400 with a message:
    • missing merchant → "Merchant is required."
    • 0 and -5 → "Spend limit must be greater than zero."
    • 5000001 → "Spend limit cannot exceed 5,000,000 minor units."
    • JPY → "Currency must be one of USD, EUR, or GBP."
    • EUR for a USD merchant → "Lumen Coffee Roasters settles in USD. Issue this card in USD."
  • No 16-digit run appears in the list or detail responses.
  • PATCH frozen → active → cancelled → 200 each. Then active → 409. An unknown card → 404.
• Browser:
  • Issuing: I issued "Browser final" for Lumen Coffee Roasters. The drawer showed "Issued in USD, the merchant's settlement currency", and the success view showed 4242 9359 6594 2755.
  • After closing: Escape closed the drawer and focus went back to Issue card. The page had no full number, and the new row read •••• 2755.
  • Field error: an invalid limit shows an error under the field.
  • Row actions: Freeze turns into Unfreeze. Cancel card changes to Keep card / Confirm cancel, and confirming leaves "—". None of this reloads the page (a marker set on window survived).
  • Detail page: it shows the record, "£0.00 of £320.50 spent", and the history in Europe/London time.

Acceptance criteria

Core:

• Issue a card: the drawer POSTs to /api/cards, and the new card appears in the list.
• Card list: /cards shows nickname, merchant, masked number, category, spend limit, status and created date. There's a Cards link in the sidebar.
• Card detail: /cards/[id] shows the full record, spend against the limit, and history.
• Generated numbers: generateCardNumber in src/lib/cards.ts produces the 4242 BIN with a Luhn digit from a secure random source. Only issueCard calls it.
• Reveal once: VirtualCard has no number field; it stores last4 and a reference. The number is only in the no-store 201 response, and the drawer clears it on close.
• Server-side validation: parseIssueCard in src/data/cards.ts rejects every case listed above.

Stretch:

• Freeze and unfreeze without a reload, plus cancel with a confirm step.
• Spend progress: the bar turns amber past 80% (spendProgress, tested). Spend is honest: it's 0 until a card network records authorizations, and the page says so.
• Merchant category lock: chosen at issue time, checked against an allowlist on the server, and shown on the list and the detail page.
• Tests on the Luhn generator and the transitions.
• Written states: the empty list, a card-specific not-found page, and inline role="alert" errors in the drawer and row actions.

Also:

• Idempotent issue: handled by issueCardOnce.
• Currency must match the merchant.
• Audit trail: card.events, shown as the card's history.

Bugs fixed along the way

• src/data/metrics.ts dailyVolume, the overview's Daily volume chart:

  • It bucketed by the server's local date (toLocaleDateString), which breaks ORG-STANDARDS TEST: leaderboard preview — do not merge #4.
  • It added up amount / 100 as floats (Brandon testing #1).
  • It reported each refunded payment's full amount on the payment's date, but 30% of seeded refunds are partial and happen later (TEST: grader smoke check — do not merge #3).

  It now uses utcDayKey, integer minor units, and store.refunds, and reads payments through filterPayments, the one query builder, instead of store.payments.

• src/data/queries.ts sortPayments, the payments table and CSV export: it compared amounts as strings, so 10000 sorted before 900. It now compares the integer minor units, with a regression test in queries.test.ts.

• src/components/Drawer.tsx: the close button contains only an icon and had no accessible name. I added aria-label="Close", which fixes every drawer in the console.

Found but not fixed:

• The payments page builds its filters by hand. That is fixed on the NWP-101 branch, which changes the same files.
• The overview adds USD, EUR and GBP into one total. Fixing that needs a product decision about how to show several currencies.

Notes for the reviewer

• Every error returns { error } with 400, 404 or 409. There was no API error shape before this change.
• The four seed cards are fixed values. They never draw from the shared seeded random generator, so every seeded payment is unchanged.
• A dev server started before this branch keeps its old in-memory store on globalThis, so restart it.
• Out of scope: persistence (NWP-203), auth, card network calls, editing a limit (NWP-202), and enforcing the category lock on real spend.

🤖 Generated with Claude Code

[JJFromTenex]

Claude Code 101 — Repo Rescue

🏆 Build Battle Score: 97 / 100

One-line verdict: Near-complete execution — every core criterion, every correctness rule, both stretch tiers, and two real pre-existing bugs fixed with regression tests, all backed by a spec that actually matches the code delivered.

Core criteria — 100 / 100 (35%)

1. Issue a card: ✅ — Drawer POSTs to /api/cards; success screen shown, list refreshed via router.refresh().
2. Card list: ✅ — Nickname, merchant, masked number, category, limit, status, created date all present in cards/page.tsx.
3. Card detail: ✅ — Full record, spend-vs-limit, and history rendered in cards/[id]/page.tsx.
4. Generated numbers: ✅ — generateCardNumber in lib/cards.ts, CSPRNG-backed, 4242 BIN, Luhn digit; only issueCard calls it.
5. Reveal once: ✅ — Number only in the 201 (no-store) response, never on VirtualCard, cleared from client state on drawer close.
6. Server-side validation: ✅ — parseIssueCard in data/cards.ts enforces every listed rule; the route handler calls it, not the client.

Correctness rules — 100 / 100 (20%)

• Minor units: ✅ — Integer spendLimit/spent throughout; rejects non-integers.
• Luhn on 4242 BIN: ✅ — Randomized generator, 1000-iteration test, no hardcoded constant.
• Masking: ✅ — stored JSON checked in tests to contain no 16-digit run; list/detail never return the number.
• State machine: ✅ — active⇄frozen, either→cancelled, cancelled terminal, tested including reverse-from-cancelled.
• Server-side validation: ✅ — Validation lives in data/cards.ts, invoked from the route, not the client.

Context and planning — 90 / 100 (10%)

docs/specs/NWP-201-issue-cards.md cites real file/line references (queries.ts:18, store.ts:16, generate.ts:20), states the domain rules precisely, lists a file-by-file plan, and the delivered diff matches it closely, down to reusing parseFilters conventions and choosing Drawer over a nonexistent Dialog. Can't verify the referenced .claude/rules/cards.md exists, so held just short of a perfect score.

Code quality — 92 / 100 (15%)

Tests sit beside the code they cover and target real regressions (Luhn, transitions, idempotency, currency mismatch, string-vs-numeric sort, UTC bucketing). No DB/ORM added, no seed JSON tampering, no console.log/TODO found in the diff. Labels are wired via htmlFor/id, errors use role="alert", and the Drawer close button gets a real aria-label. Two genuine pre-existing defects (dailyVolume's local-date/float/refund bug, sortPayments's string sort) are named, root-caused, and fixed with tests — solid bonus. Can't independently verify the tsc/lint claims or full CLAUDE.md compliance from the diff alone.

PR description — 100 / 100 (5%)

Thorough: states what was built, verification steps (curl + browser + tests), an honest bugs-fixed section with root causes, and explicitly calls out remaining out-of-scope items.

Stretch goals — 100 / 100 (15%)

Tier 1: ✅ freeze/unfreeze without reload · ✅ amber progress bar past 80% · ✅ category lock chosen and displayed · ✅ Luhn/transition unit tests · ✅ written empty/not-found/inline-error states.
Tier 2: ✅ Idempotent issue — Idempotency-Key header honoured server-side in data/cards.ts issueCardOnce, tested for replay. ✅ Currency matches merchant — parseIssueCard in data/cards.ts rejects a mismatch against merchants.ts, and the drawer derives currency from the chosen merchant. (Cancel-with-confirm and audit trail also present but capped by the 0.50 Tier 2 ceiling.)

---

Breakdown: Core (100 × 0.35) + Rules (100 × 0.20) + Context (90 × 0.10) + Quality (92 × 0.15) + PR (100 × 0.05) + Stretch (100 × 0.15) = 97 / 100

One thing to do differently next time: Nothing structurally — the highest-leverage move for an even stronger submission would be citing the actual .claude/rules/cards.md content verbatim in the spec, since that's the one claim in the PR that can't be checked from the diff alone.

---

Powered by Anthropic and Tenex