@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/engine/common.js

@@ -0,0 +1,32 @@
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+/** A removed discount as Stripe answers it: the discount, marked deleted (docs.stripe.com/api/discounts/delete). */
+export function deletedDiscount(d, now) {
+    const coupon = d.coupon && typeof d.coupon === 'object' ? String(d.coupon.id) : typeof d.coupon === 'string' ? d.coupon : null;
+    return {
+        id: d.id ?? `di_${coupon ?? 'twin'}`, object: 'discount', deleted: true, checkout_session: d.checkout_session ?? null, customer: d.customer ?? null,
+        invoice: d.invoice ?? null, invoice_item: d.invoice_item ?? null, promotion_code: d.promotion_code ?? null, subscription: d.subscription ?? null,
+        subscription_item: d.subscription_item ?? null, source: d.source ?? { type: 'coupon', coupon }, start: d.start ?? now,
+    };
+}
+/** Keep the rows whose field equals the request's parameter of the same name, for each name given. */
+/** A list's range filter on a unix time (`created[gte]=…&created[lt]=…`, or one exact time). */
+export function inRange(t, v) {
+    const at = Number(t);
+    const r = (v && typeof v === 'object' ? v : { gte: v, lte: v });
+    return (r.gt === undefined || at > Number(r.gt)) && (r.gte === undefined || at >= Number(r.gte)) && (r.lt === undefined || at < Number(r.lt)) && (r.lte === undefined || at <= Number(r.lte));
+}
+export const SPEC_FIELDS = new Map(surface.resources.map((r) => [r.name, new Set(r.fields.map((f) => f.name))]));
+/** A refund's destination_details for a card charge: "If this is a `card` refund, this hash contains the transaction
+ *  specific details" and its `type` "can be `refund`, `reversal`, or `pending`" — a reversal, where "The original charge
+ *  will drop off the bank statement altogether", for an authorization released uncaptured, else a refund, "a credit entry
+ *  on the bank statement" (docs.stripe.com/api/refunds/object). The network's reference number the twin never has. A
+ *  charge not paid by card answers none. */
+export function refundDestination(charge, type) {
+    const pmd = charge.payment_method_details;
+    if (pmd && pmd.type !== 'card')
+        return {};
+    return { destination_details: { type: 'card', card: { reference: null, reference_status: null, reference_type: null, type } } };
+}
+/** An account's external_accounts, "External accounts (bank accounts and debit cards) currently attached to this
+ *  account" (docs.stripe.com/api/accounts/object), as the list its example answers. */
+export const externalList = (account, data) => ({ object: 'list', data, has_more: false, total_count: data.length, url: `/v1/accounts/${account}/external_accounts` });

package/dist/src/{screens → engine}/connect-settings.d.ts

@@ -1,22 +1,16 @@
-import { type SemanticsContext } from '@volter/world-core';
 /** The platform's test client_id: the World's one platform (acct_twin_self) is the application it names. */
 export declare const PLATFORM_CLIENT_ID = "ca_twin_self";
 export declare const SETTINGS_URL = "https://dashboard.stripe.com/settings/connect/onboarding-options/oauth";
 /** The page's addresses: the docs' own, its test-mode link, and Connect's settings root. */
 export declare const CONNECT_SETTINGS_PATH: RegExp;
+export declare const SETTINGS = "_connect_oauth_settings";
 export type ConnectOAuthSettings = {
     oauth_enabled: boolean;
     redirect_uris: string[];
 };
-/** What the platform saved, or the settings a new platform starts with (OAuth off, no redirect URI). */
-export declare function connectOAuthSettings(ctx: SemanticsContext): ConnectOAuthSettings;
 /** The redirect URIs a form's field names, or the first one refused and why. */
 export declare function redirectUris(field: string): {
     uris: string[];
 } | {
     refused: string;
 };
-export declare function stripeConnectSettingsFlow(scope: {
-    root?: string;
-    clock?: () => string;
-}): (request: Request) => Promise<Response | undefined>;

package/dist/src/engine/connect-settings.js

