@volter/twin-stripe 2.0.38 → 3.0.1

package/src/semantics/issuing.ts

@@ -1,590 +1,74 @@
-// Issuing semantics: cardholders, cards, authorizations, transactions, disputes, network tokens and
-// personalization designs. An authorization's `card` is the full Card in every answer and webhook
-// (the manifest's write hook embeds it on writes; reads embed it here). The machines in
-// ../manifest.ts say how authorizations, disputes, cards, cardholders, tokens and designs move.
-//
-// The test-helper routes here (/v1/test_helpers/issuing/…) are Stripe's own doors for what no API
-// verb makes: a card presented at a merchant, a capture, a force capture, a design's review. A
-// presented authorization is decided in Stripe's order: card status, then spending controls
-// (card, then cardholder), then the real-time issuing_authorization.request webhook delivered
-// synchronously to the first enrolled endpoint; with none it is approved (card_active).
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { emptySpendingControls, normalizeSpendingControls, nextStripeEventId, persistStripeEvent, spendingControlsViolation } from '../stripe-twin.ts';
-import { requestAuthorizationDecision, STRIPE_WEBHOOK_FALLBACK_SECRET, stripeEventMatches, type StripeEvent } from '../stripe-events.ts';
-import { at, created, fail, filePurposeRefused, list, newest, send, where, type Row } from './shared.ts';
-import { balanceOf } from './ledger.ts';
-
-const CH = 'issuing.cardholder';
-/** The id of a card's cardholder: the card answers the cardholder in full (the served spec's issuing.card.cardholder is
- *  the Cardholder object, not an id); its id is read from it for filtering and for the objects that name it by id. */
-export const holderId = (c: Row): string => (typeof c.cardholder === 'string' ? c.cardholder : String((c.cardholder as Row | undefined)?.id ?? ''));
-const CARD = 'issuing.card';
-const AUTH = 'issuing.authorization';
-const TXN = 'issuing.transaction';
-const DSP = 'issuing.dispute';
-const TOK = 'issuing.token';
-const PD = 'issuing.personalization_design';
-
-// ── cardholders ──
-
-const createCardholder: Semantics = async (ctx) => {
-  const params = ctx.params;
-  if (params.name === undefined || params.name === '') return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
-  const chType = typeof params.type === 'string' ? params.type : '';
-  if (chType !== 'individual' && chType !== 'company') return fail(ctx, "Invalid type: must be one of 'individual' or 'company'.", 400, 'parameter_invalid_string_enum');
-  const billing = params.billing && typeof params.billing === 'object' ? (params.billing as Row) : undefined;
-  if (!billing || !billing.address || typeof billing.address !== 'object') return fail(ctx, 'Missing required param: billing[address].', 400, 'parameter_missing');
-  const controls = normalizeSpendingControls(params.spending_controls, null);
-  if (controls.error) return send(ctx, controls.error);
-  return ctx.reply(
-    await created(ctx, CH, { ...params, spending_controls: controls.controls ?? emptySpendingControls() }, {
-      status: 'active', livemode: false, metadata: {}, phone_number: params.phone_number ?? null,
-      email: params.email ?? null, requirements: { disabled_reason: null, past_due: [] },
-    }),
-  );
-};
-
-/** A requested move of a state field the machine declares, legal or refused; a value the machine
- *  does not name is written as given, as the hand-written route did. */
-function requestedMove(ctx: SemanticsContext, resource: string, operationId: string, current: unknown, values: string[]): Response | undefined {
-  const to = ctx.params.status;
-  if (typeof to !== 'string' || !values.includes(to)) return undefined;
-  const refused = ctx.legal(resource, 'status', operationId, current, to);
-  return refused ? ctx.refuse(refused) : undefined;
+// Stripe's issuing operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import type { Row } from '../engine/common.ts';
+import { CARD, CH, cardNumberOf, cvcOf } from '../engine/issuing.ts';
+import { emptySpendingControls, normalizeSpendingControls, nowUnix } from '../engine/stripe.ts';
+import { at, created, fail, issuingDecide, issuingRefusal, send } from './shared.ts';
+
+export async function GetIssuingCardsCard(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'card');
+  const card = ctx.get(CARD, id);
+  if (!card) return fail(ctx, `No such card: '${id}'`, 404, 'resource_missing');
+  const expand = Array.isArray(ctx.params.expand) ? ctx.params.expand.map(String) : [];
+  // source: spec:/components/schemas/issuing.card/properties/number/description "For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with"
+  const virtual = card.type === 'virtual';
+  const shown: Row = { ...card };
+  if (virtual && expand.includes('number')) shown.number = cardNumberOf(await ctx.secret(`issuing-card-number:${id}`));
+  // source: spec:/components/schemas/issuing.card/properties/cvc/description "The card's CVC. For security reasons, this is only available for virtual cards"
+  if (virtual && expand.includes('cvc')) shown.cvc = cvcOf(await ctx.secret(`issuing-card-cvc:${id}`));
+  return ctx.reply(ctx.expand(CARD, shown));
 }
 
-const updateCardholder: Semantics = async (ctx) => {
-  const id = at(ctx, 'cardholder');
-  const ch = ctx.get(CH, id);
-  if (!ch) return fail(ctx, `No such cardholder: '${id}'`, 404, 'resource_missing');
-  const controls = normalizeSpendingControls(ctx.params.spending_controls, null);
-  if (controls.error) return send(ctx, controls.error);
-  const refused = requestedMove(ctx, CH, 'PostIssuingCardholdersCardholder', ch.status, ['active', 'inactive', 'blocked']);
-  if (refused) return refused;
-  const updated = await ctx.write(CH, id, controls.controls ? { ...ctx.params, spending_controls: controls.controls } : ctx.params, 'issuing_cardholder.updated');
-  // each of the cardholder's cards answers it as it now stands
-  for (const card of ctx.rowsRaw(CARD).filter((c) => holderId(c) === id)) await ctx.write(CARD, String(card.id), { cardholder: updated }, 'issuing_card.cardholder_synced');
-  return ctx.reply(updated);
-};
+export async function PostIssuingAuthorizationsAuthorizationApprove(ctx: HandlerContext): Promise<Response> {
+  return issuingDecide(true)(ctx);
+}
 
