@volter/twin-stripe 2.0.38 → 3.0.1

package/src/screens/financial-connections.tsx

@@ -1,101 +0,0 @@
-// STRIPE FINANCIAL CONNECTIONS — a hosted flow (docs/contributing/architecture.md, "Screens"): an application
-// creates a Financial Connections Session for an account holder and the permissions it wants, and hands its
-// client_secret to Stripe.js, whose authentication flow lets the holder pick their bank and the accounts to share;
-// the linked accounts are then on the session and readable through the Accounts API, with balances and
-// transactions when the permissions asked for them (docs.stripe.com/financial-connections/fundamentals,
-// docs.stripe.com/financial-connections/other-data-powered-products). In test mode the bank is Stripe's test
-// institution (docs.stripe.com/financial-connections/testing). Linking is the holder's move, not an API call.
-// Authored from @volter/world-ui's consent piece under Stripe's skin; nothing of Stripe's page is copied.
-//
-// The flow is opened with the session's client_secret, never its id: the session's own documentation says "The
-// session's client_secret can be used to launch the flow using Stripe.js", and stripe.collectFinancialConnectionsAccounts
-// takes `clientSecret`, "The client_secret of the Financial Connections Session"
-// (docs.stripe.com/js/financial_connections/collect_financial_connections_accounts).
-// Where the documentation stops and the twin decides: the page is served at
-// js.stripe.com/v3/financial-connections/{client_secret}, the twin's address for the "on-page modal UI" Stripe.js
-// loads (the twin's stripe.js navigates there, ../stripe-js.ts); an id or an unknown secret finds no flow;
-// the test institution holds a checking account (•••• 6789) and a savings account (•••• 4321); a linked account's
-// balance and its three transactions are the twin's test data.
-import { semanticsContext, type SemanticsContext } from '@volter/world-core';
-import { Consent, CONSENT_CSS, flowPage } from '@volter/world-ui';
-import surface from '../generated/surface.gen.json' with { type: 'json' };
-import { manifest } from '../manifest.ts';
-import { created, type Row } from '../semantics/shared.ts';
-import { formOf, seeOther, STRIPE_CONSENT_SKIN } from './consent-skin.ts';
-
-const FCS = 'financial_connections.session';
-const FCA = 'financial_connections.account';
-const FCT = 'financial_connections.transaction';
-const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'GetFinancialConnectionsSessionsSession')!;
-const css = [CONSENT_CSS, STRIPE_CONSENT_SKIN];
-
-const TEST_ACCOUNTS = [
-  { last4: '6789', subcategory: 'checking', display_name: 'Checking', balance: 125_000 },
-  { last4: '4321', subcategory: 'savings', display_name: 'Savings', balance: 980_000 },
-];
-
-const message = (status: number, text: string): Response => flowPage({ title: 'Link your account', status, css, body: <main className="consent"><h1 className="consent-heading">{text}</h1></main> });
-const permissionsOf = (session: Row): string[] => (Array.isArray(session.permissions) ? session.permissions.map(String) : []);
-
-function page(secret: string, session: Row): Response {
-  const says: Record<string, string> = { balances: 'Account balances', ownership: 'Account ownership details', payment_method: 'Account and routing numbers', transactions: 'Transactions' };
-  return flowPage({
-    title: 'Link your account',
-    css,
-    body: (
-      <Consent
-        heading="Link your account"
-        app={{ name: 'Test Institution' }}
-        request={`Test mode · ${TEST_ACCOUNTS.map((a) => `${a.display_name} •••• ${a.last4}`).join(', ')}`}
-        permissions={permissionsOf(session).map((p) => ({ title: says[p] ?? p, detail: 'Shared with the business through Stripe' }))}
-        action={`/v3/financial-connections/${secret}`}
-        fields={{}}
-        deny={{ name: 'answer', value: 'cancel', label: 'Cancel' }}
-        allow={{ name: 'answer', value: 'link', label: 'Link accounts' }}
-        note="Stripe will share the data above with the business."
-      />
-    ),
-  });
-}
-
-/** The holder links the test institution's accounts to the session. */
-async function link(ctx: SemanticsContext, id: string, session: Row): Promise<void> {
-  const permissions = permissionsOf(session);
-  const now = Number(ctx.now());
-  for (const a of TEST_ACCOUNTS) {
-    const account = await created(ctx, FCA, { session: id }, {
-      livemode: false, status: 'active', account_holder: session.account_holder ?? null, institution_name: 'StripeBank', display_name: a.display_name,
-      last4: a.last4, category: 'cash', subcategory: a.subcategory, supported_payment_method_types: ['us_bank_account', 'link'], permissions,
-      balance: permissions.includes('balances') ? { as_of: now, type: 'cash', cash: { available: { usd: a.balance } }, current: { usd: a.balance } } : null,
-      balance_refresh: permissions.includes('balances') ? { status: 'succeeded', last_attempted_at: now, next_refresh_available_at: null } : null,
-      transaction_refresh: permissions.includes('transactions') ? { id: `fctxnref_${a.last4}`, status: 'succeeded', last_attempted_at: now, next_refresh_available_at: null } : null,
-      ownership: null, ownership_refresh: null, subscriptions: [],
-    });
-    if (!permissions.includes('transactions')) continue;
-    for (const [i, t] of [{ amount: -4_250, description: 'COFFEE ROASTERS' }, { amount: -12_000, description: 'CITY UTILITIES' }, { amount: 250_000, description: 'PAYROLL DEPOSIT' }].entries()) {
-      await created(ctx, FCT, { account: account.id }, {
-        livemode: false, amount: t.amount, currency: 'usd', description: t.description, status: 'posted',
-        status_transitions: { posted_at: now - (3 - i) * 86_400, void_at: null }, transacted_at: now - (3 - i) * 86_400, transaction_refresh: `fctxnref_${a.last4}`, updated: now,
-      });
-    }
-  }
-}
-
-/** The authentication flow Stripe.js opens, or undefined for any other request. */
-export function stripeFinancialConnectionsFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
-  return async (request) => {
-    const m = /^\/v3\/financial-connections\/([A-Za-z0-9_]+)\/?$/.exec(new URL(request.url).pathname);
-    if (!m || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
-    const secret = m[1]!;
-    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
-    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
-    const session = ctx.rows(FCS).find((s) => s.client_secret === secret);
-    if (!session) return message(404, 'This link has expired.');
-    const id = String(session.id);
-    if (ctx.rows(FCA).some((a) => a.session === id)) return message(200, 'Your accounts are linked.');
-    if (request.method === 'GET') return page(secret, session);
-    if (form.answer === 'link') await link(ctx, id, session);
-    const back = typeof session.return_url === 'string' && session.return_url ? session.return_url : undefined;
-    return back ? seeOther(back) : message(200, form.answer === 'link' ? 'Your accounts are linked.' : 'No accounts were linked.');
-  };
-}

