feat(gift-cards): vendor-agnostic gift card spend rail — TBC adapter, purchase orchestration, GraphQL API (ENG-574)

[forge0x]

Summary

Vendor-agnostic gift card spend rail for Flash: one GiftCardProvider port routed by country, The Bitcoin Company (TBC) as the first adapter, Bitrefill wired in config only until partner credentials arrive. Users pick a card, Flash pays the vendor's BOLT11 from the user's own wallet over the IBEX rail, the code comes back encrypted at rest and is shown only to the owner.

Linear: epic ENG-574 (project "Gift Cards — Spend Rail"), design doc "Gift Cards — Architecture Design". Tickets covered here: ENG-576, 577, 578, 579, 580, 581, 582, 583, and the docs half of 588.

What is in this PR

• Domain + config — src/domain/gift-cards, giftCards config block (routing, providers, catalog, limits off|log-only|enforce, flags-off baseline), GiftCard* errors registered and mapped, RateLimitConfig.giftCardPurchase, giftcard ops-event flow.
• TBC adapter — src/services/gift-cards/bitcoin-company: JWT auth cached in Redis under a lock, paginated catalog, quote, order, status with claim data; zod-validated vendor envelopes; retries only on idempotent reads; tokens and claim data redacted from logs. Shared provider contract test.
• Persistence — GiftCardOrder Mongo schema + repository with conditional transition(), partial-unique providerOrderId, unique {walletId, idempotencyKey}, migration. Claim codes AES-256-GCM with per-order key id; toJSON never emits ciphertext.
• Catalog — Redis cache per provider/country with stale marker; 6h sync in cron under a lock; list/search/paginate served from cache only.
• Purchase path — purchaseGiftCard: gate → product → quote → authorize → persist CREATED → vendor order → quote tolerance → INVOICE_ISSUED → idempotent payment → PAID/PAYMENT_PENDING/PAYMENT_FAILED → one fulfilment read. Payment uses the IBEX inline rail (src/app/payments/pay-invoice-via-ibex.ts, mirrors lnInvoicePaymentSend) inside withPaymentIdempotency with fingerprint ln|<bolt11>|giftcard|<orderId>; IBEX transaction.id stored as providerPaymentRef.
• Limits — level, account age, per-card and daily caps (Redis reservations), vendor caps, velocity, open-loop rule; log-only by default with would-reject ops events (same rollout discipline as ENG-573).
• Worker — reconcileGiftCardOrders: expiry, pending settlement via IBEX lookup, vendor polling with backoff, REFUND_REQUIRED escalation; cron job + 30s trigger interval. Fulfilment push notification with no claim data.
• GraphQL — giftCardCatalog, giftCardQuote, giftCardOrder, giftCardOrders, giftCardPurchase, globals.giftCardsEnabled; relay connections; mutation at wallet level; API-key scope map entries BLOCKED; SDL + supergraph regenerated.
• Docs — docs/gift-cards/{README,ARCHITECTURE,FLOWS,API,CONFIG,ALERTING,RUNBOOK,TESTING}.md.

Feature is off by default (giftCards.enabled: false, every provider disabled). No behaviour change until config overrides turn it on.

Review notes

• Order reads (giftCardOrder, giftCardOrders) are deliberately not behind the master gate: switching the rail off must never hide codes a customer already paid for. Ownership is enforced in the app layer.
• Payments.payInvoiceByWalletId was not used on purpose: it pays through LND, which this deployment does not run.
• Country routing is phone-based (Account has no country); NANP numbers fall back to routing.default. Persisting a country on the account is an open decision (ENG-575).
• make codegen / yarn check:sdl fail locally on two pre-existing Express type errors in src/servers/graphql-server.ts and graphql-admin-server.ts (they fail on main too). SDL was regenerated with the same steps run by hand.
• Known gaps, documented in the runbook rather than hidden: no claim-key rotation script yet; no hash-based fallback when providerPaymentRef is missing; feeBps and referralCode are config-only; failureReason is machine text.

Tests

• Full yarn test:unit: 290 suites, 3667 passed, 3 skipped.
• New: ~600 unit tests across domain, adapter, persistence, crypto, cache, orchestration, limits, worker, GraphQL; Mongo integration spec for the transition race (test/flash/integration/gift-cards, not run locally, needs Mongo).
• yarn tsc-check: clean except the two pre-existing errors above. eslint: clean on all touched files.

Not in this PR

Mobile (ENG-589–591), ERPNext writer (ENG-584, blocked on doctype decision), Bitrefill adapter (ENG-585, blocked on credentials), alert wiring/dashboards (ENG-588), rollout (ENG-592).

🤖 Generated with Claude Code

https://claude.ai/code/session_01W5e4H8MF7oX2LPUxBRW3Pf

[linear]

ENG-574

[forge0x]

Review round 1 applied — 3fc2191ef

Simon-style review returned NEEDS WORK (2 blocking, 6 should-fix). All eight are addressed in this commit.

Blocking

