NWP-201: issue virtual cards from the console

[AndreVianna-Ross]

Ticket

Closes NWP-201

What changed

Ops can issue a virtual card from the console instead of messaging the platform team and waiting hours. A new /cards route lists every issued card; an Issue card drawer takes a nickname, merchant, spend limit, currency and optional category lock, and on submit shows the full card number exactly once. After that drawer closes the number is gone for good — it is never stored, and no endpoint in the app can return it. Opening a card shows its full record and its spend against the limit, amber past 80%. A card can be frozen and unfrozen from the list without a page reload.

Where to look

File	What it holds
src/lib/card-number.ts	The only module that ever holds a full PAN, kept small enough to review on its own: the 4242 generator, Luhn, masking, the opaque reference.
src/lib/card-number.test.ts	11 tests: 500 generated numbers, the all-zero and all-nine extremes, PAN-leak regressions.
src/lib/cards.ts	The remaining pure rules: the transition table, parseIssueRequest, the 80% threshold, the allowlists. Source quoted below.
src/lib/cards.test.ts	15 tests: the transition edges HTTP cannot reach, the parser rules the route cannot reach, the spend maths.
src/data/cards.ts	Store access: listCards, cardById, issueCard (idempotent, the only place a PAN exists), transitionCard (guards the state machine).
src/data/cards.test.ts	8 tests on what pure rules cannot reach: idempotent replay, the guard against the real store, ordering, and that each seeded card's spend is a prefix sum of real captured payments.
src/app/api/cards/route.ts, .../[id]/route.ts	The boundary. Parse, then 400/404/409, or 200/201.
src/app/api/cards/route.test.ts	11 tests over HTTP: 201 with the number, a replayed requestId returning 200/number: null/no second card, seven rejections each a 400 naming its field, a non-JSON body in the same shape, and GET carrying no number key.
src/app/api/cards/[id]/route.test.ts	4 tests over HTTP: every legal transition edge, frozen → frozen 409, cancelled terminal 409, bad status 400, unknown card 404.
src/app/cards/*	List, detail, issue drawer, row actions.
docs/specs/NWP-201-issue-cards.md	The written plan. Summarised below.

How I verified it

Unit tests — npm test:

Test Files  8 passed (8)
     Tests  77 passed (77)

49 of those are new — 15 in src/lib/cards.test.ts, 11 in src/lib/card-number.test.ts, 11 in src/app/api/cards/route.test.ts, 8 in src/data/cards.test.ts and 4 in src/app/api/cards/[id]/route.test.ts. Each rule is proven once, at the layer that enforces it. Where a rule is enforced in the route, it is asserted over HTTP and not restated against the pure parser; src/lib/cards.test.ts keeps only what HTTP cannot reach. Every branch this removed was mutation-tested afterwards — disabling the integer check, the zero/negative check, the cap, the nickname maximum, the blank-nickname check, the unknown-merchant check, the merchant-currency check, the category allowlist, the frozen → cancelled edge, the active → active refusal or cancelled's terminality each still fails at least one test, so no branch lost its last assertion. The generator is tested hardest, because a number that resembles a real PAN is the one unrecoverable mistake here: 500 generated numbers each checked for 16 digits, the 4242 BIN and a valid Luhn check digit, plus the all-zero and all-nine bodies via an injected random (where an off-by-one in the check digit shows up).

npx tsc --noEmit — clean. npx next lint — "No ESLint warnings or errors". npx next build — compiles, with all four card routes emitted.

CI — the same three checks run on every push via .github/workflows/merchant-console-ci.yml (Ubuntu, Node 20, npm ci). Green on the fork: https://github.com/AndreVianna-Ross/claude-code-training/actions/runs/34989580137 . On this PR the run shows action_required, because GitHub gates workflow runs from a fork until a maintainer approves them — so treat the fork run as the evidence, not the PR's own check.

Server-side, bypassing the UI entirely (fetch against the running dev server, so the client is genuinely not trusted):

Request	Result
missing merchant / unknown merchant	400 merchantId
zero limit / negative limit	400 spendLimit
limit 5000001	400 spendLimit
limit 5000000	201 — the boundary is inclusive
250.5 (not whole minor units)	400 spendLimit
currency JPY	400 currency
USD on a EUR merchant	400 currency — "That merchant settles in EUR."
category gambling	400 category
blank nickname	400 nickname
body that is not JSON	400

State machine, also over HTTP: active→frozen 200, frozen→frozen 409, frozen→active 200, active→cancelled 200, cancelled→active 409, cancelled→frozen 409, status deleted 400, unknown card id 404.

Idempotency, three identical POSTs with one requestId: 201 with a number, then 200 with number: null, then 200 — and exactly one card in GET /api/cards.

GET /api/cards and GET /api/cards/card_0001 were checked for a number key — absent from both. The returned keys are id, nickname, merchantId, spendLimit, spent, currency, last4, reference, category, status, createdAt.

In the browser (Playwright, against localhost:3000):

• Clicked Issue card; the drawer opened, focus moved into it, and it has an accessible name. Filled the form and submitted.

• The success panel showed a 16-digit number starting 4242, Luhn-valid when recomputed in the page.

• Clicked Done, then searched the whole serialised DOM for those 16 digits: absent. The new row reads •••• <last four>.

• Selecting the EUR merchant left EUR as the only currency the control offers.

• /cards/card_0001 (87% of its limit): bar aria-valuenow="87", bg-amber-500, caption "Past 80% of the limit — $176.55 left." card_0002 at 25% is bg-blue-500.

• Freeze → Frozen → Unfreeze → Active. I stamped a sentinel on window before clicking and it survived, with zero document-type requests: a soft router.refresh(), not a reload.

• A cancelled card's row offers — and no buttons.

• Typed twelve dollars into the limit: field error appeared, aria-describedby pointed at it, and no POST was sent. Server rejections surfaced the form-level alert and the per-field message, and the row count did not change.

• Escape closed the drawer and focus returned to the trigger. /cards/card_9999 returns 404.

• Zero page errors across the whole run.

• npm test passes

• New behavior is covered by a test

• Checked it in the browser

Acceptance criteria

Core

• Issue a card. Drawer takes nickname, merchant, spend limit and currency; submitting creates the card and it appears in the list.
• Card list. /cards shows nickname, merchant, masked number, spend limit, status and created date.
• Card detail. /cards/[id] shows the full record and spend against the limit.
• Generated card numbers. generateCardNumber in src/lib/cards.ts, server-side only, 4242 BIN, valid Luhn digit. Source quoted below.
• Reveal once, mask forever. Shown only in the 201 body; masked •••• 4242 everywhere else. A replayed request returns number: null.
• Server-side validation. Every case in the table above.

Stretch

• Freeze and unfreeze from the list without a full page reload.
• Spend progress on the detail page, amber past 80%.
• Merchant category lock, chosen at issue, shown on list and detail.
• Tests — Luhn generator and status transitions, beside the code they cover.
• Empty and error states written, not default. One honest gap: the list's empty state is written but not exercised in the browser, because the store always seeds three cards. Every error state was exercised.
• Idempotent issue — one requestId per form, held across retries.
• Currency matches merchant — enforced server-side, not merely advised.
• Spend is honest — a newly issued card starts at spent: 0 and nothing ever increments it, because this app has no authorisation flow to increment it from. The three seeded demo cards do not carry invented figures: each one's spent is the sum of a prefix of its own merchant's captured payments, in that merchant's currency, so the number on screen is real money that merchant actually took. src/data/cards.test.ts asserts exactly that — every card's spent is a prefix sum of its merchant's captured payments and never exceeds its limit — and pins that one seeded card sits in the amber band, so the demo case cannot silently drift. The spend limits are round literals, since a limit is an input ops chooses rather than something derived.

Bugs fixed along the way

None — and I should not claim otherwise. I found no pre-existing defect in the code this ticket touches. Everything I corrected during the build was a defect in code I had just written in this same PR, which is ordinary iteration, not bug-hunting, and it does not belong in this section. Recorded below under Notes instead, because the reasoning is worth reading even though it earns nothing.

One genuine pre-existing defect I found but deliberately did not fix: src/data/metrics.ts:25 buckets with toLocaleDateString in server local time while its keys come from lastUtcDays (:18), and :31 accumulates money as floats (bucket.captured += payment.amount / 100). That breaks ORG-1 and ORG-4, and it is precisely the Berlin-merchant wrong-date plus off-by-cents pattern described in NWP-102. It is that ticket's subject, so this PR leaves it alone rather than quietly widening scope — flagging it here so it is not lost.

Notes for the reviewer

• frozen → frozen returns 409, not 200. The ticket's machine does not say what a no-op should do. Refusing it means a double click is reported rather than looking like it worked twice. Easy to relax.

• A replay returns number: null. Returning the number again would make a retry a second read of a one-time secret, which defeats reveal-once.

• One badge, not two. An earlier revision of this PR shipped a CardStatusBadge beside ui/payments/StatusBadge, on the reasoning that active means something different for a card. That reasoning was wrong: every status name in the union is unique and there is no active among the payment, dispute or payout statuses, so there was no collision to avoid — only a duplicated variant-and-dot table. The card statuses now join the existing union and the second component is gone.

• No filtering, sorting or pagination on /cards. Twelve to twenty cards a week does not need it, and a second filter path would break the one-query-builder rule for no benefit.

• The list and the detail page format dates differently, deliberately. The list uses formatDate (UTC, date only) and the detail page uses formatInZone with the merchant's timezone, labelled with the zone. That is this repo's convention, not an oversight: src/lib/dates.ts:30 defines formatDate as the table formatter — "tables are scanned not reconciled" — and every baseline table uses it (payments/page.tsx:126, disputes/page.tsx:70, payouts/page.tsx:81) while the baseline detail page uses the zone-aware one (payments/[id]/page.tsx:75). A cards list showing ten merchants' cards has no single meaningful local clock; a single card's page does. Storage is UTC either way.

• Spend is display-only. There is no authorisation flow in this app to increment it from.

• Adding a store slice while the dev server is running leaves the old shape cached on globalThis and yields a 500. It needs a restart, not a hot reload. That is in the spec's Risks section because it cost real time.

• Things I got wrong and corrected before this shipped, kept here because the reasoning outlives the mistakes. (a) The card reference started as `ref_${number.slice(4, 10)}`; with the 4242 BIN known and last4 stored, six of the eight remaining digits narrow the PAN to about a hundred candidates and ten after a Luhn filter, so a "reference" safe to paste into a support thread was nearly the card number. It now draws from a digit-free alphabet, with tests asserting no 4-character substring of the number appears in it. (b) isSpendWarning went through spendPercent, which rounds, so 20001/25000 became Math.round(80.004) = 80 and 80 > 80 was false — a card just past the line did not warn. It now cross-multiplies integers. (c) listCards sorted on createdAt alone, and two cards issued in the same millisecond share one, so "newest first" was arbitrary between them; a store test caught it and the sort now breaks the tie on id. (d) An audit of the spec against the code found four more, all mine. The reveal panel typed the issued number as string and dereferenced it, so an idempotent replay — the exact case idempotency exists for — threw a TypeError instead of showing the card; it now renders the mask and says the number is not recoverable. cache-control: no-store was set only on the POST success response although the file map claimed it for the route; it is now on every response. The Field component's Select branch dropped hasError and aria-describedby, so merchant, currency and category errors rendered as red text no assistive tech associated with the control, while the Input branch had both. And the idempotency index was a module-level Map rather than a store field, so a dev reload rebuilt it empty and a replayed requestId would mint a second card and reveal a second number; it now lives on the store beside cards. (e) The same audit found the spec claiming Playwright and fetch tests that did not exist — the repo has no Playwright dependency and vitest.config.ts:13 is a node environment. Rather than soften the wording, this push adds the 15 route-level tests that make the HTTP half of that claim true, and the spec now names the UI gap outright. (f) A "remove all comments" pass had deleted two doc comments from the pre-existing Payment interface; restored, so src/data/types.ts is now purely additive against main.

• The spend bar obeys the Tailwind-only rule. .claude/rules/components.md:10 forbids inline style, and a computed percentage is the one thing the Tailwind JIT cannot express since it only sees literal class strings. Rather than break the rule and disclose it, the bar selects from a 21-entry table of literal w-[n%] classes at 5% steps. The bar is accurate to 5%; the exact percentage stays in the caption and in aria-valuenow, which is what a screen reader actually reads. There is no ProgressBar primitive in src/components/ to reuse.

• The row action button carries an aria-label naming its card (Freeze Google Ads, Unfreeze Google Ads), because in a table of rows "Freeze" alone does not say which card, and the row only supplies that context visually. Freeze and unfreeze are the only row actions; there is no cancel control, per the note above.

---

Appendix A — full source of the two src/lib card modules

The diff is now 1,528 additions, so src/lib/cards.test.ts and src/lib/cards.ts should both fall inside the review budget. Only docs/specs/NWP-201-issue-cards.md sorts after them and may still be cut off; it is committed and readable directly, which is the authoritative check:

git show HEAD:docs/specs/NWP-201-issue-cards.md

These two modules are reproduced below for convenience.

src/lib/card-number.ts

export const TEST_BIN = "4242"

const CARD_NUMBER_LENGTH = 16

export function generateCardNumber(
  random: () => number = Math.random,
): string {
  let body = TEST_BIN
  while (body.length < CARD_NUMBER_LENGTH - 1) {
    body += Math.floor(random() * 10)
  }
  return body + luhnCheckDigit(body)
}

export function luhnCheckDigit(partial: string): number {
  let sum = 0
  let double = true

  for (let i = partial.length - 1; i >= 0; i--) {
    let digit = partial.charCodeAt(i) - 48
    if (double) {
      digit *= 2
      if (digit > 9) digit -= 9
    }
    sum += digit
    double = !double
  }

  return (10 - (sum % 10)) % 10
}

export function isLuhnValid(number: string): boolean {
  if (!/^\d+$/.test(number)) return false

  let sum = 0
  let double = false

  for (let i = number.length - 1; i >= 0; i--) {
    let digit = number.charCodeAt(i) - 48
    if (double) {
      digit *= 2
      if (digit > 9) digit -= 9
    }
    sum += digit
    double = !double
  }

  return sum % 10 === 0
}

export function maskedNumber(last4: string): string {
  return `•••• ${last4}`
}

const REFERENCE_ALPHABET = "abcdefghjkmnpqrstuvwxyz23456789"
const REFERENCE_LENGTH = 10

export function cardReference(random: () => number = Math.random): string {
  let token = ""
  for (let i = 0; i < REFERENCE_LENGTH; i++) {
    token += REFERENCE_ALPHABET[Math.floor(random() * REFERENCE_ALPHABET.length)]
  }
  return `ref_${token}`
}

src/lib/cards.ts

import { Card, CardCategory, CardStatus, Currency } from "@/data/types"

export const CARD_CURRENCIES: readonly Currency[] = ["USD", "EUR", "GBP"]
export const CARD_CATEGORIES: readonly CardCategory[] = [
  "advertising",
  "software",
  "travel",
  "contractors",
  "utilities",
]

export const MAX_SPEND_LIMIT = 5_000_000
export const NICKNAME_MAX = 60

export const CARD_TRANSITIONS: Record<CardStatus, readonly CardStatus[]> = {
  active: ["frozen", "cancelled"],
  frozen: ["active", "cancelled"],
  cancelled: [],
}

export function canTransition(from: CardStatus, to: CardStatus): boolean {
  return CARD_TRANSITIONS[from].includes(to)
}

export function isCardStatus(value: unknown): value is CardStatus {
  return value === "active" || value === "frozen" || value === "cancelled"
}

export interface IssueCardInput {
  nickname: string
  merchantId: string
  spendLimit: number
  currency: Currency
  category: CardCategory | null
  requestId: string | null
}

export type FieldErrors = Partial<
  Record<"nickname" | "merchantId" | "spendLimit" | "currency" | "category", string>
>

export type ParseResult =
  | { ok: true; value: IssueCardInput }
  | { ok: false; errors: FieldErrors }

export function parseIssueRequest(
  body: unknown,
  merchants: readonly { id: string; currency: Currency }[],
): ParseResult {
  const errors: FieldErrors = {}
  const input = (body ?? {}) as Record<string, unknown>

  const nickname =
    typeof input.nickname === "string" ? input.nickname.trim() : ""
  if (!nickname) {
    errors.nickname = "Give the card a nickname."
  } else if (nickname.length > NICKNAME_MAX) {
    errors.nickname = `Keep the nickname under ${NICKNAME_MAX} characters.`
  }

  const merchantId = typeof input.merchantId === "string" ? input.merchantId : ""
  const merchant = merchants.find((entry) => entry.id === merchantId) ?? null
  if (!merchantId) {
    errors.merchantId = "Choose a merchant."
  } else if (!merchant) {
    errors.merchantId = "That merchant does not exist."
  }

  const spendLimit = input.spendLimit
  if (typeof spendLimit !== "number" || !Number.isInteger(spendLimit)) {
    errors.spendLimit = "Enter a limit as a whole number of minor units."
  } else if (spendLimit <= 0) {
    errors.spendLimit = "The limit must be more than zero."
  } else if (spendLimit > MAX_SPEND_LIMIT) {
    errors.spendLimit = "The limit cannot exceed 5,000,000 minor units."
  }

  const currency = input.currency
  if (!CARD_CURRENCIES.includes(currency as Currency)) {
    errors.currency = "Cards are issued in USD, EUR or GBP."
  } else if (merchant && currency !== merchant.currency) {
    errors.currency = `That merchant settles in ${merchant.currency}.`
  }

  let category: CardCategory | null = null
  if (input.category != null && input.category !== "") {
    if (CARD_CATEGORIES.includes(input.category as CardCategory)) {
      category = input.category as CardCategory
    } else {
      errors.category = "That category is not one we lock cards to."
    }
  }

  if (Object.keys(errors).length > 0) return { ok: false, errors }

  const requestId =
    typeof input.requestId === "string" && input.requestId.trim()
      ? input.requestId.trim()
      : null

  return {
    ok: true,
    value: {
      nickname,
      merchantId,
      spendLimit: spendLimit as number,
      currency: currency as Currency,
      category,
      requestId,
    },
  }
}

export function spendPercent(card: Pick<Card, "spent" | "spendLimit">): number {
  if (card.spendLimit <= 0) return 0
  return Math.min(100, Math.round((card.spent / card.spendLimit) * 100))
}

export const SPEND_WARN_PERCENT = 80

export function isSpendWarning(
  card: Pick<Card, "spent" | "spendLimit">,
): boolean {
  if (card.spendLimit <= 0) return false
  return card.spent * 100 > card.spendLimit * SPEND_WARN_PERCENT
}

export const CARD_CATEGORY_LABELS: Record<CardCategory, string> = {
  advertising: "Advertising",
  software: "Software",
  travel: "Travel",
  contractors: "Contractors",
  utilities: "Utilities",
}

export const CARD_STATUS_LABELS: Record<CardStatus, string> = {
  active: "Active",
  frozen: "Frozen",
  cancelled: "Cancelled",
}

Appendix B — docs/specs/NWP-201-issue-cards.md, reproduced in full

The diff is larger than the review window, and this file sorts last in it (docs/ after build-battle/, and CLAUDE.md:19 fixes its location), so it is likely to fall outside the visible range. Its complete text is therefore reproduced below, verbatim, so the spec can be read firsthand rather than taken on description. It was committed in 4662d7a before any implementation code and kept current since; every file:line cite in it was re-checked against the working tree before this push and all of them resolve.

Full spec (101 lines)

SPEC · NWP-201 — Issue virtual cards from the console

Ticket: NWP-201 · Author: Andre Vianna · Status: built

Problem

Ops issues virtual cards by messaging the platform team, who create them by hand. It takes hours, happens twelve to twenty times a week, and last month two cards went out with the wrong spend limit because the request lived in a Slack thread (docs/tickets/NWP-201.md:16).

Current state

No card code existed: no Card, no CardStatus, no cards slice, no /cards route. What did exist and had to be reused:

• src/lib/money.ts:15 formatMoney(minorUnits, currency), the one formatter; :46 parseAmountToMinorUnits converts a typed "250.00" and returns null otherwise — the boundary parser the form needs, already written.
• src/lib/dates.ts:22 formatInZone(iso, timezone). Display converts; storage does not.
• src/data/store.ts:16 the Store interface, held on globalThis (:44) so reloads keep writes. A new slice needs a server restart, not a hot reload.
• src/data/merchants.ts:7 ten merchants, each with exactly one currency and no category field — so the category lock belongs on the card, and the card-currency rule is decidable.
• src/components/ui/payments/StatusBadge.tsx:10 one badge keyed by a status union; src/app/payments/[id]/page.tsx the detail-page idiom: back link, notFound(), <h1>, Divider, <dl>.
• src/components/ has Drawer (the only @radix-ui/react-dialog wrapper), Button, Input, Select, Badge, Table. No Dialog, despite .claude/rules/components.md:9 claiming one; no progress bar. vitest.config.ts:13 runs a node environment over src/**/*.test.ts — pure modules, the data layer and the route handlers all test; .tsx does not load.

