NWP-201: issue virtual cards

[krishna-koushik]

Ticket

Closes NWP-201

What changed

Ops issued virtual cards by messaging the platform team, who created them by hand: hours of latency, 12–20 times a week, and two cards last month created with the wrong spend limit because the request lived in a Slack thread. This puts it in the console — issue a card, list what has been issued, open one to check it.

The card domain lives in src/data/, beside types.ts, merchants.ts and queries.ts — src/lib/ holds cross-cutting format helpers (money, dates, csv), and PAN mechanics are domain, not formatting. It splits by concern:

• src/data/card-number.ts — TEST_BIN, Luhn, generateCardNumber, lastFour, maskCardNumber, the limit and nickname bounds.
• src/data/card-status.ts — the transition table and the type guards.
• src/data/cards.ts — server-only: id allocation, validation, issueCard, setCardStatus, queries.

The first two are pure and isomorphic on purpose: card-status-actions.tsx is a client component that imports the transition table, so neither may reach for node:crypto or the store. Randomness arrives as an injected DigitSource, the way src/lib/dates.ts takes now — which keeps the generator testable against a pinned output and lets the seed generator stay deterministic.

How I verified it

• npm test passes
• New behavior is covered by a test
• Checked it in the browser

Test Files  6 passed (6)
     Tests  85 passed (85)

npx tsc --noEmit is clean and npm run build succeeds with /cards and /cards/[id] reported as ƒ (Dynamic), confirming they are not statically prerendered against a mutable store.

Beyond the unit tests I drove the running app: issued a card through the drawer, confirmed the number is shown once, closed it and asserted via the DOM that no 16-digit 4242 number remained anywhere on the page, then walked a card Active → Frozen → Active → Cancelled from the list without a page reload and watched the action buttons disappear at the terminal state. Every status code was exercised with curl — 201, 200 replay without the number, the validation 400s, 404, 409, and the 200 same-status no-op.

Two things that came out of running it rather than reading it: the issued number was Luhn-valid with a last4 matching its masked cell, and a card created at the 5,000,000-minor-unit ceiling renders as $50,000.00.

Acceptance criteria

Core — all six:

• Issue a card — drawer takes nickname, merchant, spend limit, currency, category lock
• Card list — /cards with nickname, merchant, masked number, limit, status, created date
• Card detail — full record plus spend against the limit
• Generated card numbers — server-side, 4242 BIN, valid Luhn check digit
• Reveal once, mask forever — full number only on the success screen; •••• 1234 everywhere else
• Server-side validation — missing merchant, zero or negative limit, limit above 5,000,000 minor units, currency outside USD/EUR/GBP

Stretch — all five:

• Freeze and unfreeze from the list without a full reload
• Spend progress on detail, amber past 80% (one seeded card sits at 86% so it is visible)
• Merchant category lock chosen at issue and shown on the card
• Tests on the Luhn generator and the status transitions, beside the code they cover
• Empty and error states written, not default — two distinct empty states on the list, plus error.tsx and not-found.tsx, neither of which existed anywhere in the app before

Beyond the ticket: a server-side requestKey so a double submit returns the original card with no number rather than issuing a second one, and a CardEvent timeline recording every status change, rendered on detail in the merchant's timezone.

Bugs found along the way

Four pre-existing defects, all unrelated to this ticket, now fixed with regression tests on their own branch (NWP-203-metrics-fixes) so they can be reviewed on their own terms rather than buried here:

• src/data/queries.ts sorted amounts lexicographically, so 10000 came before 900. Reached from /api/payments?sort=amount and the CSV export.
• src/data/metrics.ts bucketed in the server's local timezone while matching keys generated in UTC.
• src/data/metrics.ts accumulated money as floats in major units.
• grossVolume, dailyVolume and disputedAmount each summed USD, EUR and GBP into figures rendered with a hardcoded $.

Notes for the reviewer

Why src/data/cards.ts is not a second query builder. The convention names payments specifically — "Payment filtering goes through the builder behind GET /api/payments." filterPayments/sortPayments are Payment-typed on every line, so reusing them would mean widening their types: a bigger and riskier change than card-specific code. The one genuinely generic piece, paginate<T>, is reused unmodified. src/data/cards.ts is an entity module holding data plus its accessors — the same shape as src/data/merchants.ts.

Reveal-once is structural rather than filtered. The Card type has no number field at all, so every payload is safe by construction and no toPublicCard() mapper is needed — a mapper is just a place to make a mistake. numberRef is independently random, never derived from the number: with a fixed BIN and a Luhn check digit the candidate space is small enough that a hash would be reversible.

There is no GET /api/cards. Server components call queryCards/cardById in-process, matching how payments/page.tsx calls queryPayments. Only the writes needed endpoints.

spent has no honest source, and I did not fake one. Payment has no cardId and there is no card-transaction entity. Attributing payments.filter(p => p.merchantId === card.merchantId) would be semantically inverted — those are payments the merchant received — and would push every card over its limit. So spent lives on the card, seeded for some and 0 for new ones, with a "No spend yet" state. Real attribution belongs with NWP-202/203.

A currency that doesn't match the merchant's settlement currency is rejected with a 400, naming both currencies. Worth being explicit that this is a deliberate narrowing, not an improvement: EUR ad spend for a USD merchant is a legitimate ops case that this now forbids. The earlier version recorded the mismatch and issued the card anyway; that field is removed rather than left as a value that can only ever be true.