@@ -0,0 +1,26 @@
+// The platform's Connect OAuth settings (its client_id, whether OAuth is on, its redirect URIs), which the Dashboard's
+// settings page saves (../screens/dashboard.tsx) and connect.stripe.com/oauth/authorize reads (../screens/connect-oauth.tsx).
+/** The platform's test client_id: the World's one platform (acct_twin_self) is the application it names. */
+export const PLATFORM_CLIENT_ID = 'ca_twin_self';
+export const SETTINGS_URL = 'https://dashboard.stripe.com/settings/connect/onboarding-options/oauth';
+/** The page's addresses: the docs' own, its test-mode link, and Connect's settings root. */
+export const CONNECT_SETTINGS_PATH = /^\/(test\/)?settings\/connect(\/onboarding-options\/oauth)?\/?$/;
+export const SETTINGS = '_connect_oauth_settings';
+/** The redirect URIs a form's field names, or the first one refused and why. */
+export function redirectUris(field) {
+    const uris = [...new Set(field.split(/[\n,]/).map((s) => s.trim()).filter(Boolean))];
+    for (const uri of uris) {
+        let url;
+        try {
+            url = new URL(uri);
+        }
+        catch {
+            return { refused: `${uri} is not a valid URL.` };
+        }
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return { refused: `${uri} must use http or https.` };
+        if (uri.includes('#'))
+            return { refused: `${uri} must not contain a fragment.` };
+    }
+    return { uris };
+}

package/dist/src/engine/connect.d.ts

@@ -0,0 +1,66 @@
+import { type Row } from './common.js';
+export declare const PLATFORM_CREATED = 1767225600;
+/** The platform's own account as Stripe's default has it, before anything is written to it. */
+export declare const platformAccountDefault: () => Row;
+/** A new Express account owes what its hosted onboarding will ask for (screens/connect-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. */
+export declare function expressRequirements(params: Row): Row;
+/** 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). */
+export declare function controllerOf(type: string): Row;
+/** 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). */
+export declare const at_path: (a: Row, path: string) => unknown;
+export declare const CARD_COMPANY_NOW: string[];
+export declare const CARD_COMPANY_LATER: string[];
+export declare const CARD_INDIVIDUAL_NOW: string[];
+/** A field only card_payments asks for (the transfers capability's requirements leave it out). */
+export declare const cardOnly: (field: string) => boolean;
+export declare const personHas: (p: Row, field: string) => boolean;
+export declare const met: (a: Row, bank: boolean, field: string, persons?: Row[]) => boolean;
+export declare function customRequirements(a: Row, bank: boolean, persons?: Row[]): {
+    now: string[];
+    later: string[];
+};
+/** 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). */
+export declare function keptKyc(params: Row): Row;
+/** 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). */
+export declare function keptPerson(params: Row, was?: Row): Row;
+export declare const RELATIONSHIP: Row;
+/** 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. */
+export declare const capabilityBody: (acct: Row, id: string, status: unknown, requested?: boolean, requestedAt?: unknown) => Row;
+/** 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. */
+export declare const SESSION_COMPONENTS: Record<string, string[]>;
+export declare function sessionComponents(account: Row, given: Row): Row;

package/dist/src/engine/connect.js

@@ -0,0 +1,189 @@
+// 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 { accountRequirements, accountSettings, asBool, PLATFORM_ACCOUNT_ID } from "./stripe.js";
+import { currentlyDue, kindOf } from "./onboarding.js";
+import { externalList } from "./common.js";
+// 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.
+export 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,
+});
+/** A new Express account owes what its hosted onboarding will ask for (screens/connect-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. */
+export 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 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). */
+export 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 } };
+}
+/** 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). */
+export const at_path = (a, path) => path.split('.').reduce((v, k) => (v && typeof v === 'object' ? v[k] : undefined), a);
+export 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'];
+export const CARD_COMPANY_LATER = ['company.phone', 'settings.payments.statement_descriptor', 'representative.dob.day', 'representative.dob.month', 'representative.dob.year', 'representative.phone'];
+export 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). */
+export const cardOnly = (field) => [...CARD_COMPANY_NOW, ...CARD_COMPANY_LATER, ...CARD_INDIVIDUAL_NOW].includes(field);
+export 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 !== '';
+};
+export 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 !== '';
+};
+export 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). */
+export 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;
+}
+/** 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). */
+export 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;
+}
+export const RELATIONSHIP = { director: false, executive: false, owner: false, representative: false, percent_ownership: null, title: null };
+// ── 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. */
+export 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 },
+    };
+};
+// 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. */
+export 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'],
+};
+export 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;
+}

package/dist/src/engine/coupons.js

@@ -0,0 +1,5 @@
+"use strict";
+// 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.

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

@@ -0,0 +1 @@
+export declare const CN = "credit_note";

package/dist/src/engine/credit-notes.js