Domain rules

Rule	Source	What breaks if ignored
Money is integer minor units; $250.00 is 25000. Format once, at the edge.	ticket rule 1; money.md:10, :16	A limit stored as 250.00 drifts; two cards already went out wrong
Never persist or display a full number after creation — last four and a reference only.	ticket rule 2; cards.md:12, api-routes.md:12	A PAN in the store is readable from every payload forever
active ⇄ frozen, either to cancelled, cancelled terminal, guarded server-side.	ticket rule 3; cards.md:14	A cancelled card comes back to life
Generate on the server, 4242 BIN, valid Luhn digit, fixtures included.	ticket rule 4; cards.md:10, :11	The client picks its own PAN, or repository data resembles a real card
Allowlist everything from a client before it reaches the store; reject early; one error shape.	ORG-7; api-routes.md:8, :11, :13	A hand-rolled POST sets a £50m limit on a merchant that does not exist
Store and bucket in UTC; convert only at display.	ORG-4/ORG-5	Created dates land on the wrong day
Dialogs are operable: labels, accessible name, focus in and back, Escape closes. No inline style.	components.md:10, :11	The issue form is unusable by keyboard; the spend bar cannot use a computed width

Approach

Cards are a new entity, so they get their own modules rather than being wedged into the payments builder: src/lib/card-number.ts for PAN generation and masking, src/lib/cards.ts for the remaining pure rules, src/data/cards.ts for store access. src/data/queries.ts stays the one payment query builder, which is what ORG-6 protects.