package/src/screens/identity.tsx

@@ -1,96 +0,0 @@
-// STRIPE IDENTITY — a hosted flow (docs/contributing/architecture.md, "Screens"): an application creates a
-// VerificationSession and sends the person to its `url` at verify.stripe.com/start/{session}; they submit their
-// ID there, the session is processing and then verified, with a VerificationReport of what was checked, or it
-// asks for input again with the reason in last_error; the person returns to return_url
-// (docs.stripe.com/identity/how-sessions-work, docs.stripe.com/identity/verification-sessions). In test mode the
-// page offers the outcome instead of a camera (the twin's decision: docs.stripe.com/identity/testing, once cited
-// for it, no longer answers). Submitting is the person's move
-// (the session machine's external actor) and the check Stripe's (its vendor moves). Authored from
-// @volter/world-ui's consent piece under Stripe's skin; nothing of Stripe's page is copied.
-//
-// Where the documentation stops and the twin decides: test mode's person is Jenny Rosen with a driving licence,
-// the name Stripe's test reports carry; a failed check is document_unverified_other.
-import { semanticsContext, type SemanticsContext } from '@volter/world-core';
-import { Consent, CONSENT_CSS, flowPage } from '@volter/world-ui';
-import surface from '../generated/surface.gen.json' with { type: 'json' };
-import { manifest } from '../manifest.ts';
-import { created, type Row } from '../semantics/shared.ts';
-import { formOf, seeOther, STRIPE_CONSENT_SKIN } from './consent-skin.ts';
-
-const VS = 'identity.verification_session';
-const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'GetIdentityVerificationSessionsSession')!;
-const css = [CONSENT_CSS, STRIPE_CONSENT_SKIN];
-
-const message = (status: number, text: string): Response => flowPage({ title: 'Stripe Identity', status, css, body: <main className="consent"><h1 className="consent-heading">{text}</h1></main> });
-
-function page(id: string, session: Row): Response {
-  const kind = session.type === 'id_number' ? 'ID number' : 'Government-issued photo ID';
-  return flowPage({
-    title: 'Verify your identity',
-    css,
-    body: (
-      <Consent
-        heading="Verify your identity"
-        app={{ name: 'Stripe Identity' }}
-        request="Test mode: choose how the verification ends"
-        permissions={[
-          { title: kind, detail: 'Test data: Jenny Rosen, driving licence' },
-          ...(((session.options as Row | undefined)?.document as Row | undefined)?.require_matching_selfie === true ? [{ title: 'Selfie', detail: 'Matched to the ID photo' }] : []),
-        ]}
-        action={`/start/${id}`}
-        fields={{}}
-        deny={{ name: 'outcome', value: 'unverified', label: 'Fail verification' }}
-        allow={{ name: 'outcome', value: 'verified', label: 'Verify' }}
-        note="Stripe uses this data only to verify your identity."
-      />
-    ),
-  });
-}
-
-/** The person submits; Stripe checks and writes the report, and the session is verified or asks again. */
-async function submit(ctx: SemanticsContext, id: string, session: Row, verified: boolean): Promise<void> {
-  if (ctx.legal(VS, 'status', OPERATION.id, String(session.status), 'processing', id, 'external')) return;
-  // Stripe's check decides the processing session at once: the second move of the one write below
-  ctx.legal(VS, 'status', OPERATION.id, 'processing', verified ? 'verified' : 'requires_input', id, 'vendor');
-  const type = session.type === 'id_number' ? 'id_number' : 'document';
-  const error = verified ? null : { code: 'document_unverified_other', reason: 'The document could not be verified.' };
-  // a document check holds its images: files "Array of File ids containing images for this document" (the served
-  // spec's document report). Where the documentation stops and the twin decides: the licence's front and back, two
-  // identity_document files, as the published report's two
-  const images: string[] = [];
-  if (type === 'document') for (const side of ['front', 'back']) {
-    const f = await created(ctx, 'file', { purpose: 'identity_document' }, { filename: `driving_license_${side}.jpg`, size: 0, type: 'jpg', title: null, expires_at: null, url: null, links: { object: 'list', data: [], has_more: false, url: '' } });
-    images.push(String(f.id));
-  }
-  // the report records the options the session was checked with (the session's own, as its object answers them)
-  const sessionOptions = (session.options as Row | undefined) ?? {};
-  const report = await created(ctx, 'identity.verification_report', { verification_session: id, type }, {
-    livemode: false, client_reference_id: session.client_reference_id ?? null,
-    document: type === 'document' ? { status: verified ? 'verified' : 'unverified', type: 'driving_license', first_name: 'Jenny', last_name: 'Rosen', address: null, dob: null, error, files: images } : null,
-    id_number: type === 'id_number' ? { status: verified ? 'verified' : 'unverified', id_number_type: 'us_ssn', first_name: 'Jenny', last_name: 'Rosen', dob: null, error } : null,
-    selfie: null, email: null, phone: null,
-    options: type === 'document' ? { document: (sessionOptions.document as Row | undefined) ?? {} } : { id_number: (sessionOptions.id_number as Row | undefined) ?? {} },
-  });
-  // the url "can only be used once" (the served spec): spent by the submission, as the verification sessions page's
-  // examples answer a verified and a requires_input session with url null
-  await ctx.write(VS, id, verified
-    ? { status: 'verified', last_verification_report: report.id, last_error: null, url: null, client_secret: null, verified_outputs: { first_name: 'Jenny', last_name: 'Rosen' } }
-    : { status: 'requires_input', last_verification_report: report.id, last_error: error, url: null }, verified ? 'verification_session.verified' : 'verification_session.requires_input');
-}
-
-/** verify.stripe.com's pages, or undefined for any other request. */
-export function stripeIdentityFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
-  return async (request) => {
-    const m = /^\/start\/(vs_[A-Za-z0-9_]+)\/?$/.exec(new URL(request.url).pathname);
-    if (!m || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
-    const id = m[1]!;
-    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
-    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
-    const session = ctx.get(VS, id);
-    if (!session) return message(404, 'This verification link is invalid.');
-    if (session.status !== 'requires_input') return message(200, session.status === 'verified' ? 'You are verified.' : 'This verification has ended.');
-    if (request.method === 'GET') return page(id, session);
-    await submit(ctx, id, session, form.outcome === 'verified');
-    return typeof session.return_url === 'string' && session.return_url ? seeOther(session.return_url) : message(200, form.outcome === 'verified' ? 'You are verified.' : 'We could not verify your identity.');
-  };
-}

