NWP-201: issue virtual cards from the console

[FADHLyemen]

Ticket

Closes NWP-201

What changed

Ops can issue a virtual card from the console instead of asking the platform team in Slack. /cards lists every issued card — nickname, merchant, masked number, spend limit, status, created date — and opening one shows the full record, its spend against the limit, its authorizations, and its history. Issuing takes a nickname, merchant, spend limit and category lock; the number is generated server-side and shown exactly once. After that it is •••• 4242 everywhere, because the full number is never written to the record at all.

How I verified it

• npm test passes
• New behavior is covered by a test
• Checked it in the browser — not done. See "Deliberately not done".

npm test — 58 passed (4 files), up from 28 on main. 30 cases in src/lib/cards.test.ts.
npx tsc --noEmit — exit 0. npx next lint --dir src — No ESLint warnings or errors.

Server-side validation — every case 400 with a message:

missing merchant : 400  Merchant is required.
unknown merchant : 400  Unknown merchant.
zero limit       : 400  Spend limit must be greater than zero.
negative limit   : 400  Spend limit must be greater than zero.
over 5,000,000   : 400  Spend limit must be 5000000 minor units or less.
bad currency JPY : 400  Currency must be one of USD, EUR, GBP.
float limit 250.5: 400  Spend limit must be an integer number of minor units.
string "$250.00" : 400  Spend limit must be an integer number of minor units.
GBP merchant+USD : 400  Currency must match the merchant's own (GBP).

valid            : 201  card_0006
at exactly max   : 201  boundary accepted, not rejected
GBP merchant+GBP : 201  card_0006 GBP

Idempotent issue — same Idempotency-Key twice:

POST #1 : 201  card_0008  replayed=False
POST #2 : 200  card_0008  replayed=True     (no second card, no second number)

Reveal once — four surfaces grepped for anything on the 4242 BIN, all zero:

/cards  0 · /cards/card_0002  0 · /api/cards  0 · /api/cards/card_0002  0

POST /api/cards → fullNumber: 4242942034921448 | stored last4: 1448
GET  /api/cards/card_0008     → "last4": "1448"  (no fullNumber key)

Card payload has no spend field — spend is derived from authorizations:

sample card keys: category, createdAt, currency, history, id, last4,
                  merchantId, nickname, reference, spendLimit, status
no stored spend field on Card: True

State machine + audit trail — after freeze then unfreeze:

{'type': 'issued',         'to': 'active',                    'at': '2026-07-18T17:05:00.000Z'}
{'type': 'status_changed', 'from': 'active', 'to': 'frozen',  'at': '2026-09-10T18:45:05.233Z'}
{'type': 'status_changed', 'from': 'frozen', 'to': 'active',  'at': '2026-09-10T18:45:05.253Z'}

active->frozen 200 · frozen->active 200 · active->active 409 · "deleted" 400
active->cancelled 200 · cancelled->active 409 · cancelled->frozen 409 · unknown 404

Pages — /cards 200, /cards/card_0002 200, /cards/card_9999 404. Detail renders aria-valuenow="71", an Authorizations list and a History list. Cancel and Freeze carry per-card labels: aria-label="Cancel Halcyon ads", aria-label="Freeze Trade show travel".

Acceptance criteria

Core — all six met, evidence above.

• Issue a card · [x] Card list · [x] Card detail
• Generated numbers — 4242 BIN + Luhn, asserted over 500 iterations, generator source inlined above
• Reveal once, mask forever · [x] Server-side validation

Stretch — Tier 1

• Freeze/unfreeze without reload · [x] Amber past 80% · [x] Category lock · [x] Luhn + transition tests · [x] Written empty and error states

Stretch — Tier 2 (all five, added after the first review)

• Idempotent issue — Idempotency-Key header or body field; a replay returns the first card with replayed: true and HTTP 200. Ops double-clicking Issue cannot burn two numbers.
• Currency matches merchant — enforced in validateIssueInput, not just defaulted in the form. The form now shows the merchant's currency instead of offering a choice the server would reject.
• Spend is honest — the stored spent field is gone. Cards have real CardTransaction records and spend is spentForCard(), their sum, so the bar and the authorization list cannot disagree. A newly issued card reads zero with no special-casing.
• Cancel from the UI with confirm — two-step confirm naming the card, because cancelled is the one transition nothing comes back from.
• Audit trail — every card carries history: issued, then each status change with from/to and timestamp, rendered on the detail page.

Deliberately not done

No browser check. Everything above is curl and rendered-HTML inspection. I did not open the drawer, type in the form, or click Cancel in a real browser. The server half of every criterion is proven; the click path is not.

Out of scope per the ticket: persistence (NWP-203), auth, real network calls, editing a limit after issue (NWP-202).

Seeded cards hide the empty state. Five cards seed on boot, so the empty state only renders if the store is emptied. It is written and correct, but not what you see first.

No unit tests for the route handlers. src/lib/cards.ts is covered thoroughly; the routes are covered by the curl matrix above. src/app/api/ has no test file today and I did not start the pattern here.

Idempotency keys are unbounded. store.issuedKeys is a Map that grows for the life of the process. Fine for an in-memory store that resets on restart; a real deployment would need a TTL.

sortPayments amount bug still unfixed — String(a.amount).localeCompare(...) sorts 9000 after 123456. Found during NWP-101, untouched here. Different ticket.

