@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/semantics/connect.js

@@ -0,0 +1,476 @@
+import { ACCOUNT_TYPES, accountCapabilities, accountRequirements, accountSettings, asBool, PLATFORM_ACCOUNT_ID } from "../stripe-twin.js";
+import { currentlyDue, kindOf } from "../screens/onboarding.js";
+import { at, created, externalList, fail, list, newest, path, syncExternals } from "./shared.js";
+const accountMissing = (ctx, id, status = 404) => 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, id) => 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 = () => ({
+    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 = 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) {
+    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 = 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) {
+    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 = 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, path) => path.split('.').reduce((v, k) => (v && typeof v === 'object' ? v[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) => [...CARD_COMPANY_NOW, ...CARD_COMPANY_LATER, ...CARD_INDIVIDUAL_NOW].includes(field);
+const personHas = (p, field) => {
+    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, bank, field, persons = []) => {
+    if (field === 'external_account')
+        return bank;
+    if (field.startsWith('representative.')) {
+        const rep = persons.find((p) => p.relationship?.representative === true);
+        return !!rep && personHas(rep, field.slice('representative.'.length));
+    }
+    if (field.startsWith('owners.'))
+        return persons.filter((p) => p.relationship?.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, bank, persons = []) {
+    const company = a.business_type === 'company';
+    const cards = Object.keys(a.capabilities ?? {}).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) {
+    const out = { ...params };
+    if (params.company && typeof params.company === 'object') {
+        const { tax_id, ...company } = params.company;
+        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;
+        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, id) {
+    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, id, account) {
+    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 = {};
+    for (const [key, was] of Object.entries(account.capabilities ?? {})) {
+        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 ?? {}), 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 = 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);
+    // 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'])
+        if (rest[k] && typeof rest[k] === 'object' && ex[k] && typeof ex[k] === 'object')
+            rest[k] = { ...ex[k], ...rest[k] };
+    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 = 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) => fail(ctx, `No such person: '${at(ctx, 'person')}'`, 404, 'resource_missing');
+const accountPerson = (ctx) => {
+    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, was = {}) {
+    const { ssn_last_4, id_number, ...rest } = params;
+    const out = { ...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'])
+        if (out[k] && typeof out[k] === 'object' && was[k] && typeof was[k] === 'object')
+            out[k] = { ...was[k], ...out[k] };
+    return out;
+}
+const RELATIONSHIP = { 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 = 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 = async (ctx) => {
+    const p = accountPerson(ctx);
+    return p ? ctx.reply(p) : personMissing(ctx);
+};
+const updatePerson = 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 = 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, id, status, requested = true, requestedAt = null) => {
+    const req = acct.requirements ?? {};
+    const mine = (list) => (Array.isArray(list) ? list : []).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 = async (ctx) => {
+    const account = at(ctx, 'account');
+    const acct = ctx.get('account', account);
+    if (!acct)
+        return accountMissing(ctx, account);
+    const caps = acct.capabilities ?? {};
+    return ctx.reply({ object: 'list', url: path(ctx), has_more: false, data: Object.entries(caps).map(([id, status]) => capabilityBody(acct, id, status)) });
+};
+const capability = async (ctx) => {
+    const account = at(ctx, 'account');
+    const acct = ctx.get('account', account);
+    if (!acct)
+        return accountMissing(ctx, account);
+    const caps = acct.capabilities ?? {};
+    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 = async (ctx) => {
+    const account = at(ctx, 'account');
+    const acct = ctx.get('account', account);
+    if (!acct)
+        return accountMissing(ctx, account);
+    const caps = { ...(acct.capabilities ?? {}) };
+    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[cap], requested, requested ? ctx.now() : null));
+};
+// ── external accounts: a payout destination from a token or a bank_account hash ──
+const externalMissing = (ctx) => fail(ctx, `No such external account: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+const accountExternal = (ctx) => {
+    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, account) {
+    const row = accountRow(ctx, account);
+    const controller = row?.controller ?? controllerOf(String(row?.type ?? 'standard'));
+    const dashboard = String((controller.stripe_dashboard?.type) ?? '');
+    const losses = String((controller.losses?.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 = 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 : {};
+    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 = 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 = async (ctx) => {
+    const e = accountExternal(ctx);
+    return e ? ctx.reply(e) : externalMissing(ctx);
+};
+const deleteExternal = 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 = 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 = {
+    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, given) {
+    const stripeLosses = (account.controller?.losses?.payments) === 'stripe';
+    const out = {};
+    for (const [name, featureNames] of Object.entries(SESSION_COMPONENTS)) {
+        const c = given[name] && typeof given[name] === 'object' ? given[name] : {};
+        const asked = c.features && typeof c.features === 'object' ? c.features : {};
+        const f = {};
+        const val = (k, fallback) => (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 = 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 : 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 = {
+    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/dist/src/semantics/coupons.d.ts

@@ -0,0 +1,6 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+/** 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 declare function lapseCoupons(ctx: SemanticsContext): Promise<void>;
+export declare const coupons: Record<string, Semantics>;

package/dist/src/semantics/coupons.js

@@ -0,0 +1,92 @@
+import { asBool } from "../stripe-twin.js";
+import { at_, created, fail, list, newest, where } from "./shared.js";
+/** A coupon for a fixed amount off, in its currency (docs.stripe.com/api/coupons/create#create_coupon-amount_off). */
+function amountOffOf(ctx, params) {
+    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 = 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 = null;
+    let amountOff = 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 = 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 : 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) {
+    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 = 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 = {
+    PostCoupons: createCoupon,
+    PostPromotionCodes: createPromotionCode,
+    GetPromotionCodes: listPromotionCodes,
+};

package/dist/src/semantics/credit-notes.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const creditNotes: Record<string, Semantics>;