@volter/twin-stripe 2.0.37 → 3.0.0

package/src/semantics/treasury.ts

@@ -1,383 +0,0 @@
-// 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,
-  }),
-};

package/src/semantics/webhook-endpoints.ts

@@ -1,87 +0,0 @@
-// Webhook endpoint semantics: registering a URL and the events it subscribes to. Delivery reads
-// the endpoints from the tree, signing each POST with the endpoint's own secret; a disabled one
-// (the machine in ../manifest.ts) receives nothing. Endpoint list, retrieve and delete are the derived core's.
-//
-// The Events API lists and retrieves the stored events of the account a request acts for: an event of a connected
-// account carries it ("Each event for a connected account contains a top-level `account` property that identifies the
-// connected account. Because the connected account owns the object that triggered the event, you must make API
-// requests for that object as the connected account", docs.stripe.com/connect/webhooks; the event's `account`: "The
-// connected account that originates the event", spec/openapi.json.gz), so a request with the Stripe-Account header
-// sees that account's events and one without it the platform's, those with no `account`. Where the documentation
-// stops and the twin decides: a platform request does not see its connected accounts' events.
-import { worldEnvValue, type Semantics, type SemanticsContext } from '@volter/world-core';
-import { asBool } from '../stripe-twin.ts';
-import { actingAccount } from './ledger.ts';
-import { at, created, fail, inRange, list, newest, where, type Row } from './shared.ts';
-
-const WE = 'webhook_endpoint';
-
-// The signing secret is the World's where the World set one. Stripe mints an endpoint's secret and the app is given it
-// (the dashboard, `stripe listen`); in a World the app's env is the World's, made at boot, so the World's value is the
-// one the app verifies with, and an endpoint the app registers is signed with it: the twin's decision, since Stripe
-// lets no one choose a secret. A Connect endpoint (`connect`) takes a Connect name first. Only a value the World sets
-// counts (worldEnvValue), never one the caller's shell passes through; with none (a twin outside a World) the twin
-// mints, as Stripe does.
-const ACCOUNT_SECRET_ENV = ['STRIPE_WEBHOOK_SECRET', 'STRIPE_WEBHOOK_SIGNING_SECRET', 'STRIPE_ENDPOINT_SECRET', 'STRIPE_WEBHOOK_SECRET_KEY', 'NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET'];
-const CONNECT_SECRET_ENV = ['STRIPE_CONNECT_WEBHOOK_SECRET', 'STRIPE_WEBHOOK_SECRET_CONNECT', 'STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET'];
-export function worldEndpointSecret(connect: boolean): string | undefined {
-  for (const name of connect ? [...CONNECT_SECRET_ENV, ...ACCOUNT_SECRET_ENV] : ACCOUNT_SECRET_ENV) { const value = worldEnvValue(name); if (value) return value; }
-  return undefined;
-}
-
-const create: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const url = typeof params.url === 'string' ? params.url : '';
-  if (!url) return fail(ctx, 'Missing required param: url.', 400, 'parameter_missing');
-  const enabledEvents = Array.isArray(params.enabled_events) ? params.enabled_events.map(String) : typeof params.enabled_events === 'string' ? [params.enabled_events] : undefined;
-  if (!enabledEvents || enabledEvents.length === 0) return fail(ctx, 'Missing required param: enabled_events.', 400, 'parameter_missing');
-  const id = ctx.mint(WE);
-  return ctx.reply(
-    await created(ctx, WE, { ...params, id }, {
-      url, enabled_events: enabledEvents, status: 'enabled', livemode: false, metadata: {},
-      api_version: '2024-06-20', application: null, description: typeof params.description === 'string' ? params.description : null,
-      secret: worldEndpointSecret(asBool(params.connect)) ?? `whsec_twin_${id}`,
-    }),
-  );
-};
-
-// `disabled` switches delivery off (status disabled) and back on; it is a parameter, not a field
-const update: Semantics = async (ctx) => {
-  const id = at(ctx, 'webhook_endpoint');
-  const we = ctx.get(WE, id);
-  if (!we) return ctx.notFound(WE, id);
-  const { disabled, ...fields }: Row = { ...ctx.params };
-  if (Array.isArray(ctx.params.enabled_events)) fields.enabled_events = ctx.params.enabled_events.map(String);
-  if (disabled !== undefined) return switchDelivery(ctx, id, we, fields, asBool(disabled));
-  return ctx.reply(await ctx.write(WE, id, fields, 'webhook_endpoint.update'));
-};
-
-/** `disabled` switches delivery off or back on (docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled). */
-async function switchDelivery(ctx: SemanticsContext, id: string, we: Row, fields: Row, off: boolean): Promise<Response> {
-  const status = off ? 'disabled' : 'enabled';
-  const refused = ctx.legal(WE, 'status', 'PostWebhookEndpointsWebhookEndpoint', we.status, status, id);
-  if (refused) return ctx.refuse(refused);
-  return ctx.reply(await ctx.write(WE, id, { ...fields, status }, 'webhook_endpoint.update'));
-}
-
-/** Whether a stored event is the acting account's (no `account`: the platform's). */
-const ownEvent = (ctx: SemanticsContext, e: Row): boolean => (typeof e.account === 'string' ? e.account : undefined) === actingAccount(ctx);
-
-const listEvents: Semantics = async (ctx) =>
-  list(ctx, 'event', where(ctx, newest(ctx, 'event').filter((e) => ownEvent(ctx, e)), {
-    type: (e, v) => e.type === v,
-    types: (e, v) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String(e.type)),
-    created: (e, v) => inRange(e.created, v),
-  }));
-
-const retrieveEvent: Semantics = async (ctx) => {
-  const e = ctx.get('event', at(ctx, 'id'));
-  return e && ownEvent(ctx, e) ? ctx.reply(e) : ctx.notFound('event', at(ctx, 'id'));
-};
-
-export const webhookEndpoints: Record<string, Semantics> = {
-  GetEvents: listEvents,
-  GetEventsId: retrieveEvent,
-  PostWebhookEndpoints: create,
-  PostWebhookEndpointsWebhookEndpoint: update,
-};