-// ── cards: a virtual card is active at once, a physical one inactive until shipped ──
+export async function PostIssuingAuthorizationsAuthorizationDecline(ctx: HandlerContext): Promise<Response> {
+  return issuingDecide(false)(ctx);
+}
 
-const createCard: Semantics = async (ctx) => {
+export async function PostIssuingCards(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
-  const cardholder = typeof params.cardholder === 'string' ? params.cardholder : '';
-  if (!cardholder) return fail(ctx, 'Missing required param: cardholder.', 400, 'parameter_missing');
-  if (!ctx.get(CH, cardholder)) return fail(ctx, `No such cardholder: '${cardholder}'`, 400, 'resource_missing');
+  // source: spec:PostIssuingCards "The currency for the card."
   if (params.currency === undefined || params.currency === '') return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
   const cardType = typeof params.type === 'string' ? params.type : '';
+  if (!cardType) return fail(ctx, 'Missing required param: type.', 400, 'parameter_missing');
+  // source: spec:PostIssuingCards "The type of card to issue."
   if (cardType !== 'virtual' && cardType !== 'physical') return fail(ctx, "Invalid type: must be one of 'virtual' or 'physical'.", 400, 'parameter_invalid_string_enum');
-  const last4 = String(4242 + ctx.rowsRaw(CARD, { withDeleted: true }).length + 1).slice(-4);
+  // the card answers its cardholder in full (the served spec's issuing.card.cardholder is the Cardholder object)
+  const holder = typeof params.cardholder === 'string' ? params.cardholder : '';
+  const cardholder = holder ? ctx.get(CH, holder) : undefined;
+  if (holder && !cardholder) return fail(ctx, `No such cardholder: '${holder}'`, 400, 'resource_missing');
   const controls = normalizeSpendingControls(params.spending_controls, typeof params.currency === 'string' ? params.currency : null);
   if (controls.error) return send(ctx, controls.error);
-  return ctx.reply(
-    await created(ctx, CARD, { ...params, cardholder: ctx.get(CH, cardholder), spending_controls: controls.controls ?? emptySpendingControls() }, {
-      status: cardType === 'virtual' ? 'active' : 'inactive', livemode: false, metadata: {},
-      brand: 'Visa', last4, exp_month: 12, exp_year: 2030, cancellation_reason: null,
-    }),
-  );
-};
-
-// a card list filters on the cardholder's id, the card answering the cardholder in full
-const listCards: Semantics = async (ctx) =>
-  list(ctx, CARD, where(ctx, newest(ctx, CARD), {
-    cardholder: (c, v) => holderId(c) === v,
-    status: (c, v) => c.status === v,
-    type: (c, v) => c.type === v,
-    last4: (c, v) => c.last4 === v,
-  }));
+  const id = ctx.mint(CARD);
+  const number = cardNumberOf(await ctx.secret(`issuing-card-number:${id}`));
+  // Where the documentation stops and the twin decides: a card expires three years after it is issued, at the end of
+  // the month it was issued in.
+  const issued = new Date(Number(nowUnix(ctx.occurredAt)) * 1000);
+  return ctx.reply(ctx.expand(CARD, await created(ctx, CARD, { ...params, id, cardholder: holder || null, spending_controls: controls.controls ?? emptySpendingControls() }, {
+    // source: https://docs.stripe.com/api/issuing/cards/create "Whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to inactive."
+    status: typeof params.status === 'string' ? params.status : 'inactive',
+    livemode: false, metadata: {}, brand: 'Visa', last4: number.slice(-4),
+    exp_month: issued.getUTCMonth() + 1, exp_year: issued.getUTCFullYear() + 3,
+    cancellation_reason: null, replacement_for: null, replacement_reason: null, shipping: null, wallets: null,
+  })));
+}
 