Restart the dev server after pulling. src/data/store.ts pins the store to globalThis, so a server running from before this change holds a store with no cards key: createStore() never re-runs, TypeScript says Card[], and the first write throws on code that looks correct. There is a store.cards ??= [] guard, but a restart is the real fix.

Two documentation errors found along the way: .claude/rules/components.md claims src/components/ has a Dialog — it does not, only Drawer, which wraps the same Radix dialog root, so trusting that sentence gives a module-not-found. CLAUDE.md also describes the seed data as JSON; it is TypeScript.

🤖 Generated with Claude Code

[JJFromTenex]

Claude Code 101 — Repo Rescue

🏆 Build Battle Score: 87 / 100

One-line verdict: The most thoroughly planned and instrumented submission of this shape I've seen — but the diff is truncated exactly where the domain logic lives (card-number.ts, card-status.ts, cards.ts, types.ts, tests), so several core claims are graded on strong indirect evidence rather than sight of the code.

Core criteria — 90 / 100 (35%)

1. Issue a card: ✅ — Drawer takes nickname/merchant/limit/currency/category, posts to /api/cards, router.refresh() on success.
2. Card list: ✅ — page.tsx renders card id, nickname, merchant, masked number, limit, status, created date, all six required columns.
3. Card detail: ✅ — [id]/page.tsx shows the full record plus a real spend-vs-limit bar.
4. Generated numbers: ⚠️ — card-number.ts (BIN, Luhn, generator) is referenced throughout but not in the diff; can't confirm the algorithm, only its exported surface (MAX_SPEND_LIMIT_MINOR_UNITS, NICKNAME_MAX_LENGTH, maskCardNumber).
5. Reveal once: ✅ — Success screen is the only place cardNumber is rendered; drawer close clears state; list/detail only ever use last4.
6. Server-side validation: ✅ — POST /api/cards routes every body through validateIssueCard and returns field-scoped 400s; the bound checks themselves live in src/data/cards.ts, not shown, but the enforcement point is real and server-side.

Correctness rules — 85 / 100 (20%)

• Minor units: ✅ — Client converts to minor units before sending (parseAmountToMinorUnits), display formatting happens once via formatMoney.
• Luhn on 4242 BIN: ✅ (unverifiable from diff — card-number.ts not shown; no red flags in what's visible).
• Masking: ✅ — Card is consumed everywhere via last4/maskCardNumber; no full-number field appears in list, detail, or post-reveal client state.
• State machine: ✅ — PATCH route returns 409 on illegal transitions; UI removes all action buttons once allowedTransitions is empty (terminal cancelled).
• Server-side validation: ✅ — Route handler enforces via validateIssueCard, not just client checks.

Caveat: the four files that actually implement these rules are outside the visible diff. Scored on the strength of the visible call sites and the absence of any contradicting evidence.

Context and planning — 75 / 100 (10%)

A genuine spec exists (.claude/NWP-201-issue-cards.md), cites real paths and rules, and includes a file map and a verification table — well above the bar for "generic". But the spec's own file map says the isomorphic logic goes in src/lib/cards.ts; the delivered code puts it in src/data/card-number.ts and src/data/card-status.ts instead. Good planning, imperfect fidelity between plan and delivery.

Code quality — 85 / 100 (15%)

Visible code is clean: no console.log/TODO, labelled inputs with aria-describedby/aria-invalid, keyboard-operable Radix-based drawer/select, no ORM or seed tampering. The "Notes for reviewer" section shows real engineering judgment (rejecting a second query builder, rejecting a phantom Dialog component). Test files and the actual data-layer files are not in the diff, so the claimed 85-test suite and its honesty cannot be directly confirmed — noted rather than penalized outright, since nothing visible contradicts it.

PR description — 95 / 100 (5%)

Exceptionally candid: names an explicit non-improvement (currency narrowing), states spent has no honest source and why, flags a restart-required footgun, and separates unrelated bug fixes onto another branch rather than padding this diff. Exactly the honest reporting the rubric wants.

Stretch goals — 90 / 100 (15%)

Tier 1: Freeze/unfreeze without reload ✅, spend bar amber past 80% ✅, category lock at issue + displayed ✅, written empty/error states (error.tsx, not-found.tsx, two distinct empty states) ✅, Luhn/status-transition unit tests ❌ (claimed, not visible in diff) → 0.40.
Tier 2: Idempotent issue ✅ (route.ts explicitly branches on "replayed" in issued, requestKey minted client-side) — spend honesty ✅ (card.spent stated as seeded/0, "No spend yet" state, no invented derivation) — cancel-with-confirm ✅ (card-status-actions.tsx two-step confirm, terminal state removes buttons) — audit trail ✅ (card.events timeline rendered on detail with per-transition timestamps). Currency-matches-merchant not credited: only a client-side warning is visible; the server enforcement is asserted in the PR text but the validating file isn't in the diff. 3+ qualifying items already exceed the 0.50 tier cap.

---

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

One thing to do differently next time: Keep the delivered file layout in lockstep with the spec's file map — the src/lib/cards.ts vs src/data/card-number.ts/card-status.ts drift is small but it's exactly the kind of mismatch that makes a reviewer distrust the rest of the paper trail.

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

Generated files were skipped: build-battle/merchant-console/package-lock.json

---

Powered by Anthropic and Tenex