• Indeterminate send errors no longer land in PAYMENT_FAILED. Only proven refusals do; a generic IBEX error or unconfirmed payment moves the order to PAYMENT_PENDING, the pending order is returned so the client polls instead of re-buying, and the reconciler falls back to a vendor poll when IBEX cannot account for the payment (including INVOICE_ISSUED at expiry, which closes the documented write-off window).
• giftCardQuote now consumes its own attempt budget (30/min) before touching the vendor and carries query complexity 120. New code GIFT_CARD_QUOTE_RATE_LIMITED.

Should fix

• 24h fulfilment timeout polls the vendor first; REFUND_REQUIRED only when the vendor does not report fulfilled.
• giftCards.enabled now stops new money leaving only. The reconciler runs whenever non-terminal orders exist and settles through the registered provider, so paid customers still get codes and the 24h alert still fires.
• Same-key replay of an unpaid, unexpired INVOICE_ISSUED order resumes from the pay step (idempotent by construction). CREATED is never re-entered.
• giftCardOrder returns the order with claim: null and records a claim-crypto error at Critical instead of throwing.
• Vendor expiresAt is nullable; the order expiry is the earliest of order TTL, decoded BOLT11 expiry, and any vendor-stated expiry.
• TBC catalog pagination advances by rows returned and stops on an empty page; at the page cap the sync fails and keeps the last good catalog.

PAYMENT_FAILED enum description updated and SDL regenerated. Docs updated to as-built. Two authentication specs that enumerate @config getters gained the two new limit getters.

Full yarn test:unit: 292 suites, 3738 passed, 3 skipped. Round 2 review in progress.

[forge0x]

Review round 2 applied — 7fbdf3a2d

Round 2 (reviewing 3fc2191ef) returned NEEDS WORK: 4 blocking, 18 should-fix. All addressed.

Blocking

• A busy idempotency lock during a same-key replay no longer clobbers the first attempt's outcome with a null-ref PAYMENT_PENDING; it returns the current row unchanged (round-1 regression).
• 24h escalation writes REFUND_REQUIRED only when the final vendor poll positively says not fulfilled; vendor errors, claim-key faults, and repo faults keep PAID and retry. The claim key is checked loadable immediately before every pay; failure fails the order before IBEX is called.
• After IBEX answers, purchaseGiftCard never returns a bare error: lost transitions re-read and return the row; a repo fault returns the order and pages paid-not-recorded.
• quantity is capped per product (maxQuantity, 1 for TBC until a multi-card fulfilment response is captured); the adapter refuses more before calling the vendor.

Should fix (highlights)

• Resolver gate removed from giftCardPurchase so a replay works while the rail is off.
• No-ref PAYMENT_PENDING self-terminates after expiresAt + 24h when the vendor reports not-paid; polls bump updatedAt so the batch rotates.
• New EXPIRED → PAID transition so a late Success after worker expiry is fulfilled, not written off.
• Product country is enforced against the account's gated country (as documented). Registry requires registration + enabled.
• Vendor 4xx text never reaches customers; vendor quote 4xx → GIFT_CARD_INVALID_VALUE. TBC Disputed held pending. Physical/non-Lightning rows skipped at sync; VariableNoCents refuses cents up front; zero-product syncs fail closed.
• Claim ciphertext AAD binds keyId + orderId (no cross-order transplant).
• Replay does not consume the purchase rate limit; fake repo enforces the real transition table; ~350 new/retargeted specs.

GraphQL: GiftCardProduct.maxQuantity, wholeUnitsOnly; SDL regenerated. Docs brought to as-built.

Full yarn test:unit: 294 suites, 3920 tests (3 skipped), green. One earlier run hit a jest worker SIGSEGV in an unrelated suite; it passes in isolation on branch and main and the rerun is clean. Round 3 review in progress.

[islandbitcoin]

Review rounds 3–5 applied

Three more simon-review rounds ran over f622de7d9/7ac5dda94. Round 1 (of this batch) found one blocking: the expiry path wrote off a PAID order when the vendor reported paidPendingFulfillment — that vouch now transitions INVOICE_ISSUED/EXPIRED → PAID (vendor-reported-payment) and the normal PAID poll path finishes fulfilment (f622de7d9). Also fixed the with-ref IN_FLIGHT dead-end (vendor polled past the warn horizon; fulfilled settles, unpaid past grace escalates) and the expire-on-vendor-error hole (a failed poll no longer expires the row unconditionally).

Rounds 2–3 returned ACCEPTABLE, 0 blocking; their remaining items were doc drift, fixed in 37fc89966:

• FLOWS.md: the with-ref pending vouch is fulfilled only — a paidPendingFulfillment answer is left for the re-read.
• ALERTING.md: vendor-reported-payment on a ref-less PAYMENT_PENDING row also covers the vendor's refunded (lands PAID then REFUND_REQUIRED).

Final verdict: no blocking, no should-fix outstanding. Review history this PR: rounds 1–2 (2026-09-12), rounds 3–5 (this batch, 2026-09-14).

🤖 Generated with Claude Code