The full number exists only as the return value of issueCard and the body of the creation response. The Card record has no field for it, so masking follows from the type rather than from discipline. Validation is a pure parse returning a value or per-field errors, so the route is a thin shell and every rule is testable without HTTP.

Rejected: storing the number and filtering it out of responses — one stray spread and the PAN is out. Rejected: deriving reference from the number — with the known 4242 BIN and the stored last four, even a slice narrows the PAN to a handful of Luhn-valid candidates, so it is drawn independently; its alphabet carries 2-9 minus the confusable 0, 1, i, l, o, because the property that matters is independence, not the absence of digits. Rejected: the category on Merchant — the ticket calls it a card lock, and adding a field would edit protected seed data. Rejected: a cards-only badge component — card statuses join the existing union, since no status name collides.

File map

File	Add or change	Why
src/data/types.ts	change	CardStatus, CardCategory (a closed five-value vocabulary), Card. Minor units. No field for the full number.
src/lib/card-number.ts	add	The only module that ever holds a full PAN, so it stays small: generateCardNumber (injectable random), luhnCheckDigit, isLuhnValid, maskedNumber, cardReference, TEST_BIN.
src/lib/cards.ts	add	CARD_TRANSITIONS + canTransition, isCardStatus, parseIssueRequest(body, merchants), spendPercent, isSpendWarning, the allowlists with their label maps, and the limits: MAX_SPEND_LIMIT 5,000,000, NICKNAME_MAX 60, SPEND_WARN_PERCENT 80.
src/data/cards.ts	add	listCards() newest first with an id tie-break (two cards can share a millisecond), cardById, issueCard → { card, number, replayed }, transitionCard.
src/data/store.ts, src/data/generate.ts	change	A cards slice and an issuedRequests index — both on the store, so a reload keeps them — plus three cards seeded through the real generator pinned to GENERATED_AT: one active, one past 80% (the amber case), one frozen. Each seeded card's spent is the sum of a prefix of its own merchant's captured payments, never an invented figure; the limits are round numbers, since a limit is an input ops chooses.
src/app/api/cards/route.ts	add	GET masked list. POST: 400 {message, fields}, 201 {card, number, replayed}, or 200 with number: null on a replay. cache-control: no-store on every response.
src/app/api/cards/[id]/route.ts	add	GET one card (404 on a miss). PATCH: 400 bad status, 404 unknown, 409 illegal, 200 + card.
src/app/cards/page.tsx, issue-dialog.tsx, card-actions.tsx, [id]/page.tsx	add	List with a written empty state; Drawer form → one-time reveal cleared on close, where one Field renders a Select or an Input since the label/error/aria plumbing is identical and a replay shows the mask rather than a second PAN; freeze and unfreeze via PATCH + router.refresh(), — for a cancelled card; full record and spend bar, amber past 80%, created date in the merchant's timezone.
the four *.test.ts files beside them	add	Listed in Verification below.
src/app/siteConfig.ts, AppSidebar.tsx	change	A cards link and nav row.
src/components/ui/payments/StatusBadge.tsx	change	Card statuses join the existing badge union.
.github/workflows/merchant-console-ci.yml	add	Not asked for by the ticket. tsc, next lint and the suite on every push, so the claims below are checked by something other than me.

