@volter/twin-stripe 0.1.2 → 2.0.1

package/src/semantics/issuing.ts

@@ -0,0 +1,590 @@
+// 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;
+}
+
+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);
+};
+
+// ── cards: a virtual card is active at once, a physical one inactive until shipped ──
+
+const createCard: Semantics = async (ctx) => {
+  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');
+  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 !== '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);
+  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 updateCard: Semantics = async (ctx) => {
+  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);
+    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}`));
+  };
+}
+
+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'),
+};