@volter/twin-stripe 0.1.1 → 2.0.0

package/src/semantics/connect.ts

@@ -0,0 +1,471 @@
+// Connect semantics: connected accounts (and the platform's own account), their persons,
+// capabilities, external (payout) accounts, login links, onboarding links and embedded-component
+// sessions. A new connected account is not yet active: charges and payouts are off and its
+// requirements are outstanding, as on Stripe before onboarding. Account retrieve and delete and
+// the person list are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { ACCOUNT_TYPES, accountCapabilities, accountRequirements, accountSettings, asBool, PLATFORM_ACCOUNT_ID } from '../stripe-twin.ts';
+import { currentlyDue, kindOf } from '../screens/onboarding.tsx';
+import { at, created, externalList, fail, list, newest, path, syncExternals, type Row } from './shared.ts';
+
+const accountMissing = (ctx: SemanticsContext, id: string, status = 404): Response => fail(ctx, `No such account: '${id}'`, status, 'resource_missing');
+/** The account, tombstones included where the hand-written routes looked past a deletion. */
+const accountRow = (ctx: SemanticsContext, id: string): Row | undefined => ctx.row('account', id, { withDeleted: true });
+
+// the platform's own account: stored once it is written, otherwise Stripe's default. It "controls itself" (controller
+// type `account`, docs.stripe.com/api/accounts/object), is fully onboarded with nothing due, and takes card payments
+// and transfers. Where the documentation stops and the twin decides: it was created as the World began (2026-01-01),
+// and its bank account, which its automatic payouts reach, is not modelled, so it lists none.
+const PLATFORM_CREATED = 1_767_225_600;
+/** The platform's own account as Stripe's default has it, before anything is written to it. */
+export const platformAccountDefault = (): Row => ({
+  object: 'account', id: PLATFORM_ACCOUNT_ID, type: 'standard', country: 'US', default_currency: 'usd', created: PLATFORM_CREATED,
+  charges_enabled: true, payouts_enabled: true, details_submitted: true, email: null, metadata: {},
+  capabilities: { card_payments: 'active', transfers: 'active' }, controller: { type: 'account' },
+  requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+  future_requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+  external_accounts: externalList(PLATFORM_ACCOUNT_ID, []), tos_acceptance: { date: null, ip: null, user_agent: null }, business_profile: {},
+  settings: accountSettings(undefined), livemode: false,
+});
+const platform: Semantics = async (ctx) => ctx.reply(ctx.get('account', PLATFORM_ACCOUNT_ID) ?? platformAccountDefault());
+
+/** A new Express account owes what its hosted onboarding will ask for (screens/onboarding.tsx; the US sets
+ *  docs.stripe.com/connect/required-verification-information lists), or, where the twin does not model the set, the
+ *  generic list. */
+function expressRequirements(params: Row): Row {
+  const kind = kindOf({ country: params.country ?? 'US', business_type: params.business_type ?? 'individual' });
+  const base = accountRequirements();
+  return kind ? { ...base, currently_due: currentlyDue(kind), eventually_due: currentlyDue(kind) } : base;
+}
+
+// the requested capabilities become Stripe's status map, and settings its canonical shape
+const create: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const type = typeof params.type === 'string' ? params.type : 'standard';
+  if (!ACCOUNT_TYPES.has(type)) return fail(ctx, 'Invalid account type: must be one of express, standard, or custom.', 400, 'parameter_invalid_string_enum');
+  const { capabilities: _caps, settings: _settings, ...accountParams } = keptKyc(params);
+  const id = ctx.mint('account');
+  const made = await created(ctx, 'account', { ...accountParams, id, type }, {
+    business_type: null, charges_enabled: false, payouts_enabled: false, details_submitted: false,
+    capabilities: accountCapabilities(params), requirements: type === 'express' ? expressRequirements(params) : accountRequirements(),
+    country: typeof params.country === 'string' ? params.country : 'US',
+    default_currency: 'usd', email: params.email ?? null, metadata: {}, livemode: false,
+    settings: accountSettings(params.settings), business_profile: {},
+    controller: controllerOf(type), external_accounts: externalList(id, []),
+    future_requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+    tos_acceptance: { date: null, ip: null, user_agent: null },
+  });
+  await review(ctx, String(made.id));
+  return ctx.reply(ctx.get('account', String(made.id))!);
+};
+
+/** The controller an account made with a `type` has: "Each of the three account types maps to values in the
+ *  `controller` hash", Standard to losses.payments `stripe`, fees.payer `account`, requirement_collection `stripe` and
+ *  a `full` dashboard, Express to `application`, `application_express`, `stripe` and `express`, Custom to
+ *  `application`, `application_custom`, `application` and `none`; each "type": "application", "is_controller": true
+ *  (docs.stripe.com/connect/migrate-to-controller-properties). */
+function controllerOf(type: string): Row {
+  const [losses, payer, collection, dashboard] = type === 'express' ? ['application', 'application_express', 'stripe', 'express']
+    : type === 'custom' ? ['application', 'application_custom', 'application', 'none'] : ['stripe', 'account', 'stripe', 'full'];
+  return { type: 'application', is_controller: true, losses: { payments: losses }, fees: { payer }, requirement_collection: collection, stripe_dashboard: { type: dashboard } };
+}
+
+// connected accounts only: the platform's own is not one
+const listAccounts: Semantics = async (ctx) => list(ctx, 'account', newest(ctx, 'account').filter((a) => a.id !== PLATFORM_ACCOUNT_ID));
+
+/** What a Custom account still owes, from what the platform has given for it, as Stripe's requirements endpoint lists it
+ *  for a US account with no Stripe Dashboard and the full service agreement
+ *  (docs.stripe.com/_endpoint/get-requirements-for-setups, the data behind
+ *  docs.stripe.com/connect/required-verification-information). With transfers alone, a company owes business_profile.url,
+ *  company.name, an external account and tos_acceptance.date and .ip at once (capability_limit_amount -1: paused until
+ *  given) and company.tax_id before $3,000 of payouts (payout_limit_amount 300000); an individual owes the url, its
+ *  first and last name, the bank account and the terms at once, and its date of birth and ssn_last_4 before $3,000 of
+ *  payouts. Requesting card_payments adds business_profile.mcc and the entity's address at once (and an individual's
+ *  email and ssn_last_4). A company with card_payments owes, at once, business_profile.mcc, its address, that its owners
+ *  are provided, each owner's name and email, and its representative's name, email, address, title and ssn_last_4; and
+ *  in time its phone, its statement descriptor and its representative's date of birth and phone (the endpoint's answer
+ *  for US / dashboard none / full terms / company / card_payments and transfers, saved in scratch as
+ *  req-custom-company-cards-transfers.json: capability_limit_amount -1 for the first, none for the second). The
+ *  representative and the owners are the account's persons (relationship.representative, relationship.owner).
+ *  Where the documentation stops and the twin decides: what has no limit, or is owed before $3,000 of payouts, is
+ *  eventually_due and blocks nothing (the twin keeps no payout total against it); an owner field is met when every
+ *  person marked owner has it (none marked: met). */
+const at_path = (a: Row, path: string): unknown => path.split('.').reduce<unknown>((v, k) => (v && typeof v === 'object' ? (v as Row)[k] : undefined), a);
+const CARD_COMPANY_NOW = ['business_profile.mcc', 'company.address.line1', 'company.address.city', 'company.address.state', 'company.address.postal_code', 'company.owners_provided', 'owners.first_name', 'owners.last_name', 'owners.email', 'representative.first_name', 'representative.last_name', 'representative.email', 'representative.address.line1', 'representative.address.city', 'representative.address.state', 'representative.address.postal_code', 'representative.relationship.title', 'representative.ssn_last_4'];
+const CARD_COMPANY_LATER = ['company.phone', 'settings.payments.statement_descriptor', 'representative.dob.day', 'representative.dob.month', 'representative.dob.year', 'representative.phone'];
+const CARD_INDIVIDUAL_NOW = ['business_profile.mcc', 'individual.address.line1', 'individual.address.city', 'individual.address.state', 'individual.address.postal_code', 'individual.email', 'individual.ssn_last_4'];
+/** A field only card_payments asks for (the transfers capability's requirements leave it out). */
+const cardOnly = (field: string): boolean => [...CARD_COMPANY_NOW, ...CARD_COMPANY_LATER, ...CARD_INDIVIDUAL_NOW].includes(field);
+const personHas = (p: Row, field: string): boolean => {
+  if (field === 'ssn_last_4') return p.ssn_last_4_provided === true;
+  const v = at_path(p, field);
+  return v !== undefined && v !== null && v !== '';
+};
+const met = (a: Row, bank: boolean, field: string, persons: Row[] = []): boolean => {
+  if (field === 'external_account') return bank;
+  if (field.startsWith('representative.')) {
+    const rep = persons.find((p) => (p.relationship as Row | undefined)?.representative === true);
+    return !!rep && personHas(rep, field.slice('representative.'.length));
+  }
+  if (field.startsWith('owners.')) return persons.filter((p) => (p.relationship as Row | undefined)?.owner === true).every((p) => personHas(p, field.slice('owners.'.length)));
+  if (field === 'company.tax_id') return at_path(a, 'company.tax_id_provided') === true;
+  if (field === 'individual.ssn_last_4') return at_path(a, 'individual.ssn_last_4_provided') === true;
+  const v = at_path(a, field);
+  return v !== undefined && v !== null && v !== '';
+};
+function customRequirements(a: Row, bank: boolean, persons: Row[] = []): { now: string[]; later: string[] } {
+  const company = a.business_type === 'company';
+  const cards = Object.keys((a.capabilities as Row | undefined) ?? {}).includes('card_payments');
+  const now = ['business_profile.url', ...(company ? ['company.name'] : ['individual.first_name', 'individual.last_name']), 'external_account', 'tos_acceptance.date', 'tos_acceptance.ip'];
+  if (cards) now.push(...(company ? CARD_COMPANY_NOW : CARD_INDIVIDUAL_NOW));
+  const later = [...(company ? ['company.tax_id'] : ['individual.dob.day', 'individual.dob.month', 'individual.dob.year', 'individual.ssn_last_4']), ...(cards && company ? CARD_COMPANY_LATER : [])].filter((f) => !now.includes(f));
+  return { now: now.filter((f) => !met(a, bank, f, persons)), later: later.filter((f) => !met(a, bank, f, persons)) };
+}
+
+/** A request's company or individual as Stripe keeps it: a tax id or SSN given is kept only as provided (the Account
+ *  object answers company.tax_id_provided and individual.ssn_last_4_provided, never the numbers;
+ *  docs.stripe.com/api/accounts/object). */
+function keptKyc(params: Row): Row {
+  const out: Row = { ...params };
+  if (params.company && typeof params.company === 'object') {
+    const { tax_id, ...company } = params.company as Row;
+    out.company = { ...company, ...(tax_id !== undefined && tax_id !== '' ? { tax_id_provided: true } : {}) };
+  }
+  if (params.individual && typeof params.individual === 'object') {
+    const { ssn_last_4, id_number, ...individual } = params.individual as Row;
+    out.individual = { ...individual, ...(ssn_last_4 !== undefined && ssn_last_4 !== '' ? { ssn_last_4_provided: true } : {}), ...(id_number !== undefined && id_number !== '' ? { id_number_provided: true } : {}) };
+  }
+  return out;
+}
+
+/** Stripe's review of a Custom account once the platform gives it something: with nothing left due, its requested
+ *  capabilities become active and it can take charges and receive payouts; with something due again (its bank account
+ *  removed), they stop. Where the documentation stops and the twin decides: test-mode verification is immediate, and
+ *  it owes what customRequirements lists. An Express or Standard account is onboarded on Stripe's own pages. */
+async function review(ctx: SemanticsContext, id: string): Promise<void> {
+  const account = ctx.get('account', id);
+  if (account && account.type === 'custom') await reviewCustom(ctx, id, account);
+}
+
+/** The review of a Custom account (see review). */
+async function reviewCustom(ctx: SemanticsContext, id: string, account: Row): Promise<void> {
+  const bank = ctx.rows('external_account').some((e) => e.account === id);
+  const persons = ctx.rows('person').filter((p) => p.account === id);
+  const { now: due, later } = customRequirements(account, bank, persons);
+  // one account, one review: "If a connected account has both card_payments and transfers, and the status of either one
+  // is inactive, then both capabilities are disabled" (docs.stripe.com/connect/account-capabilities)
+  const ready = due.length === 0;
+  const capabilities: Row = {};
+  for (const [key, was] of Object.entries((account.capabilities as Row | undefined) ?? {})) {
+    const to = ready ? 'active' : 'inactive';
+    // Stripe's review moves each capability, as the machine declares it may
+    if (was !== to) ctx.legal('capability', 'status', ctx.call.operation.id, String(was), to, key, 'vendor');
+    capabilities[key] = to;
+  }
+  const requirements = { ...((account.requirements as Row | undefined) ?? {}), currently_due: due, eventually_due: [...due, ...later], past_due: [], disabled_reason: ready ? null : 'requirements.past_due', current_deadline: null };
+  await ctx.write('account', id, { capabilities, requirements, charges_enabled: ready, payouts_enabled: ready, details_submitted: ready }, ready ? 'account.updated' : 'account.update');
+}
+
+// `type` cannot change; settings merge onto the existing ones
+const update: Semantics = async (ctx) => {
+  const id = at(ctx, 'account');
+  const ex = ctx.get('account', id);
+  if (!ex) return accountMissing(ctx, id);
+  const { type: _drop, settings: rawSettings, ...rest } = keptKyc(ctx.params);
+  if (rawSettings !== undefined) rest.settings = accountSettings(rawSettings, ex.settings as Row | undefined);
+  // a company or an individual given in part is laid over what the account holds
+  for (const k of ['company', 'individual', 'business_profile', 'tos_acceptance'] as const) if (rest[k] && typeof rest[k] === 'object' && ex[k] && typeof ex[k] === 'object') rest[k] = { ...(ex[k] as Row), ...(rest[k] as Row) };
+  await ctx.write('account', id, rest, 'account.update');
+  await review(ctx, id);
+  return ctx.reply(ctx.get('account', id)!);
+};
+
+// a single-use Express dashboard link, not stored
+const loginLink: Semantics = async (ctx) => {
+  const id = at(ctx, 'account');
+  if (!ctx.get('account', id)) return accountMissing(ctx, id);
+  return ctx.reply({ object: 'login_link', created: ctx.now(), url: `https://connect.twin.local/express/${id}` });
+};
+
+// ── persons on an account ──
+
+const personMissing = (ctx: SemanticsContext): Response => fail(ctx, `No such person: '${at(ctx, 'person')}'`, 404, 'resource_missing');
+const accountPerson = (ctx: SemanticsContext): Row | undefined => {
+  const p = ctx.get('person', at(ctx, 'person'));
+  return p && p.account === at(ctx, 'account') ? p : undefined;
+};
+
+/** A person's details as Stripe keeps them: an SSN or ID number given is kept only as provided (the Person object
+ *  answers ssn_last_4_provided and id_number_provided, never the numbers; docs.stripe.com/api/persons/object). */
+function keptPerson(params: Row, was: Row = {}): Row {
+  const { ssn_last_4, id_number, ...rest } = params;
+  const out: Row = { ...rest, ...(ssn_last_4 !== undefined && ssn_last_4 !== '' ? { ssn_last_4_provided: true } : {}), ...(id_number !== undefined && id_number !== '' ? { id_number_provided: true } : {}) };
+  // a relationship, address or date of birth given in part is laid over what the person holds
+  for (const k of ['relationship', 'address', 'dob'] as const) if (out[k] && typeof out[k] === 'object' && was[k] && typeof was[k] === 'object') out[k] = { ...(was[k] as Row), ...(out[k] as Row) };
+  return out;
+}
+const RELATIONSHIP: Row = { director: false, executive: false, owner: false, representative: false, percent_ownership: null, title: null };
+
+// a person given or changed is part of the account's review: its representative and owners are what card_payments asks for
+const createPerson: Semantics = async (ctx) => {
+  const account = at(ctx, 'account');
+  if (!accountRow(ctx, account)) return accountMissing(ctx, account);
+  const kept = keptPerson(ctx.params, { relationship: RELATIONSHIP });
+  const body = await created(ctx, 'person', { ...kept, account }, {
+    relationship: RELATIONSHIP,
+    requirements: { currently_due: [], eventually_due: [], past_due: [], pending_verification: [], errors: [], alternatives: [] },
+    verification: { status: 'unverified', document: { back: null, details: null, details_code: null, front: null } },
+    metadata: {}, ssn_last_4_provided: false, id_number_provided: false,
+  });
+  await review(ctx, account);
+  return ctx.reply(body);
+};
+
+const person: Semantics = async (ctx) => {
+  const p = accountPerson(ctx);
+  return p ? ctx.reply(p) : personMissing(ctx);
+};
+
+const updatePerson: Semantics = async (ctx) => {
+  const was = accountPerson(ctx);
+  if (!was) return personMissing(ctx);
+  const body = await ctx.write('person', at(ctx, 'person'), keptPerson(ctx.params, was), 'person.update');
+  await review(ctx, at(ctx, 'account'));
+  return ctx.reply(body);
+};
+
+const deletePerson: Semantics = async (ctx) => {
+  if (!accountPerson(ctx)) return personMissing(ctx);
+  const id = at(ctx, 'person');
+  await ctx.write('person', id, { deleted: true }, 'person.delete');
+  await review(ctx, at(ctx, 'account'));
+  return ctx.reply({ id, object: 'person', deleted: true });
+};
+
+// ── capabilities: the account's capability map is the truth; requesting one leaves it pending ──
+
+/** A capability as its account stands: its status, and the account's requirements that capability asks for (transfers
+ *  leaves out what only card_payments asks for). Where the documentation stops and the twin decides: the account-wide
+ *  fields (the bank account, the terms) belong to every capability. */
+const capabilityBody = (acct: Row, id: string, status: unknown, requested = true, requestedAt: unknown = null): Row => {
+  const req = (acct.requirements as Row | undefined) ?? {};
+  const mine = (list: unknown): string[] => (Array.isArray(list) ? (list as string[]) : []).filter((f) => id === 'card_payments' || !cardOnly(f));
+  const due = mine(req.currently_due);
+  return {
+    id, object: 'capability', account: acct.id, status, requested, requested_at: requestedAt,
+    requirements: { currently_due: due, eventually_due: mine(req.eventually_due), past_due: [], pending_verification: [], errors: [], alternatives: [], current_deadline: null, disabled_reason: due.length ? 'requirements.past_due' : null },
+  };
+};
+
+const capabilities: Semantics = async (ctx) => {
+  const account = at(ctx, 'account');
+  const acct = ctx.get('account', account);
+  if (!acct) return accountMissing(ctx, account);
+  const caps = (acct.capabilities as Row) ?? {};
+  return ctx.reply({ object: 'list', url: path(ctx), has_more: false, data: Object.entries(caps).map(([id, status]) => capabilityBody(acct, id, status)) });
+};
+
+const capability: Semantics = async (ctx) => {
+  const account = at(ctx, 'account');
+  const acct = ctx.get('account', account);
+  if (!acct) return accountMissing(ctx, account);
+  const caps = (acct.capabilities as Row) ?? {};
+  const cap = at(ctx, 'capability');
+  return cap in caps ? ctx.reply(capabilityBody(acct, cap, caps[cap])) : fail(ctx, `No such capability: '${cap}'`, 404, 'resource_missing');
+};
+
+const requestCapability: Semantics = async (ctx) => {
+  const account = at(ctx, 'account');
+  const acct = ctx.get('account', account);
+  if (!acct) return accountMissing(ctx, account);
+  const caps = { ...((acct.capabilities as Row) ?? {}) };
+  const cap = at(ctx, 'capability');
+  const requested = ctx.params.requested === undefined ? true : asBool(ctx.params.requested);
+  const to = requested ? 'pending' : 'inactive';
+  const refused = ctx.legal('capability', 'status', 'PostAccountsAccountCapabilitiesCapability', String(caps[cap] ?? 'unrequested'), to, cap);
+  if (refused) return ctx.refuse(refused);
+  caps[cap] = to;
+  await ctx.write('account', account, { capabilities: caps }, 'account.updated');
+  // Stripe reviews the account against what the capability asks for (review)
+  await review(ctx, account);
+  const now = ctx.get('account', account)!;
+  return ctx.reply(capabilityBody(now, cap, (now.capabilities as Row)[cap], requested, requested ? ctx.now() : null));
+};
+
+// ── external accounts: a payout destination from a token or a bank_account hash ──
+
+const externalMissing = (ctx: SemanticsContext): Response => fail(ctx, `No such external account: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+const accountExternal = (ctx: SemanticsContext): Row | undefined => {
+  const e = ctx.get('external_account', at(ctx, 'id'));
+  return e && e.account === at(ctx, 'account') ? e : undefined;
+};
+
+/** Whether the platform may create, update or delete an account's external accounts: "A platform can create, update, or
+ *  delete external accounts only for connected accounts without access to either the full Stripe or Express Dashboard
+ *  and where the platform is responsible for negative balances" (docs.stripe.com/connect/payouts-bank-accounts); it can
+ *  still view an Express account's ("A platform can view the external accounts of connected accounts that don’t have
+ *  access to the full Stripe Dashboard"). Where the documentation stops and the twin decides: the refusal. Stripe's
+ *  pages give no error code for it; the twin answers 403, which the errors page gives as "The API key doesn’t have
+ *  permissions to perform the request" (docs.stripe.com/api/errors), with the twin's own wording. The create page says
+ *  it too: "You can only specify connected accounts where account.controller.requirement_collection is `application`"
+ *  (docs.stripe.com/api/external_account_bank_accounts/create). */
+function refuseExternalWrite(ctx: SemanticsContext, account: string): Response | undefined {
+  const row = accountRow(ctx, account);
+  const controller = (row?.controller as Row | undefined) ?? controllerOf(String(row?.type ?? 'standard'));
+  const dashboard = String(((controller.stripe_dashboard as Row | undefined)?.type) ?? '');
+  const losses = String(((controller.losses as Row | undefined)?.payments) ?? '');
+  if (dashboard === 'none' && losses === 'application') return undefined;
+  return ctx.refuse({ status: 403, message: `This application does not have the required permissions to manage the external accounts of account '${account}': they can only be managed through the account's ${dashboard === 'express' ? 'Express' : 'Stripe'} Dashboard.` });
+}
+
+const createExternal: Semantics = async (ctx) => {
+  const account = at(ctx, 'account');
+  if (!accountRow(ctx, account)) return accountMissing(ctx, account);
+  const forbidden = refuseExternalWrite(ctx, account);
+  if (forbidden) return forbidden;
+  const ext = ctx.params.external_account ?? ctx.params.bank_account;
+  if (ext === undefined) return fail(ctx, 'Missing required param: external_account.', 400, 'parameter_missing');
+  const ba = typeof ext === 'object' ? (ext as Row) : {};
+  const acctNum = typeof ba.account_number === 'string' ? ba.account_number.replace(/\D/g, '') : '';
+  const currency = String(ba.currency ?? 'usd');
+  const sameCurrency = ctx.rows('external_account').filter((e) => e.account === account && String(e.currency ?? 'usd') === currency);
+  const isDefault = sameCurrency.length === 0 || ctx.params.default_for_currency === true || ctx.params.default_for_currency === 'true';
+  const made = await created(ctx, 'external_account', { account }, {
+    account_holder_name: ba.account_holder_name ?? null,
+    account_holder_type: ba.account_holder_type ?? null, bank_name: 'STRIPE TEST BANK',
+    country: ba.country ?? 'US', currency,
+    fingerprint: 'twin_ext_fp', last4: acctNum ? acctNum.slice(-4) : '6789',
+    routing_number: ba.routing_number ?? '110000000', status: 'new', metadata: {},
+    // "When set to true, or if this is the first external account added in this currency, this account becomes the
+    // default external account for its currency" (docs.stripe.com/api/external_account_bank_accounts/create)
+    default_for_currency: isDefault,
+    ...(ctx.params.metadata && typeof ctx.params.metadata === 'object' ? { metadata: ctx.params.metadata } : {}),
+  });
+  if (isDefault) for (const other of sameCurrency) if (other.default_for_currency === true) await ctx.write('external_account', String(other.id), { default_for_currency: false }, 'external_account.update');
+  await syncExternals(ctx, account);
+  await review(ctx, account);
+  return ctx.reply(made);
+};
+
+const externals: Semantics = async (ctx) => {
+  const account = at(ctx, 'account');
+  if (!accountRow(ctx, account)) return accountMissing(ctx, account);
+  return list(ctx, 'external_account', newest(ctx, 'external_account').filter((e) => e.account === account));
+};
+
+const external: Semantics = async (ctx) => {
+  const e = accountExternal(ctx);
+  return e ? ctx.reply(e) : externalMissing(ctx);
+};
+
+const deleteExternal: Semantics = async (ctx) => {
+  if (!accountExternal(ctx)) return externalMissing(ctx);
+  const forbidden = refuseExternalWrite(ctx, at(ctx, 'account'));
+  if (forbidden) return forbidden;
+  const id = at(ctx, 'id');
+  await ctx.write('external_account', id, { deleted: true }, 'external_account.delete');
+  await syncExternals(ctx, at(ctx, 'account'));
+  await review(ctx, at(ctx, 'account'));
+  return ctx.reply({ id, object: 'bank_account', deleted: true });
+};
+
+// ── hosted onboarding links and embedded-component sessions ──
+
+const accountLink: Semantics = async (ctx) => {
+  const account = typeof ctx.params.account === 'string' ? ctx.params.account : '';
+  if (!account) return fail(ctx, 'Missing required param: account.', 400, 'parameter_missing');
+  if (!ctx.get('account', account)) return accountMissing(ctx, account, 400);
+  const linkType = typeof ctx.params.type === 'string' ? ctx.params.type : '';
+  if (linkType !== 'account_onboarding' && linkType !== 'account_update') return fail(ctx, 'Invalid account link type: must be account_onboarding or account_update.', 400, 'parameter_invalid_string_enum');
+  // the owner is sent back to return_url when done, and to refresh_url for a new link once this one is used or expired
+  for (const k of ['refresh_url', 'return_url']) if (typeof ctx.params[k] !== 'string' || !ctx.params[k]) return fail(ctx, `Missing required param: ${k}.`, 400, 'parameter_missing');
+  const now = Number(ctx.now());
+  const id = ctx.mint('account_link');
+  const link = { object: 'account_link', created: now, expires_at: now + 300, url: `https://connect.stripe.com/setup/${id}` };
+  await ctx.write('account_link', id, { ...link, account, type: linkType, refresh_url: ctx.params.refresh_url, return_url: ctx.params.return_url, used: false }, 'account_link.create');
+  return ctx.reply(link);
+};
+
+// a session is identified by its client_secret: the row is kept for traceability, the answer has no id
+/** Every embedded component an account session answers (the served spec requires all of them), each enabled only when
+ *  the request enables it, with its features: what the request gives, else the spec's stated default, "The default
+ *  value for this feature is `true`" (external_account_collection); disable_stripe_user_authentication "the opposite of
+ *  the `external_account_collection` value"; edit_payout_schedule and standard_payouts "Defaults to `true` when
+ *  `controller.losses.payments` is set to `stripe` for the account, otherwise `false`"; capture_payments, dispute_management
+ *  and refund_management "true by default"; destination_on_behalf_of_charge_management "false by default";
+ *  smart_disputes_management "Defaults to the value of `dispute_management`". Where the documentation stops and the twin
+ *  decides: instant_payouts (described as `enabled` "when Stripe is responsible for negative account balances", typed
+ *  boolean) is true exactly then, and the Issuing and financial-account features, which state no default, are false. */
+const SESSION_COMPONENTS: Record<string, string[]> = {
+  account_management: ['external_account_collection', 'disable_stripe_user_authentication'],
+  account_onboarding: ['external_account_collection', 'disable_stripe_user_authentication'],
+  balance_report: [], documents: [], payout_details: [], payout_reconciliation_report: [], payouts_list: [], tax_registrations: [], tax_settings: [],
+  balances: ['external_account_collection', 'disable_stripe_user_authentication', 'edit_payout_schedule', 'instant_payouts', 'standard_payouts'],
+  payouts: ['external_account_collection', 'disable_stripe_user_authentication', 'edit_payout_schedule', 'instant_payouts', 'standard_payouts'],
+  disputes_list: ['capture_payments', 'destination_on_behalf_of_charge_management', 'dispute_management', 'refund_management', 'smart_disputes_management'],
+  payment_details: ['capture_payments', 'destination_on_behalf_of_charge_management', 'dispute_management', 'refund_management', 'smart_disputes_management'],
+  payments: ['capture_payments', 'destination_on_behalf_of_charge_management', 'dispute_management', 'refund_management', 'smart_disputes_management'],
+  payment_disputes: ['destination_on_behalf_of_charge_management', 'dispute_management', 'refund_management', 'smart_disputes_management'],
+  financial_account: ['external_account_collection', 'disable_stripe_user_authentication', 'send_money', 'transfer_balance'],
+  financial_account_transactions: ['card_spend_dispute_management'],
+  instant_payouts_promotion: ['external_account_collection', 'disable_stripe_user_authentication', 'instant_payouts'],
+  issuing_card: ['card_management', 'card_spend_dispute_management', 'cardholder_management', 'spend_control_management'],
+  issuing_cards_list: ['card_management', 'card_spend_dispute_management', 'cardholder_management', 'disable_stripe_user_authentication', 'spend_control_management'],
+  notification_banner: ['external_account_collection', 'disable_stripe_user_authentication'],
+  payment_method_settings: ['disable_stripe_user_authentication'],
+};
+function sessionComponents(account: Row, given: Row): Row {
+  const stripeLosses = (((account.controller as Row | undefined)?.losses as Row | undefined)?.payments) === 'stripe';
+  const out: Row = {};
+  for (const [name, featureNames] of Object.entries(SESSION_COMPONENTS)) {
+    const c = given[name] && typeof given[name] === 'object' ? (given[name] as Row) : {};
+    const asked = c.features && typeof c.features === 'object' ? (c.features as Row) : {};
+    const f: Row = {};
+    const val = (k: string, fallback: boolean): boolean => (asked[k] !== undefined ? asBool(asked[k]) : fallback);
+    for (const k of featureNames) {
+      if (k === 'external_account_collection') f[k] = val(k, true);
+      else if (k === 'disable_stripe_user_authentication') f[k] = val(k, !val('external_account_collection', true));
+      else if (k === 'edit_payout_schedule' || k === 'standard_payouts' || k === 'instant_payouts') f[k] = val(k, stripeLosses);
+      else if (k === 'capture_payments' || k === 'dispute_management' || k === 'refund_management') f[k] = val(k, true);
+      else if (k === 'smart_disputes_management') f[k] = val(k, val('dispute_management', true));
+      else f[k] = val(k, false);
+    }
+    out[name] = { enabled: c.enabled !== undefined ? asBool(c.enabled) : false, features: f };
+  }
+  return out;
+}
+
+const accountSession: Semantics = async (ctx) => {
+  const account = typeof ctx.params.account === 'string' ? ctx.params.account : '';
+  if (!account) return fail(ctx, 'Missing required param: account.', 400, 'parameter_missing');
+  if (!ctx.get('account', account)) return accountMissing(ctx, account, 400);
+  const comps = ctx.params.components && typeof ctx.params.components === 'object' ? (ctx.params.components as Row) : undefined;
+  if (!comps || Object.keys(comps).length === 0) return fail(ctx, 'Missing required param: components.', 400, 'parameter_missing');
+  const components = sessionComponents(ctx.get('account', account)!, comps);
+  const now = Number(ctx.now());
+  const seq = ctx.rowsRaw('account_session', { withDeleted: true }).length + 1;
+  const secret = `_twin_acct_sess_${seq}_secret`;
+  await created(ctx, 'account_session', { id: `accts_twin_${seq}`, account }, { livemode: false, client_secret: secret, expires_at: now + 3600, components });
+  return ctx.reply({ object: 'account_session', account, client_secret: secret, expires_at: now + 3600, components, livemode: false });
+};
+
+export const connect: Record<string, Semantics> = {
+  GetAccount: platform,
+  PostAccounts: create,
+  GetAccounts: listAccounts,
+  PostAccountsAccount: update,
+  PostAccountsAccountLoginLinks: loginLink,
+  PostAccountsAccountPersons: createPerson,
+  GetAccountsAccountPersonsPerson: person,
+  PostAccountsAccountPersonsPerson: updatePerson,
+  DeleteAccountsAccountPersonsPerson: deletePerson,
+  GetAccountsAccountCapabilities: capabilities,
+  GetAccountsAccountCapabilitiesCapability: capability,
+  PostAccountsAccountCapabilitiesCapability: requestCapability,
+  PostAccountsAccountExternalAccounts: createExternal,
+  GetAccountsAccountExternalAccounts: externals,
+  GetAccountsAccountExternalAccountsId: external,
+  DeleteAccountsAccountExternalAccountsId: deleteExternal,
+  PostAccountLinks: accountLink,
+  PostAccountSessions: accountSession,
+};