-const updateCard: Semantics = async (ctx) => {
+// source: spec:PostIssuingCardsCard "Any parameters not provided will be left unchanged."
+export async function PostIssuingCardsCard(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'card');
   const card = ctx.get(CARD, id);
   if (!card) return fail(ctx, `No such card: '${id}'`, 404, 'resource_missing');
-  if (ctx.params.status !== undefined && !['active', 'inactive', 'canceled'].includes(String(ctx.params.status))) return issuingRefusal(ctx, 'card_status');
-  const controls = normalizeSpendingControls(ctx.params.spending_controls, typeof card.currency === 'string' ? card.currency : null);
-  if (controls.error) return send(ctx, controls.error);
-  const refused = requestedMove(ctx, CARD, 'PostIssuingCardsCard', card.status, ['active', 'inactive', 'canceled']);
-  if (refused) return refused;
-  return ctx.reply(await ctx.write(CARD, id, controls.controls ? { ...ctx.params, spending_controls: controls.controls } : ctx.params, 'issuing_card.updated'));
-};
-
-// ── authorizations ──
-
-/** An authorization as every egress carries it: its card embedded in full. */
-function withCard(ctx: SemanticsContext, a: Row): Row {
-  const out = { ...a };
-  if (typeof out.card === 'string') {
-    const card = ctx.get(CARD, out.card);
-    if (card) out.card = card;
-  }
-  return out;
-}
-
-const authMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such authorization: '${id}'`, 404, 'resource_missing');
-
-const listAuthorizations: Semantics = async (ctx) =>
-  list(ctx, AUTH, where(ctx, newest(ctx, AUTH), {
-    card: (a, v) => a.card === v,
-    cardholder: (a, v) => a.cardholder === v,
-    status: (a, v) => a.status === v,
-  }).map((a) => withCard(ctx, a)));
-
-const retrieveAuthorization: Semantics = async (ctx) => {
-  const a = ctx.get(AUTH, at(ctx, 'authorization'));
-  return a ? ctx.reply(withCard(ctx, a)) : authMissing(ctx, at(ctx, 'authorization'));
-};
-
-const updateAuthorization: Semantics = async (ctx) => {
-  const id = at(ctx, 'authorization');
-  if (!ctx.get(AUTH, id)) return authMissing(ctx, id);
-  return ctx.reply(await ctx.write(AUTH, id, ctx.params, 'issuing_authorization.updated'));
-};
-
-/** One request_history entry; the authorization code is derived from the request time (Stripe's is not unique either). */
-function historyEntry(o: { amount: number; currency: string; approved: boolean; reason: string; reasonMessage: string | null; createdSec: number; merchantAmount: number; merchantCurrency: string }): Row {
-  return {
-    amount: o.amount, amount_details: null, approved: o.approved,
-    authorization_code: o.approved ? `S${String(100000 + (o.createdSec % 900000))}` : null,
-    created: o.createdSec, currency: o.currency,
-    merchant_amount: o.merchantAmount, merchant_currency: o.merchantCurrency,
-    network_risk_score: null, reason: o.reason, reason_message: o.reasonMessage,
-    requested_at: o.createdSec,
-  };
-}
-
-/** The test helper's default merchant, under any merchant_data the caller gives. */
-function merchantData(param: unknown): Row {
-  const base: Row = {
-    category: 'general', category_code: '5399', city: 'San Francisco', country: 'US',
-    name: 'Twin Test Merchant', network_id: '1234567890', postal_code: '94103', state: 'CA',
-    tax_id: null, terminal_id: null, url: null,
-  };
-  if (param && typeof param === 'object' && !Array.isArray(param)) Object.assign(base, param);
-  return base;
-}
-
-/** A capture: an Issuing transaction (negative: it debits) and the issuing balance's debit. */
-async function capture(ctx: SemanticsContext, authId: string, auth: Row, amountCents: number): Promise<{ txnId: string; btId: string }> {
-  const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
-  const bt = await created(ctx, 'balance_transaction', {}, {
-    amount: -amountCents, currency, fee: 0, net: -amountCents, type: 'issuing_transaction',
-    status: 'available', balance_type: 'issuing', reporting_category: 'issuing_transaction',
-    available_on: ctx.now(), fee_details: [],
-  });
-  const txn = await created(ctx, TXN, { authorization: authId, card: auth.card, cardholder: auth.cardholder }, {
-    type: 'capture', amount: -amountCents, currency,
-    merchant_amount: -amountCents, merchant_currency: typeof auth.merchant_currency === 'string' ? auth.merchant_currency : currency,
-    merchant_data: auth.merchant_data ?? merchantData(undefined),
-    livemode: false, metadata: {}, dispute: null, wallet: null, network_data: null,
-    amount_details: null, purchase_details: null, balance_transaction: bt.id,
-  });
-  return { txnId: String(txn.id), btId: String(bt.id) };
-}
-
-/** The card's stored id (an embedded card answers with its id). */
-const cardId = (auth: Row): unknown => (auth.card && typeof auth.card === 'object' ? (auth.card as Row).id : auth.card);
-
-/** Issuing refusals of a request no story sends: an unknown card status or authorization method, and a capture of an
- *  authorization that is not approved and pending. */
-function issuingRefusal(ctx: SemanticsContext, what: 'card_status' | 'authorization_method' | 'not_capturable', auth?: Row): Response {
-  switch (what) {
-    case 'card_status': return fail(ctx, "Invalid status: must be one of 'active', 'inactive', or 'canceled'.", 400, 'parameter_invalid_string_enum');
-    case 'authorization_method': return fail(ctx, "Invalid authorization_method: must be one of 'chip', 'contactless', 'keyed_in', 'online', or 'swipe'.", 400, 'parameter_invalid_string_enum');
-    case 'not_capturable': return fail(ctx, `This authorization cannot be captured because it is not an approved pending authorization (status: ${String(auth?.status)}, approved: ${auth?.approved === true}).`, 400);
-  }
-}
-
-/** A partial approval's refusal: "You can specify the amount you want to approve by setting the amount in the webhook
- *  response body or the approve call" only "When an authorization is partially authorized, the is_amount_controllable
- *  field on the authorization request is set to true" (docs.stripe.com/issuing/purchases/authorizations), and never a
- *  credit. Answers the refusal, or undefined when the amount may be approved. */
-function partialApprovalRefused(ctx: SemanticsContext, auth: Row): Response | undefined {
-  if (Math.trunc(Number(ctx.params.amount) || 0) <= 0) return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
-  if ((auth.pending_request as Row | null | undefined)?.is_amount_controllable !== true) return fail(ctx, 'amount may only be provided when the authorization was presented with is_amount_controllable.', 400);
-  return undefined;
-}
-
-// the (deprecated but real) API decision on a pending authorization: it lands in request_history
-// as the webhook's answer would, consumes the pending request, and an approval captures
-function decide(approved: boolean): Semantics {
-  return async (ctx) => {
-    const id = at(ctx, 'authorization');
-    const auth = ctx.get(AUTH, id);
-    if (!auth) return authMissing(ctx, id);
-    const finalized = { status: 400, code: 'authorization_already_finalized', message: `This authorization has already been finalized (status ${String(auth.status)}).` };
-    // a webhook-approved authorization is decided, though still pending
-    if (auth.approved === true) return ctx.refuse(finalized);
-    const refused = ctx.legal(AUTH, 'status', approved ? 'PostIssuingAuthorizationsAuthorizationApprove' : 'PostIssuingAuthorizationsAuthorizationDecline', auth.status, undefined, id);
+  const { expand: _expand, ...fields } = ctx.params;
+  // source: spec:/paths/~1v1~1issuing~1cards~1{card}/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/status "Dictates whether authorizations can be approved on this card."
+  if (fields.status !== undefined && !['active', 'inactive', 'canceled'].includes(String(fields.status))) return issuingRefusal(ctx, 'card_status');
+  if (fields.status !== undefined) {
+    const refused = ctx.legal(CARD, 'status', 'PostIssuingCardsCard', card.status, String(fields.status), id);
     if (refused) return ctx.refuse(refused);
-    // a partial approval only for an amount-controllable presentment, and never a credit
-    const badAmount = approved && ctx.params.amount !== undefined ? partialApprovalRefused(ctx, auth) : undefined;
-    if (badAmount) return badAmount;
-    const decidedAmount = approved && ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : Number(auth.amount) || 0;
-    const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
-    const history = Array.isArray(auth.request_history) ? (auth.request_history as Row[]) : [];
-    // an approval holds the funds and waits for the merchant's capture; a decline closes it
-    // (docs.stripe.com/issuing/purchases/authorizations, docs.stripe.com/issuing/funding/balance)
-    const hold = approved ? await holdFor(ctx, id, decidedAmount, currency) : null;
-    return ctx.reply(
-      await ctx.write(AUTH, id, {
-        ...(approved ? {} : { status: 'closed' }), approved, pending_request: null,
-        ...(approved && ctx.params.amount !== undefined ? { amount: decidedAmount } : {}),
-        request_history: [...history, historyEntry({
-          amount: decidedAmount, currency, approved, reason: approved ? 'webhook_approved' : 'webhook_declined', reasonMessage: null,
-          createdSec: Number(ctx.now()), merchantAmount: Number(auth.merchant_amount) || decidedAmount,
-          merchantCurrency: typeof auth.merchant_currency === 'string' ? auth.merchant_currency : currency,
-        })],
-        ...(hold ? { balance_transactions: [...(Array.isArray(auth.balance_transactions) ? auth.balance_transactions : []), hold.id] } : {}),
-      }, 'issuing_authorization.updated'),
-    );
-  };
-}
-
-/** The real-time window: "If Stripe doesn't receive your approve or decline response within 2 seconds, the
- *  Authorization is automatically approved or declined based on your timeout settings"
- *  (docs.stripe.com/issuing/controls/real-time-authorizations). */
-const REALTIME_WINDOW_SECONDS = 2;
-
-/** Time's decision on a real-time request no one answered, caught up to the World's clock: once its window has ended,
- *  a pending authorization whose issuing_authorization.request went unanswered, and that no approve or decline decided,
- *  is decided automatically, its request_history reason webhook_timeout ("webhook_timeout for all other failure modes",
- *  the same page, beside webhook_error for a response Stripe cannot process).
- *  Where the documentation stops and the twin decides: the timeout setting is the Dashboard's, which the API does not
- *  answer, and the twin's is to decline; the window is measured in World time from the authorization's created. */
-export async function lapseRealtimeRequests(ctx: SemanticsContext): Promise<void> {
-  const now = Number(ctx.now());
-  const requested = new Set(ctx.rowsRaw('event').filter((e) => e._stripe_type === 'issuing_authorization.request').map((e) => String(((e.data as Row | undefined)?.object as Row | undefined)?.id ?? '')));
-  for (const a of ctx.rowsRaw(AUTH)) {
-    if (a.status !== 'pending' || a.approved === true || !a.pending_request || !requested.has(String(a.id))) continue;
-    const at = Number(a.created) + REALTIME_WINDOW_SECONDS;
-    if (now < at) continue;
-    const id = String(a.id);
-    const currency = typeof a.currency === 'string' ? a.currency : 'usd';
-    const amount = Number(a.amount) || 0;
-    ctx.legal(AUTH, 'status', ctx.call.operation.id, 'pending', 'closed', id, 'time');
-    await ctx.write(AUTH, id, {
-      status: 'closed', approved: false, pending_request: null,
-      request_history: [...(Array.isArray(a.request_history) ? (a.request_history as Row[]) : []), historyEntry({
-        amount, currency, approved: false, reason: 'webhook_timeout', reasonMessage: null, createdSec: at,
-        merchantAmount: Number(a.merchant_amount) || amount, merchantCurrency: typeof a.merchant_currency === 'string' ? a.merchant_currency : currency,
-      })],
-    }, 'issuing_authorization.updated');
-  }
-}
-
-/** An approval's hold: "If you approve the authorization, we deduct the `amount` from your Issuing balance and hold it
- *  in reserve until the authorization is either captured, voided, or expired without capture"
- *  (docs.stripe.com/issuing/purchases/authorizations). */
-async function holdFor(ctx: SemanticsContext, authId: string, amount: number, currency: string): Promise<Row> {
-  return created(ctx, 'balance_transaction', {}, {
-    amount: -amount, currency, fee: 0, net: -amount, type: 'issuing_authorization_hold',
-    status: 'available', balance_type: 'issuing', reporting_category: 'issuing_authorization_hold',
-    available_on: ctx.now(), fee_details: [], source: authId,
-  });
-}
-
-/** An authorization approved as it is presented, its amount held: approved and pending until the merchant captures. */
-async function approvedAtOnce(ctx: SemanticsContext, subject: Row, fields: Row, held: number, entry: Row): Promise<Response> {
-  const hold = await holdFor(ctx, String(subject.id), held, String(fields.currency ?? 'usd'));
-  return ctx.reply(await created(ctx, AUTH, subject, { ...fields, amount: held, status: 'pending', approved: true, pending_request: null, request_history: [entry], balance_transactions: [hold.id] }));
-}
-
-/** An authorization as the platform's real-time answer makes it: approved (in part, only when the request was
- *  amount-controllable), declined, or declined for an answer Stripe cannot read (docs.stripe.com/issuing/controls/
- *  real-time-authorizations: the response's `approved` and `amount`; webhook_error "if we can't process your response"). */
-async function answeredByEndpoint(ctx: SemanticsContext, outcome: { kind: 'approved'; amount?: number } | { kind: 'declined' } | { kind: 'error'; message: string }, o: {
-  subject: Row; fields: Row; amount: number; controllable: boolean; entry: (e: { amount: number; approved: boolean; reason: string; reasonMessage: string | null }) => Row;
-  decline: (reason: string, message: string | null) => Promise<Response>;
-}): Promise<Response> {
-  if (outcome.kind === 'approved') {
-    const held = o.controllable && outcome.amount !== undefined ? outcome.amount : o.amount;
-    return approvedAtOnce(ctx, o.subject, o.fields, held, o.entry({ amount: held, approved: true, reason: 'webhook_approved', reasonMessage: null }));
   }
-  return outcome.kind === 'declined' ? o.decline('webhook_declined', null) : o.decline('webhook_error', outcome.message);
-}
-
-const present: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const card = typeof params.card === 'string' ? params.card : '';
-  if (!card) return fail(ctx, 'Missing required param: card.', 400, 'parameter_missing');
-  const c = ctx.get(CARD, card);
-  if (!c) return fail(ctx, `No such card: '${card}'`, 400, 'resource_missing');
-  if (params.amount === undefined) return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
-  const amount = Math.trunc(Number(params.amount) || 0);
-  const currency = String(params.currency ?? c.currency ?? 'usd');
-  const createdSec = Number(ctx.now());
-  const cardholderId = holderId(c);
-  const merchant = merchantData(params.merchant_data);
-  const isAmountControllable = params.is_amount_controllable === true;
-  const authMethod = typeof params.authorization_method === 'string' ? params.authorization_method : 'online';
-  if (!['chip', 'contactless', 'keyed_in', 'online', 'swipe'].includes(authMethod)) return issuingRefusal(ctx, 'authorization_method');
-  const merchantAmount = params.merchant_amount !== undefined ? Math.trunc(Number(params.merchant_amount) || 0) : amount;
-  const merchantCurrency = typeof params.merchant_currency === 'string' ? params.merchant_currency : currency;
-  const authId = ctx.mint(AUTH);
-  const baseFields: Row = {
-    amount, amount_details: null, authorization_method: authMethod,
-    balance_transactions: [], transactions: [],
-    currency, fleet: null, fuel: null, livemode: false,
-    merchant_amount: merchantAmount, merchant_currency: merchantCurrency, merchant_data: merchant,
-    metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
-    network_data: null,
-    verification_data: {
-      address_line1_check: 'not_provided', address_postal_code_check: 'not_provided',
-      authentication_exemption: null, cvc_check: 'match', expiry_check: 'match',
-      postal_code: null, three_d_secure: null,
-    },
-    wallet: null,
-  };
-  const subject = { id: authId, card, cardholder: cardholderId };
-  const entry = (o: { amount: number; approved: boolean; reason: string; reasonMessage: string | null }) => historyEntry({ ...o, currency, createdSec, merchantAmount, merchantCurrency });
-  const decline = async (reason: string, reasonMessage: string | null) =>
-    ctx.reply(await created(ctx, AUTH, subject, { ...baseFields, status: 'closed', approved: false, pending_request: null, request_history: [entry({ amount, approved: false, reason, reasonMessage })] }));
-  if (c.status === 'canceled') return decline('card_canceled', 'The card has been canceled.');
-  if (c.status !== 'active') return decline('card_inactive', 'The card is inactive.');
-  // what earlier approved authorizations on the card (or cardholder) already spent, for the limits
-  const prior = (key: 'card' | 'cardholder', value: string) =>
-    ctx.rows(AUTH).filter((a) => a[key] === value && a.approved === true)
-      .map((a) => ({ amount: Number(a.amount) || 0, created: Number(a.created) || 0, category: String((a.merchant_data as Row | undefined)?.category ?? '') }));
-  const controlsOpts = { amount, category: String(merchant.category ?? ''), country: merchant.country == null ? null : String(merchant.country), nowSec: createdSec };
-  const cardholderRow = cardholderId ? ctx.get(CH, cardholderId) : undefined;
-  const violation =
-    spendingControlsViolation(c.spending_controls, { ...controlsOpts, priorApproved: prior('card', card) }) ??
-    spendingControlsViolation(cardholderRow?.spending_controls, { ...controlsOpts, priorApproved: prior('cardholder', cardholderId) });
-  if (violation) return decline('spending_controls', violation);
-  // an authorization is paid from the Issuing balance, and declined when it cannot cover it
-  // (docs.stripe.com/issuing/funding/balance)
-  if ((balanceOf(ctx).issuing.get(currency) ?? 0) < amount) return decline('insufficient_funds', 'Your Issuing balance does not have enough funds for this authorization.');
-  const pendingRequest = {
-    amount, amount_details: null, currency, is_amount_controllable: isAmountControllable,
-    merchant_amount: merchantAmount, merchant_currency: merchantCurrency, network_risk_score: null,
-  };
-  const endpoint = ctx.rows('webhook_endpoint').find((w) => w.status === 'enabled' && stripeEventMatches(w.enabled_events, 'issuing_authorization.request'));
-  // no real-time enrollment: "If you don't have a real-time authorization webhook, we approve the authorization without
-  // sending the issuing_authorization.request" (docs.stripe.com/issuing/purchases/authorizations), its outcome
-  // card_active, "approved according to your default Issuing settings"
-  if (!endpoint) return approvedAtOnce(ctx, subject, baseFields, amount, entry({ amount, approved: true, reason: 'card_active', reasonMessage: null }));
-  // the request event's authorization carries pending_request, non-null only during the request
-  const requestObject = withCard(ctx, { object: 'issuing.authorization', id: authId, created: createdSec, ...baseFields, card, cardholder: cardholderId, status: 'pending', approved: false, pending_request: pendingRequest, request_history: [] });
-  // the delivered request and the stored event are one event under one id
-  const requestEvent: StripeEvent = { id: nextStripeEventId(ctx.root), object: 'event', type: 'issuing_authorization.request', created: createdSec, livemode: false, data: { object: requestObject } };
-  const version = ctx.call.request.headers.get('stripe-version') ?? undefined;
-  await persistStripeEvent('issuing_authorization.request', requestObject, ctx.root, ctx.occurredAt, version, undefined, requestEvent.id);
-  const secret = typeof endpoint.secret === 'string' && endpoint.secret ? endpoint.secret : STRIPE_WEBHOOK_FALLBACK_SECRET;
-  const outcome = await requestAuthorizationDecision(String(endpoint.url), requestEvent, secret);
-  // a request no one answered (the World refused the delivery, it failed, or it timed out) is not a decision: the
-  // authorization stays pending with its request, for the deprecated approve or decline "within the timeout window of
-  // the real-time authorization flow" (the served spec), until lapseRealtimeRequests decides it when the window ends
-  if (outcome.kind === 'timeout') return ctx.reply(await created(ctx, AUTH, subject, { ...baseFields, status: 'pending', approved: false, request_history: [], pending_request: pendingRequest }));
-  return answeredByEndpoint(ctx, outcome, { subject, fields: baseFields, amount, controllable: isAmountControllable, entry, decline });
-};
-
-// capturing an approved pending authorization, up to what it still holds; it closes unless told not to
-const captureAuthorization: Semantics = async (ctx) => {
-  const id = at(ctx, 'authorization');
-  const auth = ctx.get(AUTH, id);
-  if (!auth) return authMissing(ctx, id);
-  if (auth.approved !== true || auth.status !== 'pending') return issuingRefusal(ctx, 'not_capturable', auth);
-  const closeAuthorization = ctx.params.close_authorization !== false;
-  const refused = ctx.legal(AUTH, 'status', 'PostTestHelpersIssuingAuthorizationsAuthorizationCapture', auth.status, closeAuthorization ? 'closed' : 'pending');
-  if (refused) return ctx.refuse(refused);
-  const txns = Array.isArray(auth.transactions) ? auth.transactions : [];
-  const capturedSoFar = txns.map((t) => ctx.get(TXN, String(t))).reduce((s, t) => s + Math.abs(Number(t?.amount) || 0), 0);
-  const remaining = (Number(auth.amount) || 0) - capturedSoFar;
-  const captureAmount = ctx.params.capture_amount !== undefined ? Math.trunc(Number(ctx.params.capture_amount) || 0) : remaining;
-  if (captureAmount <= 0 || captureAmount > remaining) return fail(ctx, 'Invalid capture_amount: must be a positive integer no greater than the uncaptured authorized amount.', 400, 'parameter_invalid_integer');
-  // the capture releases what the approval held and debits the transaction; a capture that closes the authorization
-  // releases ALL it still holds, the uncaptured rest included: the amount is held "until the authorization is either
-  // captured, voided, or expired without capture" (docs.stripe.com/issuing/purchases/authorizations), and a closed
-  // authorization can be captured no further (close_authorization "Defaults to true. Set to false to enable
-  // multi-capture flows", the served spec). A capture that keeps it open releases only what it captured.
-  const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
-  const released = closeAuthorization ? remaining : captureAmount;
-  const release = await created(ctx, 'balance_transaction', {}, {
-    amount: released, currency, fee: 0, net: released, type: 'issuing_authorization_release',
-    status: 'available', balance_type: 'issuing', reporting_category: 'issuing_authorization_release',
-    available_on: ctx.now(), fee_details: [], source: id,
-  });
-  const captured = await capture(ctx, id, { ...auth, card: cardId(auth) }, captureAmount);
-  return ctx.reply(
-    await ctx.write(AUTH, id, {
-      ...(closeAuthorization ? { status: 'closed' } : {}),
-      transactions: [...txns, captured.txnId],
-      balance_transactions: [...(Array.isArray(auth.balance_transactions) ? auth.balance_transactions : []), release.id, captured.btId],
-    }, 'issuing_authorization.updated'),
-  );
-};
-
-// ── transactions ──
-
-const updateTransaction: Semantics = async (ctx) => {
-  const id = at(ctx, 'transaction');
-  if (!ctx.get(TXN, id)) return fail(ctx, `No such transaction: '${id}'`, 404, 'resource_missing');
-  return ctx.reply(await ctx.write(TXN, id, ctx.params, 'issuing_transaction.updated'));
-};
-
-// a settlement with no authorization before it still debits the issuing balance
-const forceCapture: Semantics = async (ctx) => {
-  const card = typeof ctx.params.card === 'string' ? ctx.params.card : '';
-  if (!card) return fail(ctx, 'Missing required param: card.', 400, 'parameter_missing');
-  const c = ctx.get(CARD, card);
-  if (!c) return fail(ctx, `No such card: '${card}'`, 400, 'resource_missing');
-  if (ctx.params.amount === undefined) return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
-  const amount = Math.trunc(Number(ctx.params.amount) || 0);
-  if (amount <= 0) return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
-  const currency = String(ctx.params.currency ?? c.currency ?? 'usd');
-  const bt = await created(ctx, 'balance_transaction', {}, {
-    amount: -amount, currency, fee: 0, net: -amount, type: 'issuing_transaction',
-    status: 'available', balance_type: 'issuing', reporting_category: 'issuing_transaction',
-    available_on: ctx.now(), fee_details: [],
-  });
-  return ctx.reply(
-    await created(ctx, TXN, { card, cardholder: holderId(c) }, {
-      type: 'capture', amount: -amount, currency,
-      merchant_amount: -amount, merchant_currency: typeof ctx.params.merchant_currency === 'string' ? ctx.params.merchant_currency : currency,
-      merchant_data: merchantData(ctx.params.merchant_data),
-      authorization: null, dispute: null, balance_transaction: bt.id,
-      livemode: false, metadata: {}, wallet: null, network_data: null, amount_details: null, purchase_details: null,
-    }),
-  );
-};
-
-// ── disputes: opened against a transaction, unsubmitted until submitted ──
-
-const disputeMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such dispute: '${id}'`, 404, 'resource_missing');
-
-const openDispute: Semantics = async (ctx) => {
-  const txn = typeof ctx.params.transaction === 'string' ? ctx.params.transaction : '';
-  if (!txn) return fail(ctx, 'Missing required param: transaction.', 400, 'parameter_missing');
-  const t = ctx.get(TXN, txn);
-  if (!t) return fail(ctx, `No such transaction: '${txn}'`, 400, 'resource_missing');
-  const ev = ctx.params.evidence && typeof ctx.params.evidence === 'object' ? (ctx.params.evidence as Row) : undefined;
-  if (!ev || ev.reason === undefined || ev.reason === '') return fail(ctx, 'Missing required param: evidence[reason].', 400, 'parameter_missing');
-  const amount = ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : Math.abs(Number(t.amount) || 0);
-  return ctx.reply(await created(ctx, DSP, ctx.params, { status: 'unsubmitted', amount, currency: t.currency ?? 'usd', livemode: false, metadata: {}, balance_transactions: null }));
-};
-
-const submitDispute: Semantics = async (ctx) => {
-  const id = at(ctx, 'dispute');
-  const d = ctx.get(DSP, id);
-  if (!d) return disputeMissing(ctx, id);
-  const refused = ctx.legal(DSP, 'status', 'PostIssuingDisputesDisputeSubmit', d.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  return ctx.reply(await ctx.write(DSP, id, { status: 'submitted' }, 'issuing_dispute.submitted'));
-};
-
-const updateDispute: Semantics = async (ctx) => {
-  const id = at(ctx, 'dispute');
-  if (!ctx.get(DSP, id)) return disputeMissing(ctx, id);
-  return ctx.reply(await ctx.write(DSP, id, ctx.params, 'issuing_dispute.updated'));
-};
-
-// ── network tokens: minted by the card network (the twin's mint is a test helper outside Stripe's
-// surface); Stripe lets a token be set active, deleted or suspended ──
-
-const updateToken: Semantics = async (ctx) => {
-  const id = at(ctx, 'token');
-  const t = ctx.get(TOK, id);
-  if (!t) return fail(ctx, `No such issuing token: '${id}'`, 404, 'resource_missing');
-  const status = typeof ctx.params.status === 'string' ? ctx.params.status : '';
-  if (!['active', 'deleted', 'suspended'].includes(status)) return fail(ctx, 'Invalid status: must be active, deleted, or suspended.', 400, 'parameter_invalid_string_enum');
-  const refused = ctx.legal(TOK, 'status', 'PostIssuingTokensToken', t.status, status);
-  if (refused) return ctx.refuse(refused);
-  return ctx.reply(await ctx.write(TOK, id, { status }, 'issuing_token.updated'));
-};
-
-// ── personalization designs: in review until Stripe's review (the test helpers in test mode) decides ──
-
-const designMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such personalization design: '${id}'`, 404, 'resource_missing');
-
-/** Stripe's physical bundles are its catalog, not the account's: the twin serves the one its reference publishes
- *  (docs.stripe.com/api/issuing/physical_bundles: "US Visa Credit White", standard, active, a card logo required and
- *  carrier text optional). Where the documentation stops and the twin decides: the catalog is that one bundle, and its
- *  second_line (required by the served spec, absent from the example) is optional. */
-const PHYSICAL_BUNDLES: Row[] = [
-  { id: 'ics_NLuXJPDYSTjFON', object: 'issuing.physical_bundle', livemode: false, name: 'US Visa Credit White', features: { card_logo: 'required', carrier_text: 'optional', second_line: 'optional' }, status: 'active', type: 'standard' },
-];
-const listBundles: Semantics = async (ctx) =>
-  ctx.reply({ object: 'list', url: '/v1/issuing/physical_bundles', has_more: false, data: PHYSICAL_BUNDLES.filter((b) => (ctx.params.status === undefined || b.status === ctx.params.status) && (ctx.params.type === undefined || b.type === ctx.params.type)) });
-const retrieveBundle: Semantics = async (ctx) => {
-  const b = PHYSICAL_BUNDLES.find((x) => x.id === at(ctx, 'physical_bundle'));
-  return b ? ctx.reply(b) : fail(ctx, `No such physical bundle: '${at(ctx, 'physical_bundle')}'`, 404, 'resource_missing');
-};
-
-const createDesign: Semantics = async (ctx) => {
-  const bundle = typeof ctx.params.physical_bundle === 'string' ? ctx.params.physical_bundle : '';
-  if (!bundle) return fail(ctx, 'Missing required param: physical_bundle.', 400, 'parameter_missing');
-  if (!PHYSICAL_BUNDLES.some((b) => b.id === bundle)) return fail(ctx, `No such physical bundle: '${bundle}'`, 400, 'resource_missing');
-  const logo = filePurposeRefused(ctx, 'card_logo', ['issuing_logo']);
-  if (logo) return logo;
-  return ctx.reply(
-    await created(ctx, PD, {}, {
-      livemode: false, status: 'review', physical_bundle: bundle,
-      name: ctx.params.name ?? null, lookup_key: ctx.params.lookup_key ?? null,
-      card_logo: (ctx.params.card_logo as string) ?? null, carrier_text: (ctx.params.carrier_text as object) ?? null,
-      preferences: { is_default: false, is_platform_default: null },
-      rejection_reasons: { card_logo: [], carrier_text: [] },
-      metadata: ctx.params.metadata && typeof ctx.params.metadata === 'object' ? ctx.params.metadata : {},
-    }),
-  );
-};
-
-const listDesigns: Semantics = async (ctx) =>
-  list(ctx, PD, where(ctx, newest(ctx, PD), {
-    status: (d, v) => d.status === v,
-    lookup_keys: (d, v) => (Array.isArray(v) ? v.map(String).includes(String(d.lookup_key)) : String(d.lookup_key) === String(v)),
-  }));
-
-const updateDesign: Semantics = async (ctx) => {
-  const id = at(ctx, 'personalization_design');
-  if (!ctx.get(PD, id)) return designMissing(ctx, id);
-  const logo = filePurposeRefused(ctx, 'card_logo', ['issuing_logo']);
-  if (logo) return logo;
-  return ctx.reply(await ctx.write(PD, id, ctx.params, 'personalization_design.updated'));
-};
-
-function review(action: 'activate' | 'deactivate' | 'reject', operationId: string): Semantics {
-  return async (ctx) => {
-    const id = at(ctx, 'personalization_design');
-    const d = ctx.get(PD, id);
-    if (!d) return designMissing(ctx, id);
-    const refused = ctx.legal(PD, 'status', operationId, d.status, undefined, id);
-    if (refused) return ctx.refuse(refused);
-    const status = action === 'activate' ? 'active' : action === 'deactivate' ? 'inactive' : 'rejected';
-    // a rejection records its reasons: the reject helper's required rejection_reasons, "The reason(s) the
-    // personalization design was rejected" (the served spec), per card_logo and carrier_text
-    const given = ctx.params.rejection_reasons && typeof ctx.params.rejection_reasons === 'object' ? (ctx.params.rejection_reasons as Row) : undefined;
-    if (action === 'reject' && !given) return fail(ctx, 'Missing required param: rejection_reasons.', 400, 'parameter_missing');
-    const reasons = action === 'reject' ? { rejection_reasons: { card_logo: Array.isArray(given!.card_logo) ? given!.card_logo : [], carrier_text: Array.isArray(given!.carrier_text) ? given!.carrier_text : [] } } : {};
-    return ctx.reply(await ctx.write(PD, id, { status, ...reasons }, `personalization_design.${action}`));
-  };
+  const controls = normalizeSpendingControls(fields.spending_controls, String(card.currency), card.spending_controls as Row);
+  if (controls.error) return send(ctx, controls.error);
+  return ctx.reply(ctx.expand(CARD, await ctx.write(CARD, id, { ...fields, ...(controls.controls ? { spending_controls: controls.controls } : {}) }, 'issuing.card.update')));
 }
-
-export const issuing: Record<string, Semantics> = {
-  PostIssuingCardholders: createCardholder,
-  PostIssuingCardholdersCardholder: updateCardholder,
-  PostIssuingCards: createCard,
-  GetIssuingCards: listCards,
-  PostIssuingCardsCard: updateCard,
-  GetIssuingAuthorizations: listAuthorizations,
-  GetIssuingAuthorizationsAuthorization: retrieveAuthorization,
-  PostIssuingAuthorizationsAuthorization: updateAuthorization,
-  PostIssuingAuthorizationsAuthorizationApprove: decide(true),
-  PostIssuingAuthorizationsAuthorizationDecline: decide(false),
-  PostTestHelpersIssuingAuthorizations: present,
-  PostTestHelpersIssuingAuthorizationsAuthorizationCapture: captureAuthorization,
-  PostIssuingTransactionsTransaction: updateTransaction,
-  PostTestHelpersIssuingTransactionsCreateForceCapture: forceCapture,
-  PostIssuingDisputes: openDispute,
-  PostIssuingDisputesDisputeSubmit: submitDispute,
-  PostIssuingDisputesDispute: updateDispute,
-  PostIssuingTokensToken: updateToken,
-  GetIssuingPhysicalBundles: listBundles,
-  GetIssuingPhysicalBundlesPhysicalBundle: retrieveBundle,
-  PostIssuingPersonalizationDesigns: createDesign,
-  GetIssuingPersonalizationDesigns: listDesigns,
-  PostIssuingPersonalizationDesignsPersonalizationDesign: updateDesign,
-  PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignActivate: review('activate', 'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignActivate'),
-  PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignDeactivate: review('deactivate', 'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignDeactivate'),
-  PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignReject: review('reject', 'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignReject'),
-};