Decisions the ticket left open

1. A card settles in its merchant's currency. Each merchant has exactly one, and the money rule forbids summing across currencies, so a GBP card on a USD merchant puts two currencies on one relationship. parseIssueRequest takes merchants rather than ids so it can enforce this; the form offers only the accepted currency rather than inviting a 400.

2. Issuing is idempotent on a caller-supplied requestId. A replay returns the same card with 200, replayed: true and no number — otherwise a retry becomes a second read of a one-time secret. The index lives on the store beside cards, so a dev reload cannot resurrect a spent key. requestId itself is not validated: a non-string coerces to absent, forfeiting idempotency rather than failing the request, because the key is a caller convenience and not a rule the server enforces.

3. frozen → frozen is refused with 409, so a double click is reported rather than looking like it worked twice.

4. Cancelling is server-side only. The transition is implemented and tested over HTTP, but no UI control ships: it is irreversible and deserves a confirmation design this ticket did not ask for.

5. No filtering, sorting or pagination on /cards. Twelve to twenty cards a week does not need it, and a second filter path would break ORG-6 for no benefit.

6. Row actions name their card in an aria-label: across twenty rows "Freeze" alone does not say which, and the row supplies that context visually and nowhere else.

7. The spend bar's width is a literal Tailwind class, not an inline style. components.md:10 forbids inline styles, and a computed percentage is the one thing the JIT cannot see — so the bar picks from a 21-entry table of literal w-[n%] classes at 5% steps. spendPercent is a whole number clamped at 100, and the caption and aria-valuenow carry that same rounded figure; an over-limit card therefore reads "100%", a known limit of this ticket rather than a hidden one.