@@ -0,0 +1,5 @@
+// Credit note semantics. A credit note credits part of an invoice: pre_payment while the invoice
+// is unpaid (it lowers what is owed), post_payment once paid. The invoice carries the sums of its
+// issued credit notes, re-derived on every change so voiding one returns the invoice to where it
+// was. The machine in ../manifest.ts says a credit note is voided once. The list is the derived core's.
+export const CN = 'credit_note';

package/dist/src/engine/customers.d.ts

@@ -0,0 +1,12 @@
+import type { Row } from './common.js';
+/** What a new customer answers before any invoice: its invoice_prefix and a next_invoice_sequence of 1, a zero balance,
+ *  no metadata (docs.stripe.com/api/customers/object). */
+export declare const newCustomer: (id: string) => Row;
+export declare const EU_VAT: Record<string, RegExp>;
+export declare const euVatCountry: (value: string) => string | undefined;
+/** The tax ID types Stripe checks against a government register: "Stripe automatically validates all Australian
+ *  Business Numbers (ABNs)", "all European Value-Added-Tax (EU VAT) numbers" (VIES) and "all UK Value-Added-Tax (GB VAT)
+ *  numbers" (HMRC); a verification's status "is pending, verified, unverified, or unavailable", and "When automatic
+ *  validation is unavailable, you must manually verify the tax ID" (docs.stripe.com/billing/customer/tax-ids). Any other
+ *  type answers unavailable; one of these waits pending. */
+export declare const AUTO_VALIDATED: Set<string>;

package/dist/src/engine/customers.js

@@ -0,0 +1,30 @@
+// Customer semantics: the customer and what hangs off it (tax ids, the credit-balance ledger, the
+// cash balance, legacy sources, attached payment methods) and the top-level Source object. List,
+// update and delete of a customer, retrieve of a Source and the flat tax-id list are the derived core's.
+import { invoicePrefix } from "./invoices.js";
+/** What a new customer answers before any invoice: its invoice_prefix and a next_invoice_sequence of 1, a zero balance,
+ *  no metadata (docs.stripe.com/api/customers/object). */
+export const newCustomer = (id) => ({ invoice_prefix: invoicePrefix(id), next_invoice_sequence: 1, balance: 0, metadata: {}, invoice_settings: {} });
+// ── tax ids: a customer's, keyed under it; `type` and `value` are required ──
+// An EU VAT number is its country's prefix and that country's format (the European Commission's VIES formats,
+// ec.europa.eu/taxation_customs/vies); Stripe refuses one that does not fit as tax_id_invalid
+// (docs.stripe.com/error-codes#tax-id-invalid). The message's wording is the twin's.
+export const EU_VAT = {
+    AT: /^U\d{8}$/, BE: /^[01]\d{9}$/, BG: /^\d{9,10}$/, CY: /^\d{8}[A-Z]$/, CZ: /^\d{8,10}$/, DE: /^\d{9}$/, DK: /^\d{8}$/,
+    EE: /^\d{9}$/, EL: /^\d{9}$/, ES: /^[A-Z0-9]\d{7}[A-Z0-9]$/, FI: /^\d{8}$/, FR: /^[A-Z0-9]{2}\d{9}$/, HR: /^\d{11}$/,
+    HU: /^\d{8}$/, IE: /^(\d{7}[A-W][A-I]?|\d[A-Z+*]\d{5}[A-W])$/, IT: /^\d{11}$/, LT: /^(\d{9}|\d{12})$/, LU: /^\d{8}$/,
+    LV: /^\d{11}$/, MT: /^\d{8}$/, NL: /^\d{9}B\d{2}$/, PL: /^\d{10}$/, PT: /^\d{9}$/, RO: /^\d{2,10}$/, SE: /^\d{12}$/,
+    SI: /^\d{8}$/, SK: /^\d{10}$/, XI: /^(\d{9}|\d{12}|GD\d{3}|HA\d{3})$/,
+};
+export const euVatCountry = (value) => {
+    const v = value.replace(/[\s.-]/g, '').toUpperCase();
+    const prefix = v.slice(0, 2);
+    const format = EU_VAT[prefix];
+    return format && format.test(v.slice(2)) ? (prefix === 'EL' ? 'GR' : prefix) : undefined;
+};
+/** The tax ID types Stripe checks against a government register: "Stripe automatically validates all Australian
+ *  Business Numbers (ABNs)", "all European Value-Added-Tax (EU VAT) numbers" (VIES) and "all UK Value-Added-Tax (GB VAT)
+ *  numbers" (HMRC); a verification's status "is pending, verified, unverified, or unavailable", and "When automatic
+ *  validation is unavailable, you must manually verify the tax ID" (docs.stripe.com/billing/customer/tax-ids). Any other
+ *  type answers unavailable; one of these waits pending. */
+export const AUTO_VALIDATED = new Set(['au_abn', 'eu_vat', 'gb_vat']);