Notes for the reviewer

The Card type has no field capable of holding a full number. That is the enforcement for reveal-once — not a strip step that a new route could forget, but the absence of anywhere to put one.

Cards live in src/data/cards.ts rather than queries.ts. The one-query-builder rule protects payment filtering from a second implementation; cards are a different entity, and there is still exactly one implementation of each card lookup.

Money stays integer minor units end to end. The single conversion is parseAmountToMinorUnits at the form boundary — the existing helper, not a new one — and the only float is the display-only spend ratio.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TQaU2bjRYVJKdD3hcie3yu

[JJFromTenex]

Claude Code 101 — Repo Rescue

🏆 Build Battle Score: 87 / 100

One-line verdict: The strongest-looking submission of the batch — full Tier 2 stretch, honest self-reporting, and a defensible design (no field capable of holding a full number) — but the diff cuts off exactly where the hardest logic lives (src/lib/cards.ts, src/lib/money.ts, the merchants file, and the test file), so several claims rest on the PR's own transcript rather than visible code.

Core criteria — 90 / 100 (35%)

1. Issue a card: ✅ — drawer with labelled nickname/merchant/limit/category fields, posts to /api/cards, appears in list via router.refresh().
2. Card list: ✅ — /cards shows nickname, merchant, masked number, limit, status, created date, all present in page.tsx.
3. Card detail: ✅ — full record, spend-vs-limit bar, authorizations and history all rendered.
4. Generated numbers: ⚠️ — generateCardNumber() is called consistently everywhere a number is needed and the PR claims a 500-iteration Luhn assertion, but the generator itself lives in src/lib/cards.ts, which is not in this diff. Trusted but unverified.
5. Reveal once: ✅ — Card type has no field for a full number, fullNumber only appears in the POST response, client state is discarded on dialog close.
6. Server-side validation: ✅ — the route calls validateIssueInput server-side; the form does not gate submission itself.

Correctness rules — 85 / 100 (20%)

• Minor units: ✅ — spendLimit is integer throughout the visible code; conversion happens once at parseAmountToMinorUnits on the form boundary.
• Luhn on 4242 BIN: ⚠️ — asserted in the PR's curl transcript (fullNumber: 4242942034921448), but the generator source (lib/cards.ts) is not in the diff, so this is evidence, not verification.
• Masking: ✅ — no fullNumber field on Card, GET routes only ever return card (which has last4), client resets state on close.
• State machine: ✅ — transitionCard checks canTransition, and the PR transcript demonstrates cancelled→active and cancelled→frozen both returning 409.
• Server-side validation: ✅ — enforced in the route handler, not just the form.

Context and planning — 70 / 100 (10%)

No docs/specs/ or docs/epics/ file appears in the diff (and none was noted as truncated-out specifically). The PR description itself, however, reads like a plan that was actually followed: it names real files (queries.ts vs. new data/cards.ts, the existing parseAmountToMinorUnits helper), states domain rules, and the delivered code matches that description closely. That lands at the "no spec file, but a considered plan naming real files that the commits follow" tier.

Code quality — 80 / 100 (15%)

Visible code is clean: no console.log, no TODO/FIXME, no commented-out code, labelled inputs, aria-labels on per-card actions, a confirm step before the terminal cancel transition, and no database/ORM added. The PR is honest about an unfixed bug (sortPayments) rather than either fixing it opportunistically or hiding it, and honest about not opening a browser. The one gap: the actual test file (src/lib/cards.test.ts, 30 cases claimed) is not in this diff, so "tests honest" can't be directly confirmed — only the transcript can.

PR description — 95 / 100 (5%)

Exceptionally thorough — states what was built, cites real evidence for every acceptance criterion, explicitly lists what's out of scope and what's deliberately not verified (browser check), and calls out a known bug it chose not to fix. This is close to the template for what this section wants.

Stretch goals — 95 / 100 (15%)

Tier 1: ✅ freeze/unfreeze without reload (CardActions + router.refresh()) · ✅ amber past 80% (AMBER_AT = 0.8 in [id]/page.tsx) · ✅ category lock (chosen at issue, displayed on detail) · ⚠️ Luhn/transition tests (claimed, file not in diff) · ✅ written empty state (cards/page.tsx).
Tier 2: ✅ idempotent issue — idempotency-key header, store.issuedKeys Map, replay returns 200 with the original card (data/cards.ts, api/cards/route.ts) · ✅ currency matches merchant — validateIssueInput takes a merchant-currency lookup and the form derives/display-locks currency from the chosen merchant (issue-card-dialog.tsx) · ✅ spend is honest — no spent field on Card; spentForCard() sums real CardTransaction records (data/cards.ts) · ✅ cancel with confirm — two-step confirm naming the card, goes through the guarded PATCH (card-actions.tsx) · ✅ audit trail — CardEvent[] history rendered on the detail page ([id]/page.tsx).

---

Breakdown: Core (90 × 0.35) + Rules (85 × 0.20) + Context (70 × 0.10) + Quality (80 × 0.15) + PR (95 × 0.05) + Stretch (95 × 0.15) = 87 / 100

One thing to do differently next time: Include the full diff for src/lib/cards.ts and the test file — the parts doing the actual Luhn/validation work were the most important thing to show a grader, and their absence is the only reason this isn't scored higher.

The diff was too large to review in full, so only the first part was graded.

---

Powered by Anthropic and Tenex