package/src/screens/public-details.tsx

@@ -1,105 +0,0 @@
-// THE DASHBOARD'S PUBLIC DETAILS — a workspace page (docs/contributing/architecture.md, "Screens") of the Dashboard
-// (manifest screen `dashboard`), at dashboard.stripe.com/settings/public: Settings → Business → Public details, where
-// the operator sets what their customers see ("Public Details → Business Settings",
-// support.stripe.com/questions/update-account-name-shown-in-the-dashboard). Its business name is the account's
-// `business_profile.name`, "The customer-facing business name" (docs.stripe.com/api/accounts/object), and it is the
-// name Checkout shows: "You can change a Checkout page's name by modifying the Business name field"
-// (docs.stripe.com/payments/checkout/customization/appearance). Stripe's API has no call that changes the platform's
-// own account (POST /v1/accounts/{account} updates a connected one), so this page is the only way to the act, and
-// saving it writes the platform account's stored record (semantics/connect.ts `platform`), which GET /v1/account,
-// Checkout and the customer portal then read. The Dashboard's account name (`settings.dashboard.display_name`,
-// Settings → Account) is a separate, internal setting, "for internal use only" (the same support article), and this
-// page does not touch it. Authored from plain markup under Stripe's type; nothing of Stripe's page is copied.
-//
-// Where the documentation stops and the twin decides: the page holds the business name only (the real page's
-// support details, website and statement descriptor are not modelled here); the name is required and at most 5000
-// characters (the spec's bound on business_profile.name), which the browser holds the field to and the page checks
-// again for a client that is not a browser; no sign-in guards the page, as none guards the Dashboard mirror. The page
-// is matched by its path on whatever host reaches the twin (the World routes only dashboard.stripe.com's
-// /settings/public here; the local mirror serves it on its own origin), and the form posts to the page's own address
-// and the save redirects to its own path, so it also works under the hosted mirror's path prefix. Saving is an update of an account that exists (the first save included, though
-// the twin stores the platform's record only then), so every save is sent as account.updated.
-import { semanticsContext, type SemanticsContext } from '@volter/world-core';
-import { flowPage } from '@volter/world-ui';
-import surface from '../generated/surface.gen.json' with { type: 'json' };
-import { manifest } from '../manifest.ts';
-import { platformAccountDefault } from '../semantics/connect.ts';
-import { created, type Row } from '../semantics/shared.ts';
-import { publicBusinessName } from '../stripe-shared.ts';
-import { PLATFORM_ACCOUNT_ID } from '../stripe-twin.ts';
-import { formOf } from './consent-skin.ts';
-
-export const PUBLIC_DETAILS_PATH = '/settings/public';
-const MAX_NAME = 5000;
-const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'PostAccountsAccount')!;
-
-const CSS = `
-* { box-sizing: border-box; }
-body { margin: 0; background: #f6f8fa; color: #1a1f36; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; font-size: 14px; }
-.pd { max-width: 640px; margin: 48px auto; padding: 0 16px; }
-.pd h1 { font-size: 28px; margin: 16px 0 4px; }
-.pd-lead { color: #697386; margin: 0 0 24px; }
-.pd-card { background: #ffffff; border: 1px solid #e3e8ee; border-radius: 8px; padding: 24px; }
-.pd-card label { display: block; font-weight: 600; margin-bottom: 6px; }
-.pd-card small { display: block; color: #697386; margin-bottom: 8px; }
-.pd-card input { width: 100%; padding: 8px 10px; border: 1px solid #c1c9d2; border-radius: 6px; font: inherit; }
-.pd-actions { margin-top: 20px; display: flex; justify-content: flex-end; }
-.pd-actions button { background: #635bff; color: #ffffff; border: 0; border-radius: 6px; padding: 8px 16px; font: inherit; font-weight: 600; cursor: pointer; }
-.pd-notice { padding: 10px 12px; border-radius: 6px; margin-bottom: 16px; }
-.pd-error { background: #fff0f3; color: #df1b41; }
-.pd-saved { background: #e7f8ef; color: #0e6245; }
-`;
-
-function page(account: Row | undefined, opts: { value?: string; error?: string; saved?: boolean } = {}): Response {
-  const named = (account?.business_profile as Row | undefined)?.name;
-  const value = opts.value ?? (typeof named === 'string' ? named : '');
-  return flowPage({
-    title: 'Public details – Stripe',
-    css: [CSS],
-    ...(opts.error ? { status: 400 } : {}),
-    body: (
-      <main className="pd">
-        <h1>Public details</h1>
-        <p className="pd-lead">What your customers see on Checkout, the customer portal, receipts and invoices. Currently shown: <strong data-testid="public-business-name">{publicBusinessName(account)}</strong></p>
-        {opts.error ? <p className="pd-notice pd-error" role="alert">{opts.error}</p> : null}
-        {opts.saved ? <p className="pd-notice pd-saved" role="status">Your public details were saved.</p> : null}
-        <form className="pd-card" method="post">
-          <label htmlFor="business_name">Business name</label>
-          <small>The name customers see when they pay you.</small>
-          <input id="business_name" name="business_name" autoComplete="organization" defaultValue={value} required maxLength={MAX_NAME} />
-          <div className="pd-actions"><button type="submit">Save</button></div>
-        </form>
-      </main>
-    ),
-  });
-}
-
-/** Save the business name on the platform's own account: the stored record, made from Stripe's default the first
- *  time anything is saved, and otherwise changed in place (its other public details kept). */
-async function save(ctx: SemanticsContext, name: string): Promise<void> {
-  const held = ctx.get('account', PLATFORM_ACCOUNT_ID);
-  const profile = { business_profile: { ...(((held ?? platformAccountDefault()).business_profile as Row | undefined) ?? {}), name } };
-  await (held ? ctx.write('account', PLATFORM_ACCOUNT_ID, profile, 'account.update') : created(ctx, 'account', { ...platformAccountDefault(), ...profile }, {}, { operation: 'account.update' }));
-}
-
-/** What the page says of a name no browser sends (the field is required and bounded), for a client that sends it. */
-function nameRefused(name: string): string | undefined {
-  return !name ? 'Enter your business name.' : name.length > MAX_NAME ? `Your business name must be at most ${MAX_NAME} characters.` : undefined;
-}
-
-export function stripePublicDetailsFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
-  return async (request) => {
-    const url = new URL(request.url);
-    if (url.pathname.replace(/\/+$/, '') !== PUBLIC_DETAILS_PATH || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
-    // the form is read before the context, which reads the request's body itself
-    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
-    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
-    if (request.method === 'GET') return page(ctx.get('account', PLATFORM_ACCOUNT_ID), { saved: url.searchParams.has('saved') });
-    const name = (form.business_name ?? '').trim();
-    const refused = nameRefused(name);
-    if (refused) return page(ctx.get('account', PLATFORM_ACCOUNT_ID), { value: form.business_name ?? '', error: refused });
-    await save(ctx, name);
-    // a query-only reference: the page's own path, wherever it is mounted and with or without its trailing slash
-    return new Response(null, { status: 303, headers: { location: '?saved=1' } });
-  };
-}