package/dist/src/engine/display.d.ts

@@ -0,0 +1,14 @@
+type Row = Record<string, any>;
+/** The name an account shows its customers (Checkout, the customer portal): its public business name,
+ *  `business_profile.name` ("The customer-facing business name", docs.stripe.com/api/accounts/object), which the
+ *  operator sets on the Dashboard ("You can change a Checkout page's name by modifying the Business name field",
+ *  docs.stripe.com/payments/checkout/customization/appearance). Where the documentation stops and the twin decides:
+ *  with none set it falls back to the Dashboard's account name, `settings.dashboard.display_name` ("used on the Stripe
+ *  Dashboard to differentiate between accounts", the same object page), and with neither to "Twin Inc.", the name the
+ *  twin has always given the World's own account. */
+export declare const PLATFORM_DEFAULT_NAME = "Twin Inc.";
+/** The bookkeeping type of a connected account's Connect OAuth connection (../screens/connect-oauth.tsx): one row per
+ *  account, `revoked: true` once deauthorized or its code reused. Read by the account list and the event path too. */
+export declare const OAUTH_CONNECTIONS = "_oauth_connection";
+export declare function publicBusinessName(account: Row | undefined): string;
+export {};

package/dist/src/engine/display.js

@@ -0,0 +1,16 @@
+// What Stripe's pages show of an account, and where its Connect OAuth connections are kept.
+/** The name an account shows its customers (Checkout, the customer portal): its public business name,
+ *  `business_profile.name` ("The customer-facing business name", docs.stripe.com/api/accounts/object), which the
+ *  operator sets on the Dashboard ("You can change a Checkout page's name by modifying the Business name field",
+ *  docs.stripe.com/payments/checkout/customization/appearance). Where the documentation stops and the twin decides:
+ *  with none set it falls back to the Dashboard's account name, `settings.dashboard.display_name` ("used on the Stripe
+ *  Dashboard to differentiate between accounts", the same object page), and with neither to "Twin Inc.", the name the
+ *  twin has always given the World's own account. */
+export const PLATFORM_DEFAULT_NAME = 'Twin Inc.';
+/** The bookkeeping type of a connected account's Connect OAuth connection (../screens/connect-oauth.tsx): one row per
+ *  account, `revoked: true` once deauthorized or its code reused. Read by the account list and the event path too. */
+export const OAUTH_CONNECTIONS = '_oauth_connection';
+export function publicBusinessName(account) {
+    const named = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+    return named(account?.business_profile?.name) ?? named(account?.settings?.dashboard?.display_name) ?? PLATFORM_DEFAULT_NAME;
+}

package/dist/src/engine/disputes.js

@@ -0,0 +1,9 @@
+"use strict";
+// Dispute semantics. A dispute is Stripe's to open, when a charge's cardholder disputes it: the test cards
+// that are disputed open one as their charge succeeds (./after-payment.ts). It is then listed, retrieved,
+// updated with evidence and closed. Closing concedes it (status → lost), the machine's move in
+// ../manifest.ts. Evidence is submitted with the update unless `submit` is false
+// (docs.stripe.com/api/disputes/update#update_dispute-submit), and the bank then decides it: in test mode, evidence whose
+// uncategorized_text is `winning_evidence` wins it and `losing_evidence` loses it (docs.stripe.com/testing#evidence);
+// a won dispute returns the disputed amount. Where the documentation stops and the twin decides: the bank decides at
+// once, and any other evidence leaves the dispute under review. List is the derived core's.

package/dist/src/engine/entitlements.d.ts

@@ -0,0 +1 @@
+export declare const FEAT = "entitlements.feature";

package/dist/src/engine/entitlements.js

@@ -0,0 +1,4 @@
+// Entitlements semantics: features (unique by lookup_key) that products grant, and the features a
+// customer is entitled to now, derived from its live subscriptions' products. Feature retrieve is
+// the derived core's.
+export const FEAT = 'entitlements.feature';

package/dist/src/engine/ephemeral-keys.js

@@ -0,0 +1,4 @@
+"use strict";
+// Ephemeral key semantics: the short-lived key the mobile SDKs use, scoped to exactly one object.
+// It needs the Stripe-Version header; its secret is answered only by the create; deleting it
+// expires it early.

