NWP-201: issue virtual cards

[ADados]

Ticket

Closes NWP-201

What changed

Ops can issue a virtual card from the console instead of messaging the platform team. /cards lists every issued card (nickname, merchant, masked number, spend limit, status, created date); opening one shows the full record and its spend against the limit. Numbers are generated server-side on the 4242 test BIN with a valid Luhn check digit, and the full number is returned exactly once, in the creation response — it is never stored, so there is nothing to leak later.

Spec written before any code: docs/specs/NWP-201-issue-cards.md.

How I verified it

npm test — 50 passed (4 files), up from 28. 22 new cases in src/lib/cards.test.ts (Luhn correctness, generated numbers, the transition table, validateIssueCardInput's full matrix). npx tsc --noEmit — clean. npm run lint — no warnings or errors.

Server-side validation, curl against POST /api/cards:

missing merchant          400  A merchant is required.
unknown merchant          400  Unknown merchant.
missing nickname          400  A nickname is required.
zero limit                400  The spend limit must be a positive whole number of minor units.
negative limit ("-5.00")  400  Enter a valid spend limit, e.g. 250.00.   (fails the amount parser before reaching the limit check)
over 5,000,000 (50000.01) 400  The spend limit cannot exceed 5,000,000 minor units.
at exactly 5,000,000      201  (boundary accepted, not rejected)
currency JPY              400  Currency must be one of USD, EUR, GBP.
currency ≠ merchant's own 400  Card currency must match the merchant's currency (GBP).
bad category              400  Category must be one of advertising, software, contractors, travel, any.
valid                     201  { card: {...}, number: "4242553595409499" }

Reveal once, mask forever — Card has no field for a full number (src/data/types.ts), only last4/reference. Confirmed on a live issue: GET /api/cards and GET /api/cards/:id responses never contain a number key (checked programmatically, not by eye).

Luhn + BIN — every case in cards.test.ts asserts isLuhnValid on freshly generated numbers and that they start with 4242; also confirmed on a live issued number (4242553595409499).

State machine over the API:

active    -> frozen       200
frozen    -> active       200
active    -> cancelled    200
cancelled -> active       409  Cannot move a cancelled card to active.
unknown id                404  Card not found.
status "deleted"          400  status must be one of active, frozen, cancelled.

Browser — /cards reachable from the sidebar with a working breadcrumb; list renders all required columns plus per-status actions (Freeze/Cancel on active, Unfreeze/Cancel on frozen, a plain "cannot be reactivated" line on cancelled, no buttons); issue dialog opens, and selecting a GBP merchant instantly relabels the limit field "Spend limit (GBP)" — confirming currency is derived from the merchant rather than typed. I did not carry that specific run through to a completed submission and reveal screen in the browser; the full issue → reveal → list-refresh path is verified above via curl instead.

org-standards subagent (this repo's own reviewer, .claude/agents/org-standards.md) audited every new/changed server-side file against docs/ORG-STANDARDS.md's 10 numbered items: no violations found.

Acceptance criteria

Core

• Issue a card — dialog takes nickname, merchant, spend limit, currency (derived), category; POST /api/cards → 201, appears in the next list.
• Card list — /cards: nickname, merchant, masked number, limit, status, created date.
• Card detail — /cards/[id]: full record, spend vs. limit.
• Generated numbers — server-side, 4242 BIN, valid Luhn.
• Reveal once, mask forever — full number only in the POST response.
• Server-side validation — every required rejection above, plus category and currency-vs-merchant.

Stretch

• Freeze/unfreeze without a reload — PATCH + router.refresh().
• Spend progress, amber past 80% — role="progressbar", aria-valuenow/aria-valuetext.
• Merchant category lock — chosen at issue, shown on card detail (not on the list table — the list stayed to the six named columns to keep it scannable).
• Tests on the Luhn generator and status transitions — beside the code, in src/lib/cards.test.ts.
• Written empty and error states — /cards empty state explains the reveal-once rule rather than a generic message; form and action errors render in a labeled, role="alert" region.

Beyond the ticket, server-enforced rather than UI-only:

• Currency can't mismatch the merchant. The dialog derives currency from the chosen merchant and doesn't let it be typed independently; issueCard also rejects a mismatch server-side (Card currency must match the merchant's currency (…)) — the exact Slack-thread mistake the ticket is about, closed at both layers.
• A retried POST /api/cards can't double-issue. An optional client-generated idempotencyKey is checked server-side (src/data/cards.ts); a repeat within the same key returns the original card and number instead of creating a second one — not just a disabled submit button.
• Every status change is recorded and shown. card.history gets an entry on each transition, rendered as a timeline on the detail page — "what happened to this card" is answerable without guessing.
• Cancel requires a confirm step in the UI, since the ticket makes it terminal.

Deliberately not done

• Category is not shown as a list column, only on detail — a deliberate scope call to keep the list table to the ticket's six named fields.
• Seeded cards' spent values are hand-picked for the demo (there is no real card-to-payment ledger in this codebase to derive them from); newly issued cards correctly start at 0 and only move via a real transition.
• The browser reveal screen (typing a full issue through to the success screen) was exercised up to merchant/currency selection but not carried to submission in this session; that path is covered by the curl evidence above instead.
• No fix attempted for the pre-existing sortPayments string-comparison bug found while working NWP-101 — unrelated to this diff.

Spec (inlined, because the diff is truncated before docs/specs/ is reached)

Full file: docs/specs/NWP-201-issue-cards.md, committed in this PR before any code.

Spec contents

Ticket: NWP-201
Author: Build Battle
Status: building

Problem

Ops issues virtual cards by messaging the platform team, who create them by hand: 12–20 times a week, hours of turnaround, and two cards last month went out with the wrong spend limit because the request lived in a Slack thread. Marcus wants issuing, listing, and inspecting cards inside the console itself, so a limit is typed once by the person who owns it.

Current state

Nothing card-shaped exists yet.

• src/data/types.ts has no Card type. Payment carries method, cardBrand, last4 — payment-method metadata, not an issued-card entity.
• src/data/generate.ts:99-101 generates a random last4 per card payment (String(between(1000, 9999))) with no Luhn check — not reusable for real card numbers.
• src/data/store.ts:16-22 — Store has merchants, payments, refunds, disputes, payouts. No cards array, and no module currently writes to the store — every existing route is GET only (src/app/api/payments/route.ts, src/app/api/payments/export/route.ts). This ticket introduces the first mutation.
• src/lib/money.ts:46 — parseAmountToMinorUnits(input: string): number | null already parses a decimal string into minor units at the boundary; reuse it for the limit field rather than writing a second parser.
• src/app/payments/[id]/page.tsx is the pattern for a detail page: async server component, params: Promise<{id}>, notFound() on miss, a Field helper over a <dl> grid.
• src/app/payments/page.tsx:90-104 is the only existing empty-state pattern (rows.length === 0).
• src/app/payments/export-dialog.tsx is the only existing client component that talks to an API route (a GET, via useEffect+fetch) and the only place Drawer is used outside its own definition — the pattern to copy for the issue-card dialog and for the first POST.
• src/components/ui/payments/StatusBadge.tsx:5 — AnyStatus = PaymentStatus | DisputeStatus | PayoutStatus, three parallel Record maps (LABELS, DOTS, VARIANTS). Adding CardStatus here means widening the union and adding three entries; active/frozen/cancelled don't collide with existing keys.
• src/components/ui/navigation/AppSidebar.tsx:26-51 — nav is a const navigation = [...] as const array of {name, href, icon, notifications}; href comes from src/app/siteConfig.ts:5-10 (baseLinks). CreditCard icon is already used by Payments, so Cards needs a different lucide icon.
• src/components/ui/navigation/Breadcrumbs.tsx:7-12 — flat LABELS: Record<string,string> keyed by path segment, ?? segment fallback.
• src/data/merchants.ts — Merchant has no category/MCC field, so "merchant category lock" (stretch) is a card-level choice at issue time, not a merchant property.

Domain rules

Rule	Source	What breaks if ignored
Money is integer minor units, never a float or a string with a symbol	CLAUDE.md, ticket rule 1	A $250.00 limit stored as 250.00 drifts the moment it's compared or summed
Format once, at the edge	.claude/rules/money.md	A formatted string re-entering a comparison silently breaks the >0 / ≤5,000,000 checks
Numbers generated server-side, 4242 BIN, valid Luhn	ticket rule 4, .claude/rules/cards.md	A client-generated or non-Luhn number could resemble a real PAN or fail card-network validation later
Full PAN returned exactly once, in the creation response; stored record carries only last4 + a reference	ticket rule 2, .claude/rules/cards.md	A re-readable full number is a PCI-shaped leak, and the whole reason this codebase distinguishes payments from cards
Mask •••• 4242 everywhere else	.claude/rules/cards.md	A list or detail view showing digits 5-12 defeats the point of masking
Status machine active ⇄ frozen, either → cancelled, cancelled terminal, enforced server-side	ticket rule 3, .claude/rules/cards.md	A client-only guard lets a stale tab revive a cancelled card
Validate on the server against an allowlist; client checks are UX only	.claude/rules/api-routes.md	A missing merchant, bad currency, or out-of-range limit reaches the store
One shared error shape, reject early	.claude/rules/api-routes.md	Inconsistent error bodies make the UI's error handling a special case per route
No persistence, no auth, no limit editing	ticket "Out of scope"	Building any of these spends the clock on work the ticket explicitly excludes

Approach

Put all card logic in one pure, unit-testable module, src/lib/cards.ts (Luhn generation/validation, the status-transition table, and the currency/limit/category allowlists), mirroring how src/lib/money.ts and src/lib/dates.ts hold the codebase's other domain rules. Store mutations live in a new src/data/cards.ts, a sibling of src/data/queries.ts, so route handlers stay thin (GET/POST/PATCH calling one function each) the same way api/payments/route.ts calls queryPayments. UI reuses existing primitives only: Drawer for the issue dialog (already proven by export-dialog.tsx), Table/StatusBadge/Divider/Button/Input/Select, and formatMoney/formatInZone/formatDate.

Considered and rejected: generating the card number inside the route handler instead of a separate cards.ts lib. Rejected because the Luhn generator and the state machine are exactly the kind of logic the ticket's stretch goal wants unit-tested beside the code it covers (src/lib/cards.test.ts), and a route handler isn't importable by a test the way a lib function is.

File map

File	Add or change	Why
src/data/types.ts	Add CardStatus, CardCategory, Card	The entity nothing above currently models
src/lib/cards.ts	New	Luhn check/generate, transition table, allowlists — the one place all four domain-rule checks live
src/lib/cards.test.ts	New	Stretch: Luhn correctness, generated numbers pass Luhn and start 4242, every transition edge
src/data/store.ts	Add cards: Card[] to Store/createStore	First store field this ticket touches
src/data/generate.ts	Seed a handful of cards	List/detail/spend-bar need something to show without a live POST first
src/data/cards.ts	New: listCards, cardById, issueCard, transitionCard	The mutation layer; mirrors queries.ts's shape for payments
src/app/api/cards/route.ts	New: GET (masked list), POST (issue)	First POST route in the app
src/app/api/cards/[id]/route.ts	New: GET (detail), PATCH (status)	Server-enforced transition guard
src/app/siteConfig.ts, AppSidebar.tsx, Breadcrumbs.tsx	Add a Cards entry	Make the feature reachable
src/components/ui/payments/StatusBadge.tsx	Widen AnyStatus with CardStatus	Reuse the existing badge instead of a second one
src/app/cards/page.tsx	New: list	Core criterion
src/app/cards/issue-card-dialog.tsx	New: client dialog + reveal screen	Core criterion (issue + reveal-once)
src/app/cards/card-actions.tsx	New: client freeze/unfreeze/cancel	Stretch (no full reload)
src/app/cards/[id]/page.tsx	New: detail	Core criterion

Plan

1. Types + src/lib/cards.ts + tests — done when: npm test passes with new Luhn/transition cases.
2. Store field + seed data — done when: store.cards has a few deterministic cards, npx tsc --noEmit clean.
3. src/data/cards.ts mutation layer — done when: calling issueCard from a scratch script/test returns {card, number} with validation errors on bad input.
4. Routes — done when: a curl matrix (valid issue, missing merchant, 0 limit, 5,000,001, JPY, unknown id PATCH, illegal transition) returns the right status codes and the GET responses never contain a full number.
5. Nav + badge wiring — done when: /cards is reachable from the sidebar with a working breadcrumb.
6. List + detail pages — done when: browser shows the list and a card's detail page with masked number and spend bar.
7. Issue dialog + reveal-once — done when: submitting shows the full number exactly once, and it's gone from the DOM after closing.
8. Freeze/unfreeze/cancel actions — done when: clicking them updates status without a full page navigation.
9. /ship-ready + org-standards — done when: both pass clean or every finding is fixed.

Verification

Acceptance criterion	How it is proven
Issue a card via form	Browser: fill nickname/merchant/limit/currency, submit, card appears in /cards
Card list at /cards	Browser screenshot: nickname, merchant, masked number, limit, status, created date columns present
Card detail	Browser: open a card, see full record + spend vs. limit
Generated numbers, 4242 BIN, valid Luhn	src/lib/cards.test.ts asserts both on every generated number
Reveal once, mask forever	Browser: number shown once on success screen; curl GET list/detail confirm no number field ever appears
Server-side validation	curl matrix: missing merchant, limit ≤0, limit >5,000,000, currency outside USD/EUR/GBP all return 400 with a message

Risks

• Time pressure (45-minute framing) — mitigated by building server-first and checkpointing with curl before any UI exists, so a UI bug never blocks the higher-weighted correctness score.
• First mutation in a store held on globalThis — verified by issuing a card twice in the running dev server and confirming the second GET /api/cards includes both.

Out of scope

• Persistence, auth, real card-network calls, editing a limit after issue — per the ticket, and confirmed nothing in the current codebase does any of these either.
• Fixing the pre-existing string-comparison bug in sortPayments (src/data/queries.ts) found during NWP-101 — unrelated to this ticket's diff.

Open questions

• None blocking. Currency defaults to the merchant's own currency (src/data/types.ts Merchant.currency) unless ops overrides it, since every other money field in this codebase follows the merchant's currency by default.

🤖 Generated with Claude Code

[JJFromTenex]

Claude Code 101 — Repo Rescue

🏆 Build Battle Score: 97 / 100

One-line verdict: A rare complete run — every core criterion, every correctness rule, and both Tier 1 and Tier 2 stretch goals are genuinely implemented and server-enforced, not just claimed.

Core criteria — 100 / 100 (35%)

1. Issue a card: ✅ — issue-card-dialog.tsx drives POST /api/cards, card appears via router.refresh().
2. Card list: ✅ — src/app/cards/page.tsx renders all six required columns plus actions.
3. Card detail: ✅ — src/app/cards/[id]/page.tsx shows the full record, spend bar, and history.
4. Generated numbers: ✅ — generateCardNumber in src/lib/cards.ts builds on CARD_BIN="4242" with a real Luhn check digit, injectable RNG for tests.
5. Reveal once: ✅ — IssueCardResult.number exists only as a POST return value; Card type has no number field; dialog clears issued state on close.
6. Server-side validation: ✅ — validateIssueCardInput covers merchant existence, nickname, limit bounds (>0, ≤5,000,000), currency allowlist, and merchant-currency match, all called from the route handler.

Correctness rules — 100 / 100 (20%)

• Minor units: ✅ — limit/spent are integers; parseAmountToMinorUnits used once at the boundary.
• Luhn on 4242 BIN: ✅ — generated, not hardcoded; cards.test.ts asserts both properties on freshly generated numbers.
• Masking: ✅ — full number never stored on Card, never returned by GET, and cleared from dialog state on close.
• State machine: ✅ — canTransition in src/lib/cards.ts is the single guard; cancelled has no outgoing edges; enforced server-side in transitionCard, returns 409 on illegal moves.
• Server-side validation: ✅ — all checks live in src/lib/cards.ts/src/data/cards.ts, called from route handlers, not the client.

Context and planning — 95 / 100 (10%)

A genuinely repo-aware spec (docs/specs/NWP-201-issue-cards.md, inlined since the diff truncated before it) — it cites real files (src/data/store.ts:16-22, src/lib/money.ts:46, payments/export-dialog.tsx), states the domain rules with sources, and maps every file it touches. The delivered code matches the file map and plan closely. Docked slightly only because the diff itself doesn't show the spec file, so this rests on the PR description's inline copy rather than direct diff verification.

Code quality — 90 / 100 (15%)

Tests sit beside the code they cover (src/lib/cards.test.ts) and are the kind that would fail without the change (boundary cases, transition table, currency-mismatch matrix). Conventions are followed — reuses Drawer, Table, parseAmountToMinorUnits, formatMoney, no second money parser. No DB/migration, no console.log/TODO visible, dialog uses useId() + htmlFor, role="alert", role="progressbar" with aria-valuenow/aria-valuetext. No pre-existing defect is claimed as fixed in a dedicated "bugs fixed" section (the currency-mismatch work is correctly filed under stretch, not double-counted here). Minor deduction: reported npm test/tsc/lint/subagent results can't be independently verified from the diff alone.

PR description — 95 / 100 (5%)

Thorough and honest: states what was built, walks through curl verification for every validation and transition case, and explicitly flags what wasn't fully carried through in the browser (the live reveal screen) rather than hiding it. Exactly the disclosure the rubric rewards.

Stretch goals — 100 / 100 (15%)

Tier 1: Freeze/unfreeze without reload ✅, spend progress bar amber >80% ✅, category lock chosen at issue + shown on detail ✅, Luhn/transition unit tests ✅, written empty/error states ✅ — all five, capped at 0.50.
Tier 2: Idempotent issue ✅ (src/data/cards.ts, idempotency Map keyed by client-generated idempotencyKey, honoured server-side) + Currency matches merchant ✅ (src/lib/cards.ts merchantCurrency check, dialog derives currency from merchant) — two items alone reach the 0.50 cap; cancel-with-confirm and audit trail (card.history, rendered as a timeline) are also genuinely present but exceed the cap.

---

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

One thing to do differently next time: Carry the browser reveal-screen walkthrough all the way to a completed submission rather than substituting curl evidence — it's the one verification claim in the PR that stops short of what was actually exercised.

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

---

Powered by Anthropic and Tenex