package/src/semantics/coupons.ts

@@ -0,0 +1,97 @@
+// Coupon and PromotionCode semantics. A coupon is exactly one of percent_off or amount_off (with
+// its currency) over a duration; a promotion code is a customer-facing code for an existing
+// coupon, active until switched off (the machine in ../manifest.ts). Coupon list, retrieve, update
+// and delete and promotion-code retrieve and update (`active`, the machine) are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { asBool } from '../stripe-twin.ts';
+import { at, at_, created, fail, list, newest, where, type Row } from './shared.ts';
+
+/** A coupon for a fixed amount off, in its currency (docs.stripe.com/api/coupons/create#create_coupon-amount_off). */
+function amountOffOf(ctx: SemanticsContext, params: Record<string, unknown>): number | Response {
+  const amountOff = Number(params.amount_off);
+  if (!Number.isInteger(amountOff) || amountOff <= 0) return fail(ctx, 'Invalid integer: amount_off must be a positive integer.', 400, 'parameter_invalid_integer');
+  if (params.currency === undefined || params.currency === '') return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
+  return amountOff;
+}
+
+const createCoupon: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const hasPct = params.percent_off !== undefined;
+  const hasAmt = params.amount_off !== undefined;
+  if (hasPct === hasAmt) return fail(ctx, 'You must pass exactly one of `amount_off` and `percent_off`.', 400, 'parameter_missing');
+  let percentOff: number | null = null;
+  let amountOff: number | null = null;
+  if (hasPct) {
+    percentOff = Number(params.percent_off);
+    if (!Number.isFinite(percentOff) || percentOff <= 0 || percentOff > 100) return fail(ctx, 'Invalid number: percent_off must be > 0 and <= 100.', 400, 'parameter_invalid_number');
+  }
+  const off = hasPct ? null : amountOffOf(ctx, params);
+  if (off instanceof Response) return off;
+  amountOff = off;
+  const duration = typeof params.duration === 'string' ? params.duration : 'once';
+  if (!['once', 'repeating', 'forever'].includes(duration)) return fail(ctx, 'Invalid duration: must be one of once, repeating, or forever.', 400, 'parameter_invalid_string_enum');
+  if (duration === 'repeating' && params.duration_in_months === undefined) return fail(ctx, 'Missing required param: duration_in_months (required when duration=repeating).', 400, 'parameter_missing');
+  return ctx.reply(
+    await created(ctx, 'coupon', params, {
+      percent_off: percentOff, amount_off: amountOff,
+      currency: amountOff !== null ? params.currency : null,
+      duration, duration_in_months: duration === 'repeating' ? Number(params.duration_in_months) : null,
+      name: typeof params.name === 'string' ? params.name : null,
+      valid: true, livemode: false, times_redeemed: 0, metadata: {},
+      max_redemptions: params.max_redemptions !== undefined ? Number(params.max_redemptions) : null,
+      redeem_by: params.redeem_by !== undefined ? Number(params.redeem_by) : null,
+      applies_to: null,
+    }),
+  );
+};
+
+// a code the caller does not give is derived from the promotion code's id
+const createPromotionCode: Semantics = async (ctx) => {
+  // what it promotes: promotion[type]=coupon and promotion[coupon] (2025-09-30.clover,
+  // docs.stripe.com/changelog/clover/2025-09-30/polymorphic-coupon), or the top-level coupon a caller pinned to an
+  // earlier version sends; the twin keeps the coupon's id on the code for its rules
+  const { promotion, coupon: legacy, ...params } = ctx.params;
+  const promo = promotion && typeof promotion === 'object' ? (promotion as Record<string, unknown>) : undefined;
+  if (promo && promo.type !== 'coupon') return fail(ctx, 'Invalid promotion[type]: must be coupon.', 400, 'parameter_invalid_string_enum');
+  const coupon = typeof promo?.coupon === 'string' ? promo.coupon : typeof legacy === 'string' ? legacy : '';
+  if (!coupon) return fail(ctx, promo ? 'Missing required param: promotion[coupon].' : 'Missing required param: promotion.', 400, 'parameter_missing');
+  if (!ctx.get('coupon', coupon)) return fail(ctx, `No such coupon: '${coupon}'`, 400, 'resource_missing');
+  const id = ctx.mint('promotion_code');
+  const code = typeof params.code === 'string' && params.code ? params.code : `TWIN${id.toUpperCase().replace(/[^A-Z0-9]/g, '')}`;
+  return ctx.reply(
+    await created(ctx, 'promotion_code', { ...params, coupon, promotion: { type: 'coupon', coupon }, id, code }, {
+      active: params.active !== undefined ? asBool(params.active) : true,
+      customer: typeof params.customer === 'string' ? params.customer : null,
+      expires_at: params.expires_at !== undefined ? Number(params.expires_at) : null,
+      max_redemptions: params.max_redemptions !== undefined ? Number(params.max_redemptions) : null,
+      times_redeemed: 0, livemode: false, metadata: {}, restrictions: { first_time_transaction: false, minimum_amount: null, minimum_amount_currency: null },
+    }),
+  );
+};
+
+/** Time's lapsing of coupons, caught up to the World's clock: a valid coupon whose redeem_by has passed is no longer
+ *  valid from that moment (manifest.ts). Where the documentation stops and the twin decides: the lapse sends no event
+ *  (the events page names none for it). */
+export async function lapseCoupons(ctx: SemanticsContext): Promise<void> {
+  const now = Number(ctx.now());
+  for (const c of ctx.rowsRaw('coupon')) {
+    if (c.valid !== true || typeof c.redeem_by !== 'number' || c.redeem_by > now) continue;
+    const t = await at_(ctx)(c.redeem_by);
+    t.legal('coupon', 'valid', ctx.call.operation.id, 'true', 'false', String(c.id), 'time');
+    await t.write('coupon', String(c.id), { valid: false }, 'coupon.lapsed');
+  }
+}
+
+const listPromotionCodes: Semantics = async (ctx) =>
+  list(ctx, 'promotion_code', where(ctx, newest(ctx, 'promotion_code'), {
+    code: (p, v) => p.code === v,
+    active: (p, v) => asBool(p.active) === asBool(v),
+    coupon: (p, v) => p.coupon === v,
+    customer: (p, v) => p.customer === v,
+  }));
+
+export const coupons: Record<string, Semantics> = {
+  PostCoupons: createCoupon,
+  PostPromotionCodes: createPromotionCode,
+  GetPromotionCodes: listPromotionCodes,
+};