package/dist/src/engine/files.d.ts

@@ -0,0 +1,18 @@
+import type { Row } from './common.js';
+/** The type Stripe answers for an uploaded file: "The returned file type (for example, csv, pdf, jpg, or png)"
+ *  (docs.stripe.com/api/files/object). Where the documentation stops and the twin decides: read from the name's
+ *  extension (jpeg as jpg), and null for a name without one. */
+export declare function fileType(name: string): string | null;
+/** The purposes a file link may be made to: "The file's `purpose` must be one of the following: …" (the served
+ *  spec, POST /v1/file_links `file`). */
+export declare const LINKABLE: readonly ["business_icon", "business_logo", "customer_signature", "dispute_evidence", "finance_report_run", "financial_account_statement", "identity_document_downloadable", "issuing_regulatory_reporting", "pci_document", "selfie", "sigma_scheduled_query", "tax_document_user_upload", "terminal_android_apk", "terminal_reader_splashscreen"];
+export declare const PBC = "billing_portal.configuration";
+/** A portal configuration's features, each filled where the request leaves it: every feature is answered (the served
+ *  spec requires all five), as the create page's example answers a request that sets only customer_update and
+ *  invoice_history: payment_method_update disabled, subscription_cancel disabled at_period_end with proration_behavior
+ *  none and its five default reasons, subscription_update disabled with no allowed updates and proration_behavior none
+ *  (docs.stripe.com/api/customer_portal/configurations/create); trial_update_behavior "Defaults to a value of
+ *  `end_trial` if you don't set it during creation" (the served spec). Where the documentation stops and the twin
+ *  decides: a feature the request leaves out is disabled, and schedule_at_period_end has no conditions. */
+export declare const PORTAL_FEATURES: Row;
+export declare const filled: (base: unknown, given: unknown) => unknown;

package/dist/src/engine/files.js

@@ -0,0 +1,33 @@
+/** The type Stripe answers for an uploaded file: "The returned file type (for example, csv, pdf, jpg, or png)"
+ *  (docs.stripe.com/api/files/object). Where the documentation stops and the twin decides: read from the name's
+ *  extension (jpeg as jpg), and null for a name without one. */
+export function fileType(name) {
+    const ext = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
+    return ext ? (ext === 'jpeg' ? 'jpg' : ext) : null;
+}
+/** The purposes a file link may be made to: "The file's `purpose` must be one of the following: …" (the served
+ *  spec, POST /v1/file_links `file`). */
+export const LINKABLE = ['business_icon', 'business_logo', 'customer_signature', 'dispute_evidence', 'finance_report_run', 'financial_account_statement', 'identity_document_downloadable', 'issuing_regulatory_reporting', 'pci_document', 'selfie', 'sigma_scheduled_query', 'tax_document_user_upload', 'terminal_android_apk', 'terminal_reader_splashscreen'];
+export const PBC = 'billing_portal.configuration';
+/** A portal configuration's features, each filled where the request leaves it: every feature is answered (the served
+ *  spec requires all five), as the create page's example answers a request that sets only customer_update and
+ *  invoice_history: payment_method_update disabled, subscription_cancel disabled at_period_end with proration_behavior
+ *  none and its five default reasons, subscription_update disabled with no allowed updates and proration_behavior none
+ *  (docs.stripe.com/api/customer_portal/configurations/create); trial_update_behavior "Defaults to a value of
+ *  `end_trial` if you don't set it during creation" (the served spec). Where the documentation stops and the twin
+ *  decides: a feature the request leaves out is disabled, and schedule_at_period_end has no conditions. */
+export const PORTAL_FEATURES = {
+    customer_update: { allowed_updates: [], enabled: false },
+    invoice_history: { enabled: false },
+    payment_method_update: { enabled: false, payment_method_configuration: null },
+    subscription_cancel: { cancellation_reason: { enabled: false, options: ['too_expensive', 'missing_features', 'switched_service', 'unused', 'other'] }, enabled: false, mode: 'at_period_end', proration_behavior: 'none' },
+    subscription_update: { default_allowed_updates: [], enabled: false, proration_behavior: 'none', schedule_at_period_end: { conditions: [] }, trial_update_behavior: 'end_trial' },
+};
+export const filled = (base, given) => {
+    if (!given || typeof given !== 'object' || Array.isArray(given) || !base || typeof base !== 'object' || Array.isArray(base))
+        return given === undefined ? base : given;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(given))
+        out[k] = filled(base[k], v);
+    return out;
+};