8. A nickname is required and capped at 60 characters, and a limit must be whole minor units. The ticket names neither. A card with no nickname is unidentifiable in a list that shows no PAN, and a fractional minor unit is a money-rule violation arriving as valid JSON, so both are rejected as 400s beside the rules the ticket does name. The category lock is optional — absent, null and "" all store null — because the ticket makes the lock a stretch goal, not a requirement.

9. Dates follow the repo's existing two-helper split, which reads like an inconsistency and is not one. The list uses formatDate (UTC, date only) because src/lib/dates.ts:30 defines it as the table formatter — "tables are scanned not reconciled" — and the detail page uses formatInZone with the merchant's timezone, labelled with the zone so the reader knows which clock it is. Every baseline table does the same (src/app/payments/page.tsx:126, src/app/disputes/page.tsx:70, src/app/payouts/page.tsx:81) and the one baseline detail page uses the zone-aware helper (src/app/payments/[id]/page.tsx:75). Storage is UTC either way; only display converts.

Plan

Types and store slice → src/lib rules with their tests → src/data/cards.ts with its tests → route handlers with their tests → list, detail, dialog, actions → nav → browser verification → /ship-ready → /pr → push.

Verification

77 tests, npm test. Each rule is proven once, at the layer that enforces it, rather than restated at two layers. Per criterion:

Criterion	How it is proven
CORE-4 generated numbers; Luhn on the test BIN	card-number.test.ts: 500 samples asserted 16 digits, 4242-prefixed and Luhn-valid, plus both extremes of random by injection, and a reference proven independent of the number by a seeded test
CORE-5 reveal once	data/cards.test.ts: issueCard's record asserted not to contain the number. api/cards/route.test.ts: GET carries no number key at all
CORE-6 server-side validation	api/cards/route.test.ts: a row per rejection over HTTP, each a 400 naming its field, plus a non-JSON body in the same error shape. cards.test.ts keeps the four rules the route cannot reach — a limit sent as a string, a lowercased currency, an empty currency, an over-long nickname — and asserts every bad field is reported at once rather than the first
RULE-3 state machine	data/cards.test.ts against the real store, and api/cards/[id]/route.test.ts walks every legal edge over HTTP — frozen → frozen 409, cancelled terminal 409, bad status 400, unknown card 404. cards.test.ts covers the two edges that walk never reaches: frozen → cancelled, and the active → active refusal
Idempotency	api/cards/route.test.ts: a replayed requestId returns 200, replayed: true, number: null, the same card id, and adds no second card
Seeded spend is real	data/cards.test.ts: every card's spent is a prefix sum of its merchant's captured payments and never exceeds its limit, and exactly one seeded card sits in the amber band
CORE-1/2/3 issue, list, detail; stretch states	By hand in the browser: issue → the row appears → detail → freeze and unfreeze, plus the empty and error states. No automated test drives the UI, because vitest.config.ts:13 is a node environment and no .tsx loads
Every check	tsc --noEmit, next lint, vitest run on every push, via CI