package/src/semantics/after-payment.ts

@@ -1,118 +0,0 @@
-// What Stripe does itself once a payment succeeds, which no API call asks for:
-// - a test card that is disputed opens a dispute on its charge (docs.stripe.com/testing#disputes: 4000000000000259
-//   "charge succeeds, then disputed as fraudulent", 4000000000002685 disputed as product not received,
-//   4000000000001976 an inquiry), and Stripe debits the disputed
-//   amount and its dispute fee from the balance (docs.stripe.com/disputes/how-disputes-work);
-// - a test card Radar scores as elevated risk opens a review of its charge (docs.stripe.com/testing#fraud-prevention:
-//   4000000000009235, "elevated risk", which Radar places in review; docs.stripe.com/radar/reviews);
-// - a charge a platform makes with `application_fee_amount` earns the platform an application fee, from the connected
-//   account it pays (a destination charge's `transfer_data.destination`, or the account a direct charge is made on;
-//   docs.stripe.com/connect/destination-charges, docs.stripe.com/connect/direct-charges);
-// - a bank account verified by micro-deposits for a payment or a setup carries a mandate, the customer's acceptance
-//   of debits (docs.stripe.com/payments/ach-direct-debit/accept-a-payment, docs.stripe.com/api/mandates).
-//
-// Where the documentation stops and the twin decides: evidence is due seven days after a dispute opens (Stripe's
-// deadline depends on the card network); the dispute fee is 1500 cents in any currency (Stripe's US fee is $15); an
-// elevated-risk review's risk score is 67 (Radar's elevated band); the application is `ca_twin`.
-import type { SemanticsContext } from '@volter/world-core';
-import { disputeEvidence } from '../stripe-twin.ts';
-import { actingAccount, settleApplicationFee, settleDispute, settleTransfer } from './ledger.ts';
-import { BYPASS_PENDING_CARDS } from './test-cards.ts';
-import { created, type Row } from './shared.ts';
-
-type Outcome = 'dispute' | 'dispute_not_received' | 'inquiry' | 'review' | 'available';
-const DAY = 86_400;
-
-/** The test cards whose success Stripe follows with its own act, by number and by their documented test names. */
-export const AFTER_SUCCESS_CARDS: Record<string, { brand: string; number: string; outcome: Outcome }> = {
-  pm_card_createDispute: { brand: 'visa', number: '4000000000000259', outcome: 'dispute' },
-  pm_card_createDisputeProductNotReceived: { brand: 'visa', number: '4000000000002685', outcome: 'dispute_not_received' },
-  pm_card_createDisputeInquiry: { brand: 'visa', number: '4000000000001976', outcome: 'inquiry' },
-  pm_card_riskLevelElevated: { brand: 'visa', number: '4000000000009235', outcome: 'review' },
-  // its funds go straight to the available balance (ledger.ts reads it; no act follows here)
-  ...Object.fromEntries(Object.entries(BYPASS_PENDING_CARDS).map(([name, c]) => [name, { ...c, outcome: 'available' as const }])),
-};
-const BY_NUMBER: Record<string, Outcome> = Object.fromEntries(Object.values(AFTER_SUCCESS_CARDS).map((c) => [c.number, c.outcome]));
-
-/** What Stripe does after a card succeeds: from a raw number, a test name (pm_card_* or tok_*), or a stored
- *  PaymentMethod that recorded it when it was made. */
-export function afterSuccessOf(ctx: SemanticsContext, ref: unknown): Outcome | undefined {
-  // a card given as a token (card[token], payment_method_data[card][token]) is the card the token names
-  if (ref && typeof ref === 'object' && typeof (ref as Row).token === 'string') return afterSuccessOf(ctx, (ref as Row).token);
-  if (ref && typeof ref === 'object') return BY_NUMBER[String((ref as Row).number ?? '').replace(/\D/g, '')];
-  if (typeof ref !== 'string' || !ref) return undefined;
-  const stored = ctx.row('payment_method', ref);
-  if (stored) return (stored._afterSuccess as Outcome | undefined) ?? undefined;
-  return AFTER_SUCCESS_CARDS[ref.replace(/^tok_/, 'pm_card_')]?.outcome ?? BY_NUMBER[ref.replace(/\D/g, '')];
-}
-
-/** Stripe's acts on a charge that just succeeded: a dispute or a review its card brings, and the platform's fee. */
-export async function afterCharge(ctx: SemanticsContext, chargeId: string, charge: { amount: number; currency: string; payment_intent?: string | undefined; application_fee_amount?: unknown; destination?: unknown }, ref: unknown): Promise<void> {
-  const outcome = afterSuccessOf(ctx, ref);
-  const pi = charge.payment_intent ? { payment_intent: charge.payment_intent } : { payment_intent: null };
-  const now = Number(ctx.now());
-  if (outcome === 'dispute' || outcome === 'dispute_not_received' || outcome === 'inquiry') {
-    const dispute = await created(ctx, 'dispute', { charge: chargeId, ...pi, amount: charge.amount, currency: charge.currency }, {
-      reason: outcome === 'dispute_not_received' ? 'product_not_received' : 'fraudulent', status: outcome === 'inquiry' ? 'warning_needs_response' : 'needs_response', is_charge_refundable: false,
-      evidence: disputeEvidence(), evidence_details: { due_by: now + 7 * DAY, has_evidence: false, past_due: false, submission_count: 0, enhanced_eligibility: {} },
-      balance_transactions: [], livemode: false, metadata: {}, enhanced_eligibility_types: [],
-    });
-    // an inquiry moves no money; a dispute takes the amount and its fee until it is decided
-    if (outcome !== 'inquiry') {
-      const bt = await settleDispute(ctx, String(dispute.id), charge.amount, charge.currency);
-      await ctx.write('dispute', String(dispute.id), { balance_transactions: [ctx.get('balance_transaction', bt) ?? bt] }, 'dispute.funds_withdrawn');
-    }
-    await ctx.write('charge', chargeId, { disputed: true }, 'charge.dispute.created');
-  }
-  if (outcome === 'review') await openReview(ctx, chargeId, pi);
-  const feeAmount = Math.trunc(Number(charge.application_fee_amount) || 0);
-  const destination = typeof charge.destination === 'string' && charge.destination ? charge.destination : undefined;
-  const direct = actingAccount(ctx);
-  const account = destination ?? direct;
-  // a destination charge transfers what it collected, less the platform's fee, available when the charge's funds are
-  if (destination) {
-    const amount = charge.amount - feeAmount;
-    const chargeBt = ctx.get('charge', chargeId)?.balance_transaction;
-    const availableOn = Number(ctx.get('balance_transaction', String(chargeBt))?.available_on ?? ctx.now());
-    const tr = await created(ctx, 'transfer', { amount, currency: charge.currency, destination }, {
-      amount_reversed: 0, balance_transaction: null, livemode: false, metadata: {}, reversed: false, source_type: 'card', source_transaction: chargeId,
-      reversals: { object: 'list', data: [], has_more: false, total_count: 0, url: '' },
-    });
-    const bt = await settleTransfer(ctx, String(tr.id), amount, charge.currency, destination, availableOn);
-    await ctx.write('transfer', String(tr.id), { balance_transaction: bt, destination_payment: `py_${String(tr.id).replace(/^tr_/, '')}`, reversals: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/transfers/${String(tr.id)}/reversals` } }, 'transfer.created');
-    await ctx.write('charge', chargeId, { transfer: tr.id }, 'charge.updated');
-  }
-  if (feeAmount > 0 && account) {
-    const fee = await created(ctx, 'application_fee', { account, amount: feeAmount, charge: chargeId, currency: charge.currency }, {
-      amount_refunded: 0, application: 'ca_twin', balance_transaction: null, originating_transaction: null, refunded: false, livemode: false,
-    });
-    // a direct charge's fee moves from the connected account to the platform (a destination charge kept it back)
-    const bt = !destination && direct ? await settleApplicationFee(ctx, String(fee.id), feeAmount, charge.currency, direct) : null;
-    await ctx.write('application_fee', String(fee.id), { balance_transaction: bt, refunds: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/application_fees/${String(fee.id)}/refunds` } }, 'application_fee.created');
-    await ctx.write('charge', chargeId, { application_fee: fee.id, application_fee_amount: feeAmount }, 'charge.updated');
-  }
-}
-
-/** Radar places an elevated-risk card's charge in review (docs.stripe.com/radar/reviews). */
-async function openReview(ctx: SemanticsContext, chargeId: string, pi: { payment_intent: string | null }): Promise<void> {
-  const review = await created(ctx, 'review', { charge: chargeId, ...pi }, {
-    open: true, opened_reason: 'rule', reason: 'rule', closed_reason: null, billing_zip: null, ip_address: null, ip_address_location: null, session: null, livemode: false,
-  });
-  const existing = (ctx.get('charge', chargeId)?.outcome as Row | undefined) ?? {};
-  await ctx.write('charge', chargeId, {
-    review: review.id,
-    outcome: { ...existing, type: 'manual_review', risk_level: 'elevated', risk_score: 67, seller_message: 'Stripe evaluated this payment as having elevated risk, and placed it in review.' },
-  }, 'review.opened');
-}
-
-/** The mandate a verified bank account carries for a payment (single use) or a setup (multi use). */
-export async function mintMandate(ctx: SemanticsContext, paymentMethod: unknown, use: 'single_use' | 'multi_use', amount?: number, currency?: string): Promise<string> {
-  const now = Number(ctx.now());
-  const mandate = await created(ctx, 'mandate', { payment_method: typeof paymentMethod === 'string' ? paymentMethod : null }, {
-    status: 'active', type: use, livemode: false,
-    customer_acceptance: { type: 'online', accepted_at: now, online: { ip_address: '127.0.0.1', user_agent: 'twin' } },
-    payment_method_details: { type: 'us_bank_account', us_bank_account: { collection_method: 'paper' } },
-    ...(use === 'single_use' ? { single_use: { amount: amount ?? 0, currency: currency ?? 'usd' } } : { multi_use: {} }),
-  }, { timeField: '_created' });
-  return String(mandate.id);
-}