package/dist/src/engine/front.d.ts

@@ -0,0 +1,5 @@
+export declare const PUBLISHABLE_CREATES: Set<string>;
+export declare const BY_CLIENT_SECRET: Record<string, {
+    type: string;
+    param: string;
+}>;

package/dist/src/engine/front.js

@@ -0,0 +1,25 @@
+// ── what a publishable key may call ──
+// "Publishable API key pk_... | Safe to expose: Yes | API key for Stripe.js, Elements, and mobile SDKs. It can identify
+// your account and create tokens or PaymentMethods from payment details, but it can't perform sensitive operations such
+// as creating charges or reading account data" (docs.stripe.com/keys). The served spec names the calls a publishable key
+// makes with an object's client secret: "You can retrieve a PaymentIntent client-side using a publishable key when the
+// client_secret is provided in the query string" (GET /v1/payment_intents/{intent}), "Client-side retrieval using a
+// publishable key is allowed when the client_secret is provided" (GET /v1/setup_intents/{intent}), "Required if a
+// publishable key is used to retrieve the source" (GET /v1/sources/{source}), and the confirm and verify_microdeposits
+// calls that take "The client secret of the PaymentIntent" (or SetupIntent). Anything else is refused with Stripe's
+// code: "secret_key_required | The API key provided is a publishable key, but a secret key is required"
+// (docs.stripe.com/error-codes), as 403, "The API key doesn't have permissions to perform the request"
+// (docs.stripe.com/api/errors).
+// Where the documentation stops and the twin decides: the list above is the whole of what a publishable key may call
+// (Stripe publishes no complete list); a client-secret call without the secret answers parameter_missing, and one with a
+// secret that is not the object's answers the object's 404, as though the key could not see it.
+export const PUBLISHABLE_CREATES = new Set(['PostTokens', 'PostPaymentMethods']);
+export const BY_CLIENT_SECRET = {
+    GetPaymentIntentsIntent: { type: 'payment_intent', param: 'intent' },
+    PostPaymentIntentsIntentConfirm: { type: 'payment_intent', param: 'intent' },
+    PostPaymentIntentsIntentVerifyMicrodeposits: { type: 'payment_intent', param: 'intent' },
+    GetSetupIntentsIntent: { type: 'setup_intent', param: 'intent' },
+    PostSetupIntentsIntentConfirm: { type: 'setup_intent', param: 'intent' },
+    PostSetupIntentsIntentVerifyMicrodeposits: { type: 'setup_intent', param: 'intent' },
+    GetSourcesSource: { type: 'source', param: 'source' },
+};

package/dist/src/engine/invoices.d.ts

@@ -0,0 +1,24 @@
+import type { Row } from './common.js';
+export declare const INV = "invoice";
+export declare const linesOf: (inv: Row) => Row[];
+export declare const sumLines: (lines: Row[]) => number;
+/** A draft's line no invoice item made (a subscription's) stays as it is when an item changes. */
+export declare function unlinkedLine(line: Row): Row;
+/** A preview's proration for a change at proration_date. Where the documentation stops and the twin decides: half the
+ *  period's charge credited as unused time and half charged as remaining time. */
+export declare function prorationLines(out: Row[], subtotal: number, currency: string, now: number, period: number): void;
+/** A draft invoice's fields before anything is on it: what a new invoice and a preview start from. */
+export declare const draft: (now: number) => Row;
+/** Whether leaving draft mints a PaymentIntent: only a charge_automatically invoice with a balance. */
+export declare const collectsThroughIntent: (inv: Row) => boolean;
+export declare const transitions: (inv: Row) => object;
+/** What finalizing assigns: the invoice's `number`, the customer's invoice_prefix and a sequence
+ *  (https://docs.stripe.com/api/invoices/object#invoice_object-number), and for send_invoice a
+ *  `due_date` days_until_due after finalization (#invoice_object-due_date). */
+/** A customer's invoice_prefix, "The prefix for the customer used to generate unique invoice numbers"
+ *  (docs.stripe.com/api/customers/object): the twin's, from the customer's id. */
+export declare const invoicePrefix: (customerId: string) => string;
+/** An invoice's payment as Stripe answers it (docs.stripe.com/api/invoice-payment/object): the PaymentIntent that
+ *  collects the invoice, open until the invoice is paid. Where the documentation stops and the twin decides: an
+ *  invoice has one payment, its default, and the payment's id is the invoice's with `inpay_`. */
+export declare function invoicePayment(inv: Row): Row | undefined;