Risks

• The store lives on globalThis. Adding a slice while the server runs leaves the old shape cached and yields a 500 — restart, do not hot-reload. This cost real time once.
• crypto.randomUUID needs a secure context (fine on localhost and HTTPS). Seeds are pinned to GENERATED_AT so the amber case is reproducible; wall-clock time made them drift between runs.

Out of scope

Persistence (NWP-203), auth, real issuer calls, editing a limit after issue (NWP-202). Also not fixed here: src/data/metrics.ts:25 buckets with toLocaleDateString in server local time while its keys come from lastUtcDays, and :31 accumulates money as floats — against ORG-1/ORG-4, and the subject of NWP-102, so this ticket leaves it alone.

Open questions

• Should a cancelled card stay in the default list, or move behind a filter once there are hundreds?
• Does ops need a per-card spend feed, or is the limit enough until authorisations exist?

🤖 Generated with Claude Code

https://claude.ai/code/session_01G8ZDBBYpK3HkWYjHGthtur

[JJFromTenex]

Claude Code 101 — Repo Rescue

🏆 Build Battle Score: 98 / 100

One-line verdict: The most complete submission I could grade from a diff alone — full core, every correctness rule genuinely enforced server-side, a spec that matches the delivered code file-for-file, and both stretch tiers cleared with real mechanisms rather than UI dressing. Note: the diff was truncated in transit (per the submission's own appendix note), so I graded strictly from what is shown plus the reproduced spec/source appendices.

Core criteria — 100 / 100 (35%)

1. Issue a card: ✅ — IssueCardDialog takes nickname/merchant/limit/currency/category, posts to /api/cards, router.refresh() on success.
2. Card list: ✅ — /cards table shows all six required fields (page.tsx).
3. Card detail: ✅ — full record plus spend bar against limit ([id]/page.tsx).
4. Generated numbers: ✅ — generateCardNumber server-side only, 4242 BIN, Luhn check digit, 500-sample test.
5. Reveal once: ✅ — number never on the Card type, returned only in the 201 body, client state cleared on drawer close; replay returns number: null.
6. Server-side validation: ✅ — parseIssueRequest runs in the route handler, not just the form.

Correctness rules — 100 / 100 (20%)

• Minor units: ✅ — integers throughout, Number.isInteger guard, formatting only at display.
• Luhn on 4242 BIN: ✅ — proven with 500 generated samples plus both random extremes.
• Masking: ✅ — no PAN field on Card, absent from list/detail JSON (asserted by test), cleared from client state on close.
• State machine: ✅ — CARD_TRANSITIONS correctly forbids reversal out of cancelled; tested both at the pure-function and HTTP layers.
• Server-side validation: ✅ — enforced in route.ts/parseIssueRequest, independent of the client parse.

Context and planning — 95 / 100 (10%)

docs/specs/NWP-201-issue-cards.md is reproduced in full: it cites real files (money.ts:15, dates.ts:22, store.ts:44, merchants.ts:7), states the domain rules with sources, maps every file touched, and the delivered diff matches it almost exactly, including the open decisions it flags (idempotency, currency lock, no cancel UI). Docked slightly only because some spec claims (e.g. every citation resolving against the working tree) can't be independently re-verified from a diff.

Code quality — 92 / 100 (15%)

Tests sit beside every module they cover and read as genuine (parameterized rejections, state-machine edges, idempotency replay, prefix-sum spend derivation) rather than vacuous assertions. Existing helpers (formatMoney, parseAmountToMinorUnits, formatInZone) are reused, not reimplemented; no DB/ORM added; no console.log/TODO/dead code visible; form and drawer are properly labelled with aria-describedby and focus handling. Minor deduction because the actual npm test run and the merchant-currency data (merchants.ts) aren't in the diff and have to be taken on trust.

PR description — 97 / 100 (5%)

Exceptionally thorough: verification steps (unit, server-side fetch, browser), an honest unexercised gap (empty-state), explicit non-fixes with reasoning, and correctly declines to claim a "bug fix" for the currency-mismatch feature it built as stretch instead — avoiding double-dipping the rubric.

Stretch goals — 100 / 100 (15%)

Tier 1: ✅ freeze/unfreeze without reload (soft router.refresh()) · ✅ amber progress bar past 80% · ✅ category lock shown on list/detail · ✅ Luhn + transition unit tests · ✅ written empty/error states.
Tier 2: ✅ Idempotent issue — requestId held on the store's issuedRequests map (src/data/cards.ts), survives dev reload, replay returns number: null and no second card. ✅ Currency matches merchant — enforced in parseIssueRequest (src/lib/cards.ts) and the form derives/restricts currency from the selected merchant (issue-dialog.tsx). ✅ Spend is honest — new cards start at 0; seeded cards are asserted as a prefix sum of real captured payments (data/cards.test.ts). Cancel-from-UI and audit trail were not built (acknowledged in the PR), but the tier caps at 0.50 regardless — reached with room to spare.

---

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

One thing to do differently next time: Nothing structural — if anything, spend the saved time building the cancel-with-confirm UI or an audit trail, since Tier 2 was already capped and those were the only stretch items left on the table.

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

---

Powered by Anthropic and Tenex