@volter/twin-stripe 0.1.2 → 2.0.0

package/src/semantics/transfers.ts

@@ -0,0 +1,174 @@
+// Transfer and application-fee semantics: money the platform moves to a connected account and
+// claws back (reversals), and the platform's fee on a connected charge and its refunds. A
+// reversal or fee refund never exceeds what is left, and lands on its parent's totals and list.
+// A transfer goes only to an account whose transfers capability is active, comes out of the
+// platform's available balance, and lands in the destination's (docs.stripe.com/connect/separate-
+// charges-and-transfers); a reversal moves it back.
+// A transfer tied to a charge (`source_transaction`, "Transfer availability" in the same guide) "returns success
+// regardless of your available balance if the related charge hasn't settled yet", but "the funds don't become
+// available in the destination account until the funds from the associated charge are available"; a charge whose funds
+// are already available by the World's clock is no exception, and the transfer is held to the available balance as any
+// other. "The amount of the transfer must not exceed the amount of the source charge", several transfers may share one
+// charge while "the sum of the transfers doesn't exceed the source charge", and the charge's balance currency must
+// match. "If the source charge has a `transfer_group` value, Stripe assigns the same value to the transfer's
+// `transfer_group`. If it doesn't, then Stripe generates a string in the format `group_` plus the associated
+// PaymentIntent ID ... It assigns that string as the `transfer_group` for both the charge and the transfer."
+// Where the documentation stops and the twin decides: the sum from one charge counts each transfer less what was
+// reversed of it; a transfer_group the request names is kept only when the charge has none and no PaymentIntent to
+// name one after; an uncaptured charge (an authorization, docs silent) is refused as a source_transaction until it is
+// captured; the refusals' wording is the twin's.
+// Transfer list, retrieve and update and application-fee list and retrieve are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { validateMoney } from '../stripe-twin.ts';
+import { refusePayout, settleTransfer, settleTransferReversal } from './ledger.ts';
+import { at, created, fail, list, newest, send, type Row } from './shared.ts';
+
+const transferMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such transfer: '${id}'`, 404, 'resource_missing');
+const emptyList = (url: string): Row => ({ object: 'list', data: [], has_more: false, total_count: 0, url });
+
+/** A transfer to an account whose transfers capability is not active. */
+function transfersInactive(ctx: SemanticsContext): Response {
+  return ctx.refuse({ status: 400, code: 'insufficient_capabilities_for_transfer', param: 'destination', message: 'Your destination account needs to have at least one of the following capabilities enabled: transfers, crypto_transfers, legacy_payments' });
+}
+
+const create: Semantics = async (ctx) => {
+  const bad = validateMoney(ctx.params);
+  if (bad) return send(ctx, bad);
+  const destination = typeof ctx.params.destination === 'string' ? ctx.params.destination : '';
+  if (!destination) return fail(ctx, 'Missing required param: destination.', 400, 'parameter_missing');
+  const account = ctx.get('account', destination);
+  if (!account) return fail(ctx, `No such destination: '${destination}'`, 400, 'resource_missing');
+  if (((account.capabilities as Row | undefined)?.transfers) !== 'active') return transfersInactive(ctx);
+  const amount = Math.trunc(Number(ctx.params.amount) || 0);
+  const currency = String(ctx.params.currency ?? 'usd');
+  const sourceId = typeof ctx.params.source_transaction === 'string' ? ctx.params.source_transaction : undefined;
+  let availableOn: number | undefined;
+  let group: string | undefined;
+  if (sourceId) {
+    const charge = ctx.get('charge', sourceId);
+    if (!charge) return fail(ctx, `No such charge: '${sourceId}'`, 400, 'resource_missing');
+    if (charge.status !== 'succeeded') return fail(ctx, `The source_transaction ${sourceId} has not succeeded.`, 400, 'invalid_request_error');
+    // an authorization holds no funds to transfer
+    if (charge.captured === false) return fail(ctx, `The source_transaction ${sourceId} has not been captured; capture it before transferring its funds.`, 400);
+    if (String(charge.currency ?? 'usd') !== currency) return fail(ctx, `The currency of source_transaction ${sourceId} (${String(charge.currency)}) does not match the transfer's (${currency}).`, 400, 'invalid_request_error');
+    const already = ctx.rowsRaw('transfer').filter((t) => t.source_transaction === sourceId).reduce((sum, t) => sum + (Number(t.amount) || 0) - (Number(t.amount_reversed) || 0), 0);
+    if (already + amount > Number(charge.amount ?? 0)) return fail(ctx, `The transfers from source_transaction ${sourceId} would exceed its amount (${String(charge.amount)}).`, 400, 'invalid_request_error');
+    const bt = typeof charge.balance_transaction === 'string' ? ctx.get('balance_transaction', charge.balance_transaction) : undefined;
+    // a charge that has settled waives nothing: the transfer comes out of what is available
+    const settledRefusal = bt && Number(bt.available_on) <= Number(ctx.now()) ? settledSourceRefused(ctx, amount, currency) : undefined;
+    if (settledRefusal) return settledRefusal;
+    availableOn = Math.max(Number(ctx.now()), Number(bt?.available_on) || 0);
+    group = typeof charge.transfer_group === 'string' ? charge.transfer_group : typeof charge.payment_intent === 'string' ? `group_${charge.payment_intent}` : undefined;
+    // the generated group is the charge's too
+    if (group && charge.transfer_group !== group) await ctx.write('charge', sourceId, { transfer_group: group }, 'charge.transfer_group_assigned');
+  } else {
+    const refused = refusePayout(ctx, amount, currency, undefined);
+    if (refused) return refused;
+  }
+  const id = ctx.mint('transfer');
+  const bt = await settleTransfer(ctx, id, amount, currency, destination, availableOn ?? Number(ctx.now()), sourceId !== undefined);
+  return ctx.reply(
+    await created(ctx, 'transfer', { id, ...ctx.params, ...(group ? { transfer_group: group } : {}) }, {
+      amount_reversed: 0, balance_transaction: bt, livemode: false, metadata: {},
+      reversed: false, source_type: 'card', source_transaction: null,
+      reversals: emptyList(`/v1/transfers/${id}/reversals`),
+      destination_payment: `py_${id.replace(/^tr_/, '')}`,
+    }),
+  );
+};
+
+/** A transfer from a charge whose funds have settled: "With a source_transaction, the transfer request returns success
+ *  regardless of your available balance if the related charge hasn't settled yet" (docs.stripe.com/connect/separate-
+ *  charges-and-transfers), so a settled one comes out of the available balance. */
+function settledSourceRefused(ctx: SemanticsContext, amount: number, currency: string): Response | undefined {
+  return refusePayout(ctx, amount, currency, undefined);
+}
+
+/** An application fee refunded to its whole through its own refunds endpoint: the fee machine's move, or its refusal. */
+function feeFullyRefunded(ctx: SemanticsContext, resource: string, flag: string, id: string): Response | undefined {
+  const refused = ctx.legal(resource, flag, ctx.call.operation.id, 'false', 'true', id);
+  return refused ? ctx.refuse(refused) : undefined;
+}
+
+/** Take `amount` (the remainder by default) back out of a parent's total, as a child row appended to its list. */
+async function giveBack(ctx: SemanticsContext, o: {
+  parent: Row; parentResource: string; child: string; childFields: (amount: number) => Row; childDefaults: Row;
+  doneField: string; flag: string; listUrl: string; op: string; tooLarge: (remaining: number) => string;
+  /** what the money movement itself writes, once the child exists */
+  settle?: (child: Row, amount: number) => Promise<void>;
+}): Promise<Response> {
+  const id = String(o.parent.id);
+  const total = Number(o.parent.amount ?? 0);
+  const already = Number(o.parent[o.doneField] ?? 0);
+  const remaining = total - already;
+  const amount = ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : remaining;
+  if (amount <= 0 || amount > remaining) return fail(ctx, o.tooLarge(remaining), 400, 'amount_too_large');
+  const done = already + amount;
+  // a fee refunded in full is `refunded`: the application fee machine's move (a transfer's `reversed` is no state)
+  const feeRefusal = o.parentResource === 'application_fee' && done >= total && o.parent[o.flag] !== true ? feeFullyRefunded(ctx, o.parentResource, o.flag, id) : undefined;
+  if (feeRefusal) return feeRefusal;
+  // the `metadata` a reversal or a fee refund is created with is its own ("Set of key-value pairs that you can attach to
+  // an object", docs.stripe.com/api/transfer_reversals/create, docs.stripe.com/api/fee_refunds/create)
+  const metadata = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? { metadata: ctx.params.metadata } : {};
+  const child = await created(ctx, o.child, { ...o.childFields(amount), ...metadata }, o.childDefaults);
+  if (o.settle) await o.settle(child, amount);
+  const existing = (o.parent[o.flag === 'reversed' ? 'reversals' : 'refunds'] as Row) ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+  const data = [...((existing.data as unknown[]) ?? []), child];
+  await ctx.write(o.parentResource, id, {
+    [o.doneField]: done, [o.flag]: done >= total,
+    [o.flag === 'reversed' ? 'reversals' : 'refunds']: { ...existing, data, total_count: data.length, url: o.listUrl },
+  }, o.op);
+  return ctx.reply(child);
+}
+
+const reverse: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  const tr = ctx.get('transfer', id);
+  if (!tr) return transferMissing(ctx, id);
+  return giveBack(ctx, {
+    parent: tr, parentResource: 'transfer', child: 'transfer_reversal',
+    childFields: (amount) => ({ amount, currency: tr.currency ?? 'usd', transfer: id }),
+    childDefaults: { balance_transaction: null, destination_payment_refund: null, source_refund: null, metadata: {} },
+    doneField: 'amount_reversed', flag: 'reversed', listUrl: `/v1/transfers/${id}/reversals`, op: 'transfer.reversed',
+    tooLarge: (remaining) => `Transfer ${id} can only be reversed up to ${remaining}.`,
+    settle: async (child, amount) => {
+      const bt = await settleTransferReversal(ctx, String(child.id), amount, String(tr.currency ?? 'usd'), String(tr.destination));
+      await ctx.write('transfer_reversal', String(child.id), { balance_transaction: bt }, 'transfer_reversal.updated');
+    },
+  });
+};
+
+const reversals: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  if (!ctx.get('transfer', id)) return transferMissing(ctx, id);
+  return list(ctx, 'transfer_reversal', newest(ctx, 'transfer_reversal').filter((r) => r.transfer === id));
+};
+
+const feeMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such application fee: '${id}'`, 404, 'resource_missing');
+
+const refundFee: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  const fee = ctx.get('application_fee', id);
+  if (!fee) return feeMissing(ctx, id);
+  return giveBack(ctx, {
+    parent: fee, parentResource: 'application_fee', child: 'fee_refund',
+    childFields: (amount) => ({ amount, currency: fee.currency ?? 'usd', fee: id }),
+    childDefaults: { balance_transaction: null, metadata: {} },
+    doneField: 'amount_refunded', flag: 'refunded', listUrl: `/v1/application_fees/${id}/refunds`, op: 'application_fee.refunded',
+    tooLarge: (remaining) => `Application fee ${id} can only be refunded up to ${remaining}.`,
+  });
+};
+
+const feeRefunds: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  if (!ctx.get('application_fee', id)) return feeMissing(ctx, id);
+  return list(ctx, 'fee_refund', newest(ctx, 'fee_refund').filter((r) => r.fee === id));
+};
+
+export const transfers: Record<string, Semantics> = {
+  PostTransfers: create,
+  PostTransfersIdReversals: reverse,
+  GetTransfersIdReversals: reversals,
+  PostApplicationFeesIdRefunds: refundFee,
+  GetApplicationFeesIdRefunds: feeRefunds,
+};

package/src/semantics/treasury.ts

@@ -0,0 +1,383 @@
+// Treasury semantics: financial accounts and the flows that move their money (outbound payments
+// and transfers, inbound transfers), each posting a double entry to the account's ledger (a
+// transaction and its entry). An outbound flow stays processing (cancelable) until the network
+// settles it; an inbound transfer settles at once, as in test mode. The machines in
+// ../manifest.ts say which flows cancel. Lists and retrieves with no required scope are the
+// derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { PLATFORM_ACCOUNT_ID, validateMoney } from '../stripe-twin.ts';
+import { at, created, fail, list, newest, send, where, type Row } from './shared.ts';
+
+const FA = 'treasury.financial_account';
+const TX = 'treasury.transaction';
+const ENTRY = 'treasury.transaction_entry';
+const ENTRY_TYPES = new Set(['credit_reversal', 'debit_reversal', 'inbound_transfer', 'inbound_transfer_return', 'issuing_authorization_hold', 'issuing_authorization_release', 'outbound_payment', 'outbound_transfer', 'received_credit', 'received_debit']);
+
+const faMissing = (ctx: SemanticsContext, id: string, status = 404): Response => fail(ctx, `No such financial account: '${id}'`, status, 'resource_missing');
+const metadataOf = (ctx: SemanticsContext): unknown => (ctx.params.metadata && typeof ctx.params.metadata === 'object' ? ctx.params.metadata : {});
+
+/** A financial account's features as the served spec's treasury.financial_account_features gives them: a toggle
+ *  (card_issuing, deposit_insurance, intra_stripe_flows) or a feature per network (financial_addresses.aba,
+ *  inbound_transfers.ach, outbound_payments.ach and .us_domestic_wire, outbound_transfers likewise), each
+ *  { requested, status, status_details }. What a request asks for is laid over what the account had. Where the
+ *  documentation stops and the twin decides: a requested feature is active at once (test mode), and one never requested
+ *  is left out (each is optional in the served spec). Answers the features and the active features' paths. */
+const NETWORKS: Record<string, string[]> = { financial_addresses: ['aba'], inbound_transfers: ['ach'], outbound_payments: ['ach', 'us_domestic_wire'], outbound_transfers: ['ach', 'us_domestic_wire'] };
+const TOGGLES = ['card_issuing', 'deposit_insurance', 'intra_stripe_flows'];
+function featuresOf(requested: Row, had: Row = {}): { features: Row; active: string[] } {
+  const on = (v: unknown): boolean => v === true || v === 'true';
+  const setting = (asked: boolean) => ({ requested: asked, status: asked ? 'active' : 'restricted', status_details: [] });
+  const features: Row = { ...had };
+  for (const t of TOGGLES) {
+    const r = requested[t] as Row | undefined;
+    if (r && typeof r === 'object' && r.requested !== undefined) features[t] = setting(on(r.requested));
+  }
+  for (const [f, nets] of Object.entries(NETWORKS)) {
+    const r = requested[f] as Row | undefined;
+    if (!r || typeof r !== 'object') continue;
+    const current = (features[f] as Row | undefined) ?? {};
+    const next: Row = { ...current };
+    for (const n of nets) {
+      const nr = r[n] as Row | undefined;
+      if (nr && typeof nr === 'object' && nr.requested !== undefined) next[n] = setting(on(nr.requested));
+    }
+    features[f] = next;
+  }
+  const active: string[] = [];
+  for (const t of TOGGLES) if ((features[t] as Row | undefined)?.status === 'active') active.push(t);
+  for (const [f, nets] of Object.entries(NETWORKS)) for (const n of nets) if (((features[f] as Row | undefined)?.[n] as Row | undefined)?.status === 'active') active.push(`${f}.${n}`);
+  return { features, active };
+}
+
+/** The account's bank address once financial_addresses.aba is active: "The FinancialAccount gains a FinancialAddress
+ *  when the `financial_addresses.aba` feature is active", and "A FinancialAddress is not added until the
+ *  financial_addresses.aba feature has been activated" (docs.stripe.com/treasury/account-management/financial-accounts),
+ *  whose test example answers "bank_name": "Stripe Test Bank", "routing_number": "000000001" and the networks "ach",
+ *  "us_domestic_wire", "rtp"; "The full account_number is only returned if the request expands it" (the same page).
+ *  Where the documentation stops and the twin decides: the account number is ten digits drawn from the account's id,
+ *  answered by its last four (the full number is null: expanding it is not modelled), and the holder's name is the
+ *  platform account's business name, its dashboard name or, with neither, its id. */
+function abaAddress(ctx: SemanticsContext, faId: string): Row {
+  let n = 0;
+  for (const ch of faId) n = (n * 31 + ch.charCodeAt(0)) % 10_000_000_000;
+  const number = String(n).padStart(10, '0');
+  const platform = ctx.get('account', PLATFORM_ACCOUNT_ID) as Row | undefined;
+  const name = ((platform?.business_profile as Row | undefined)?.name ?? ((platform?.settings as Row | undefined)?.dashboard as Row | undefined)?.display_name ?? PLATFORM_ACCOUNT_ID) as string;
+  return { type: 'aba', supported_networks: ['ach', 'us_domestic_wire', 'rtp'], aba: { account_holder_name: name, account_number: null, account_number_last4: number.slice(-4), bank_name: 'Stripe Test Bank', routing_number: '000000001' } };
+}
+const addressesOf = (ctx: SemanticsContext, faId: string, active: string[]): Row[] => (active.includes('financial_addresses.aba') ? [abaAddress(ctx, faId)] : []);
+
+// an account opens with a zero balance in each supported currency and the requested features active
+const open: Semantics = async (ctx) => {
+  const p = ctx.params;
+  const currencies = Array.isArray(p.supported_currencies) ? p.supported_currencies.map(String) : typeof p.supported_currencies === 'string' ? [p.supported_currencies] : [];
+  if (currencies.length === 0) return fail(ctx, 'Missing required param: supported_currencies.', 400, 'parameter_missing');
+  const requested = p.features && typeof p.features === 'object' ? (p.features as Row) : {};
+  const { features, active } = featuresOf(requested);
+  const zero = Object.fromEntries(currencies.map((c) => [c, 0]));
+  const id = ctx.mint(FA);
+  return ctx.reply(
+    await created(ctx, FA, { id }, {
+      livemode: false, status: 'open', country: (p.country as string) ?? 'US',
+      supported_currencies: currencies, active_features: active, pending_features: [], restricted_features: [],
+      features, balance: { cash: zero, inbound_pending: zero, outbound_pending: zero },
+      financial_addresses: addressesOf(ctx, id, active), platform_restrictions: null,
+      status_details: { closed: null },
+      metadata: metadataOf(ctx),
+    }),
+  );
+};
+
+// reading the features answers them; updating them lays the request over them (featuresOf)
+const features: Semantics = async (ctx) => {
+  const id = at(ctx, 'financial_account');
+  const f = ctx.get(FA, id);
+  if (!f) return faMissing(ctx, id);
+  if (ctx.call.request.method === 'GET') return ctx.reply({ object: 'treasury.financial_account_features', ...(f.features as object) });
+  const next = featuresOf(ctx.params, (f.features as Row | undefined) ?? {});
+  const updated = await ctx.write(FA, id, { features: next.features, active_features: next.active, financial_addresses: addressesOf(ctx, id, next.active) }, 'financial_account.features_updated');
+  return ctx.reply({ object: 'treasury.financial_account_features', ...(updated.features as object) });
+};
+
+// only metadata and platform restrictions change
+const updateAccount: Semantics = async (ctx) => {
+  const id = at(ctx, 'financial_account');
+  if (!ctx.get(FA, id)) return faMissing(ctx, id);
+  const patch: Row = {};
+  if (ctx.params.metadata !== undefined) patch.metadata = ctx.params.metadata;
+  if (ctx.params.platform_restrictions !== undefined) patch.platform_restrictions = ctx.params.platform_restrictions;
+  return ctx.reply(await ctx.write(FA, id, patch, 'financial_account.updated'));
+};
+
+/** Post a flow's double entry: a ledger transaction with its net balance impact, and its one entry. */
+async function post(ctx: SemanticsContext, o: {
+  financial_account: string; amount: number; currency: string; flow: string; flow_type: string;
+  status: 'open' | 'posted'; balance_impact: Row; description: string; flowDetailKey?: string;
+}): Promise<string> {
+  const now = ctx.now();
+  const txnId = ctx.mint(TX);
+  await ctx.write(TX, txnId, {
+    object: 'treasury.transaction', created: now, livemode: false,
+    amount: o.amount, currency: o.currency, financial_account: o.financial_account,
+    flow: o.flow, flow_type: o.flow_type, flow_details: null,
+    status: o.status, balance_impact: o.balance_impact, description: o.description,
+    entries: { object: 'list', has_more: false, url: `/v1/treasury/transaction_entries?transaction=${txnId}`, data: [] },
+    status_transitions: { posted_at: o.status === 'posted' ? now : null, void_at: null },
+  }, 'treasury_transaction.created');
+  await ctx.write(ENTRY, ctx.mint(ENTRY), {
+    object: 'treasury.transaction_entry', created: now, livemode: false,
+    amount: o.amount, currency: o.currency, financial_account: o.financial_account,
+    flow: o.flow, flow_type: o.flow_type,
+    flow_details: o.flowDetailKey ? { type: o.flowDetailKey, [o.flowDetailKey]: o.flow } : null,
+    transaction: txnId, effective_at: now,
+    balance_impact: o.balance_impact,
+    // what the entry records: its flow's kind where Stripe names one (docs.stripe.com/api/treasury/transaction_entries/object);
+    // a vendor `type`, kept apart from the kernel's row type
+    _stripe_type: ENTRY_TYPES.has(String(o.flow_type)) ? o.flow_type : 'other',
+  }, 'treasury_transaction_entry.created');
+  // the account's balance moves by the entry's impact: cash "Funds the user can spend right now", inbound_pending
+  // "Funds not spendable yet", outbound_pending "held for pending outbound flows" (the served spec's balance)
+  const account = ctx.get(FA, o.financial_account);
+  if (account) {
+    const bal = (account.balance as Record<string, Record<string, number>> | undefined) ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
+    const moved = Object.fromEntries((['cash', 'inbound_pending', 'outbound_pending'] as const).map((k) => [k, { ...(bal[k] ?? {}), [o.currency]: ((bal[k] ?? {})[o.currency] ?? 0) + (Number(o.balance_impact[k]) || 0) }]));
+    await ctx.write(FA, o.financial_account, { balance: moved }, 'financial_account.balance_updated');
+  }
+  return txnId;
+}
+
+/** The request's funding account, or the refusal. */
+function fundingAccount(ctx: SemanticsContext): string | Response {
+  const bad = validateMoney(ctx.params);
+  if (bad) return send(ctx, bad);
+  const fa = typeof ctx.params.financial_account === 'string' ? ctx.params.financial_account : '';
+  if (!fa) return fail(ctx, 'Missing required param: financial_account.', 400, 'parameter_missing');
+  return ctx.get(FA, fa) ? fa : faMissing(ctx, fa, 400);
+}
+
+const noTransitions = { canceled_at: null, failed_at: null, posted_at: null, returned_at: null };
+
+/** Where an outbound flow sends its money, as the served spec's payment method details give it: the bank account's
+ *  holder type, last four digits and routing number from what the request sent (a saved method's, or the test bank's
+ *  when none is given), and its billing details (required): the name and email sent, the address lines null where not
+ *  given. Where the documentation stops and the twin decides: a saved method's details are the test bank's. */
+function destinationDetails(ctx: SemanticsContext, dest: string | null): Row {
+  const data = ctx.params.destination_payment_method_data && typeof ctx.params.destination_payment_method_data === 'object' ? (ctx.params.destination_payment_method_data as Row) : {};
+  const bank = data.us_bank_account && typeof data.us_bank_account === 'object' ? (data.us_bank_account as Row) : {};
+  const billing = data.billing_details && typeof data.billing_details === 'object' ? (data.billing_details as Row) : {};
+  const address = billing.address && typeof billing.address === 'object' ? (billing.address as Row) : {};
+  const number = typeof bank.account_number === 'string' ? bank.account_number.replace(/\D/g, '') : '';
+  const billing_details = { name: billing.name ?? null, email: billing.email ?? null, address: Object.fromEntries(['city', 'country', 'line1', 'line2', 'postal_code', 'state'].map((k) => [k, address[k] ?? null])) };
+  if (dest && data.type === undefined && dest.startsWith('fa_')) return { type: 'financial_account', financial_account: { id: dest, network: 'stripe' }, billing_details };
+  return {
+    type: 'us_bank_account', billing_details,
+    us_bank_account: { last4: number ? number.slice(-4) : '6789', network: 'ach', routing_number: typeof bank.routing_number === 'string' ? bank.routing_number : '110000000', account_holder_type: typeof bank.account_holder_type === 'string' ? bank.account_holder_type : 'individual', account_type: typeof bank.account_type === 'string' ? bank.account_type : 'checking', bank_name: 'STRIPE TEST BANK', mandate: null },
+  };
+}
+
+/** An outbound payment that names no destination: "You must provide either destination_payment_method or
+ *  destination_payment_method_data" (the served spec's outbound payment create). */
+function noDestination(ctx: SemanticsContext): Response {
+  return fail(ctx, 'You must provide either `destination_payment_method` or `destination_payment_method_data`.', 400, 'parameter_missing');
+}
+
+const outboundPayment: Semantics = async (ctx) => {
+  const fa = fundingAccount(ctx);
+  if (fa instanceof Response) return fa;
+  const dest = typeof ctx.params.destination_payment_method === 'string' ? ctx.params.destination_payment_method : null;
+  if (!dest && !(ctx.params.destination_payment_method_data && typeof ctx.params.destination_payment_method_data === 'object')) return noDestination(ctx);
+  const amount = ctx.params.amount as number;
+  const currency = String(ctx.params.currency);
+  const id = ctx.mint('treasury.outbound_payment');
+  const txn = await post(ctx, { financial_account: fa, amount: -amount, currency, flow: id, flow_type: 'outbound_payment', status: 'open', balance_impact: { cash: -amount, inbound_pending: 0, outbound_pending: amount }, description: 'OutboundPayment' });
+  return ctx.reply(
+    await created(ctx, 'treasury.outbound_payment', { id }, {
+      amount, currency, financial_account: fa, livemode: false, status: 'processing', cancelable: true,
+      destination_payment_method: dest,
+      destination_payment_method_details: destinationDetails(ctx, dest),
+      destination_payment_method_data: null, end_user_details: null, expected_arrival_date: Number(ctx.now()) + 2 * 86400,
+      hosted_regulatory_receipt_url: null, returned_details: null, statement_descriptor: (ctx.params.statement_descriptor as string) ?? 'payment',
+      description: typeof ctx.params.description === 'string' ? ctx.params.description : null, transaction: txn, status_transitions: noTransitions, metadata: metadataOf(ctx),
+    }),
+  );
+};
+
+const outboundTransfer: Semantics = async (ctx) => {
+  const fa = fundingAccount(ctx);
+  if (fa instanceof Response) return fa;
+  const dest = typeof ctx.params.destination_payment_method === 'string' ? ctx.params.destination_payment_method : null;
+  const amount = ctx.params.amount as number;
+  const currency = String(ctx.params.currency);
+  const id = ctx.mint('treasury.outbound_transfer');
+  const txn = await post(ctx, { financial_account: fa, amount: -amount, currency, flow: id, flow_type: 'outbound_transfer', status: 'open', balance_impact: { cash: -amount, inbound_pending: 0, outbound_pending: amount }, description: 'OutboundTransfer' });
+  return ctx.reply(
+    await created(ctx, 'treasury.outbound_transfer', { id }, {
+      amount, currency, financial_account: fa, livemode: false, status: 'processing', cancelable: true,
+      destination_payment_method: dest, destination_payment_method_details: destinationDetails(ctx, dest),
+      expected_arrival_date: Number(ctx.now()) + 2 * 86400, hosted_regulatory_receipt_url: null,
+      returned_details: null, statement_descriptor: (ctx.params.statement_descriptor as string) ?? 'transfer',
+      description: typeof ctx.params.description === 'string' ? ctx.params.description : null, transaction: txn, status_transitions: noTransitions, metadata: metadataOf(ctx),
+    }),
+  );
+};
+
+/** The bank account an inbound transfer may pull from: "You must first set up the account-attached payment method for
+ *  inbound flows and verify the bank account using a SetupIntent", and invalid ones ("of unsupported types, containing
+ *  an unverified bank account, or not set up for inbound flows") "throw the same errors as in live mode"
+ *  (docs.stripe.com/treasury/moving-money/financial-accounts/into/inbound-transfers). A payment method is set up for
+ *  inbound flows by a SetupIntent whose flow_directions holds `inbound`, and verified when that SetupIntent succeeded
+ *  ("The bank account has been instantly verified or verification isn't necessary", its `succeeded` status,
+ *  docs.stripe.com/treasury/connect/legacy/v1/moving-money/working-with-bankaccount-objects).
+ *  Where the documentation stops and the twin decides: the page quotes no error, so the twin answers the documented code
+ *  for the class, payment_method_unexpected_state ("The provided payment method's state was incompatible with the
+ *  operation you were trying to perform", docs.stripe.com/error-codes), in its own words; an existing verified
+ *  BankAccount (`ba_`), which the page also allows, is not checked. Answers the payment method, or the refusal. */
+function inboundOrigin(ctx: SemanticsContext, origin: string): Row | Response | undefined {
+  if (origin.startsWith('ba_')) return undefined;
+  const pm = ctx.get('payment_method', origin);
+  if (!pm) return fail(ctx, `No such PaymentMethod: '${origin}'`, 400, 'resource_missing');
+  if (pm.type !== 'us_bank_account') return fail(ctx, `The PaymentMethod '${origin}' is of type ${String(pm.type)}; an InboundTransfer pulls from a us_bank_account.`, 400, 'payment_method_unexpected_state');
+  const setUp = ctx.rows('setup_intent').some((si) => si.payment_method === origin && si.status === 'succeeded' && Array.isArray(si.flow_directions) && si.flow_directions.map(String).includes('inbound'));
+  if (!setUp) return fail(ctx, `The PaymentMethod '${origin}' has not been set up for inbound flows and verified with a SetupIntent.`, 400, 'payment_method_unexpected_state');
+  return pm;
+}
+
+const inboundTransfer: Semantics = async (ctx) => {
+  const fa = fundingAccount(ctx);
+  if (fa instanceof Response) return fa;
+  const origin = typeof ctx.params.origin_payment_method === 'string' ? ctx.params.origin_payment_method : '';
+  if (!origin) return fail(ctx, 'Missing required param: origin_payment_method.', 400, 'parameter_missing');
+  const pm = inboundOrigin(ctx, origin);
+  if (pm instanceof Response) return pm;
+  const bank = (pm?.us_bank_account ?? {}) as Row;
+  const billing = (pm?.billing_details ?? {}) as Row;
+  // the debit mandate the account's verification made (docs.stripe.com/payments/setup-intents#mandates)
+  const mandate = ctx.rows('setup_intent').find((si) => si.payment_method === origin && si.status === 'succeeded' && typeof si.mandate === 'string')?.mandate;
+  const amount = ctx.params.amount as number;
+  const currency = String(ctx.params.currency);
+  const id = ctx.mint('treasury.inbound_transfer');
+  // it starts processing, its funds pending inbound, until confirmed (succeedInbound)
+  const txn = await post(ctx, { financial_account: fa, amount, currency, flow: id, flow_type: 'inbound_transfer', status: 'open', balance_impact: { cash: 0, inbound_pending: amount, outbound_pending: 0 }, description: 'InboundTransfer', flowDetailKey: 'inbound_transfer' });
+  return ctx.reply(
+    await created(ctx, 'treasury.inbound_transfer', { id }, {
+      amount, currency, financial_account: fa, origin_payment_method: origin, livemode: false,
+      status: 'processing', cancelable: true, returned: null,
+      // the pulled account as its payment method holds it
+      origin_payment_method_details: {
+        type: 'us_bank_account',
+        us_bank_account: { last4: bank.last4 ?? '6789', routing_number: bank.routing_number ?? '110000000', bank_name: bank.bank_name ?? 'STRIPE TEST BANK', account_holder_type: bank.account_holder_type ?? null, account_type: bank.account_type ?? null, fingerprint: bank.fingerprint ?? null, ...(mandate ? { mandate } : {}), network: 'ach' },
+        billing_details: { address: billing.address ?? {}, email: billing.email ?? null, name: billing.name ?? null },
+      },
+      failure_details: null, hosted_regulatory_receipt_url: null,
+      linked_flows: { received_debit: null }, statement_descriptor: (ctx.params.statement_descriptor as string) ?? 'transfer',
+      description: typeof ctx.params.description === 'string' ? ctx.params.description : null, transaction: txn, status_transitions: { succeeded_at: null, failed_at: null, canceled_at: null },
+      metadata: metadataOf(ctx),
+    }),
+  );
+};
+
+// test mode's stand-ins for money another party sends to the account or pulls from it
+// (docs.stripe.com/treasury/moving-money/receiving-funds, docs.stripe.com/api/treasury/received_credits/test_mode_create)
+function received(kind: 'received_credit' | 'received_debit'): Semantics {
+  return async (ctx) => {
+    const fa = fundingAccount(ctx);
+    if (fa instanceof Response) return fa;
+    const network = typeof ctx.params.network === 'string' ? ctx.params.network : '';
+    if (!['ach', 'us_domestic_wire', 'stripe'].includes(network)) return fail(ctx, 'Missing required param: network.', 400, 'parameter_missing');
+    const amount = ctx.params.amount as number;
+    const currency = String(ctx.params.currency);
+    const id = ctx.mint(`treasury.${kind}`);
+    const signed = kind === 'received_credit' ? amount : -amount;
+    const txn = await post(ctx, { financial_account: fa, amount: signed, currency, flow: id, flow_type: kind, status: 'posted', balance_impact: { cash: signed, inbound_pending: 0, outbound_pending: 0 }, description: kind === 'received_credit' ? 'ReceivedCredit' : 'ReceivedDebit', flowDetailKey: kind });
+    return ctx.reply(
+      await created(ctx, `treasury.${kind}`, { id }, {
+        amount, currency, financial_account: fa, network, livemode: false, status: 'succeeded', failure_code: null,
+        description: typeof ctx.params.description === 'string' ? ctx.params.description : kind === 'received_credit' ? 'Received credit' : 'Received debit',
+        hosted_regulatory_receipt_url: null, transaction: txn, reversal_details: null,
+        initiating_payment_method_details: { type: 'us_bank_account', billing_details: { address: {}, email: null, name: null }, us_bank_account: { bank_name: 'STRIPE TEST BANK', last4: '6789', routing_number: '110000000' } },
+        linked_flows: kind === 'received_credit' ? { credit_reversal: null, issuing_authorization: null, issuing_transaction: null, source_flow: null, source_flow_type: null } : { debit_reversal: null, inbound_transfer: null, issuing_authorization: null, issuing_transaction: null, payout: null },
+      }),
+    );
+  };
+}
+
+/** Test mode's confirmation of a processing inbound transfer: it succeeds, its transaction posts and the pending funds
+ *  become cash ("The status changes to succeeded once the funds have been "confirmed" and a transaction is created and
+ *  posted", docs.stripe.com/api/treasury/inbound_transfers). */
+const succeedInbound: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  const flow = ctx.get('treasury.inbound_transfer', id);
+  if (!flow) return fail(ctx, `No such inbound transfer: '${id}'`, 404, 'resource_missing');
+  const refused = ctx.legal('treasury.inbound_transfer', 'status', 'PostTestHelpersTreasuryInboundTransfersIdSucceed', flow.status, 'succeeded', id);
+  if (refused) return ctx.refuse(refused);
+  const txn = typeof flow.transaction === 'string' ? ctx.get(TX, flow.transaction) : undefined;
+  const amount = Number(flow.amount) || 0;
+  const cur = String(flow.currency ?? 'usd');
+  if (txn && txn.status === 'open') {
+    await ctx.write(TX, String(txn.id), { status: 'posted', balance_impact: { cash: amount, inbound_pending: 0, outbound_pending: 0 }, status_transitions: { ...(txn.status_transitions as object), posted_at: ctx.now() } }, 'treasury_transaction.posted');
+    const account = ctx.get(FA, String(txn.financial_account));
+    if (account) {
+      const bal = (account.balance as Record<string, Record<string, number>> | undefined) ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
+      await ctx.write(FA, String(account.id), { balance: { ...bal, cash: { ...(bal.cash ?? {}), [cur]: ((bal.cash ?? {})[cur] ?? 0) + amount }, inbound_pending: { ...(bal.inbound_pending ?? {}), [cur]: ((bal.inbound_pending ?? {})[cur] ?? 0) - amount } } }, 'financial_account.balance_updated');
+    }
+  }
+  return ctx.reply(await ctx.write('treasury.inbound_transfer', id, { status: 'succeeded', cancelable: false, status_transitions: { ...(flow.status_transitions as object), succeeded_at: ctx.now() } }, 'inbound_transfer.succeeded'));
+};
+
+/** Cancel a flow still processing; an outbound one must also still be cancelable. */
+function cancel(resource: string, param: string, name: string, operationId: string, op: string, checkCancelable: boolean): Semantics {
+  return async (ctx) => {
+    const id = at(ctx, param);
+    const flow = ctx.get(resource, id);
+    if (!flow) return fail(ctx, `No such ${name}: '${id}'`, 404, 'resource_missing');
+    // a processing flow that is no longer cancelable is refused as one no longer processing
+    const refused = ctx.legal(resource, 'status', operationId, checkCancelable && flow.cancelable !== true ? 'not_cancelable' : flow.status, undefined, id);
+    if (refused) return ctx.refuse(refused);
+    // a canceled flow's open transaction is voided and what it held returns to the account (the reverse of its
+    // balance impact). Where the documentation stops and the twin decides: a flow already posted is only marked canceled
+    const txn = typeof flow.transaction === 'string' ? ctx.get(TX, flow.transaction) : undefined;
+    if (txn && txn.status === 'open') {
+      await ctx.write(TX, String(txn.id), { status: 'void', status_transitions: { ...(txn.status_transitions as object), void_at: ctx.now() } }, 'treasury_transaction.voided');
+      const account = ctx.get(FA, String(txn.financial_account));
+      const impact = (txn.balance_impact as Record<string, number> | undefined) ?? {};
+      const cur = String(txn.currency ?? 'usd');
+      if (account) {
+        const bal = (account.balance as Record<string, Record<string, number>> | undefined) ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
+        const back = Object.fromEntries((['cash', 'inbound_pending', 'outbound_pending'] as const).map((k) => [k, { ...(bal[k] ?? {}), [cur]: ((bal[k] ?? {})[cur] ?? 0) - (Number(impact[k]) || 0) }]));
+        await ctx.write(FA, String(account.id), { balance: back }, 'financial_account.balance_updated');
+      }
+    }
+    return ctx.reply(await ctx.write(resource, id, { status: 'canceled', cancelable: false, status_transitions: { ...(flow.status_transitions as object), canceled_at: ctx.now() } }, op));
+  };
+}
+
+// the ledger is always read for one account
+function ledger(resource: string, spec: Record<string, (r: Row, v: unknown) => boolean>): Semantics {
+  return async (ctx) => {
+    if (typeof ctx.params.financial_account !== 'string' || !ctx.params.financial_account) return fail(ctx, 'Missing required param: financial_account.', 400, 'parameter_missing');
+    return list(ctx, resource, where(ctx, newest(ctx, resource), spec));
+  };
+}
+
+export const treasury: Record<string, Semantics> = {
+  PostTreasuryFinancialAccounts: open,
+  GetTreasuryFinancialAccountsFinancialAccountFeatures: features,
+  PostTreasuryFinancialAccountsFinancialAccountFeatures: features,
+  PostTreasuryFinancialAccountsFinancialAccount: updateAccount,
+  PostTreasuryOutboundPayments: outboundPayment,
+  PostTreasuryOutboundPaymentsIdCancel: cancel('treasury.outbound_payment', 'id', 'outbound payment', 'PostTreasuryOutboundPaymentsIdCancel', 'outbound_payment.canceled', true),
+  PostTreasuryOutboundTransfers: outboundTransfer,
+  PostTreasuryOutboundTransfersOutboundTransferCancel: cancel('treasury.outbound_transfer', 'outbound_transfer', 'outbound transfer', 'PostTreasuryOutboundTransfersOutboundTransferCancel', 'outbound_transfer.canceled', true),
+  PostTreasuryInboundTransfers: inboundTransfer,
+  PostTestHelpersTreasuryInboundTransfersIdSucceed: succeedInbound,
+  PostTestHelpersTreasuryReceivedCredits: received('received_credit'),
+  PostTestHelpersTreasuryReceivedDebits: received('received_debit'),
+  PostTreasuryInboundTransfersInboundTransferCancel: cancel('treasury.inbound_transfer', 'inbound_transfer', 'inbound transfer', 'PostTreasuryInboundTransfersInboundTransferCancel', 'inbound_transfer.canceled', false),
+  GetTreasuryTransactions: ledger(TX, {
+    financial_account: (r, v) => r.financial_account === v, status: (r, v) => r.status === v,
+    flow: (r, v) => r.flow === v, flow_type: (r, v) => r.flow_type === v,
+  }),
+  GetTreasuryTransactionEntries: ledger(ENTRY, {
+    financial_account: (r, v) => r.financial_account === v, flow: (r, v) => r.flow === v, transaction: (r, v) => r.transaction === v,
+  }),
+};