@volter/twin-stripe 2.0.38 → 3.0.0

package/src/engine/connect.ts

@@ -0,0 +1,184 @@
+// 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.ts';
+import { currentlyDue, kindOf } from './onboarding.ts';
+import { externalList, type Row } from './common.ts';
+
+// 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 = (): 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,
+});
+
+/** 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: 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 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: 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 } };
+}
+
+/** 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: Row, path: string): unknown => path.split('.').reduce<unknown>((v, k) => (v && typeof v === 'object' ? (v as Row)[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: string): boolean => [...CARD_COMPANY_NOW, ...CARD_COMPANY_LATER, ...CARD_INDIVIDUAL_NOW].includes(field);
+export 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 !== '';
+};
+export 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 !== '';
+};
+export 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). */
+export 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;
+}
+
+/** 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: 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;
+}
+export const RELATIONSHIP: Row = { 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: 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 },
+  };
+};
+
+// 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: 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'],
+};
+export 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;
+}

package/src/engine/coupons.ts

@@ -0,0 +1,5 @@
+// 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/src/engine/credit-notes.ts

@@ -0,0 +1,6 @@
+// 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/src/engine/customers.ts

@@ -0,0 +1,35 @@
+// 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.ts';
+import type { Row } from './common.ts';
+
+/** 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: string): Row => ({ 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: Record<string, RegExp> = {
+  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: string): string | undefined => {
+  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/src/engine/display.ts

@@ -0,0 +1,19 @@
+// What Stripe's pages show of an account, and where its Connect OAuth connections are kept.
+
+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 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: Row | undefined): string {
+  const named = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v : undefined);
+  return named(account?.business_profile?.name) ?? named(account?.settings?.dashboard?.display_name) ?? PLATFORM_DEFAULT_NAME;
+}

package/src/engine/disputes.ts

@@ -0,0 +1,9 @@
+// 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/src/engine/entitlements.ts

@@ -0,0 +1,5 @@
+// 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/src/engine/ephemeral-keys.ts

@@ -0,0 +1,3 @@
+// 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/src/engine/files.ts

@@ -0,0 +1,41 @@
+// File, file link, Identity and billing-portal semantics. A file is the uploaded document's object
+// (the twin keeps no bytes); a file link is answered, not kept. An Identity verification session is
+// created here and verified through the twin's own helper outside Stripe's surface; its reports
+// are the derived core's to list and read, as are file list and retrieve, session retrieve and
+// portal-configuration retrieve.
+import type { Row } from './common.ts';
+
+/** 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: string): string | null {
+  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'] as const;
+
+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: Row = {
+  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: unknown, given: unknown): unknown => {
+  if (!given || typeof given !== 'object' || Array.isArray(given) || !base || typeof base !== 'object' || Array.isArray(base)) return given === undefined ? base : given;
+  const out: Row = { ...(base as Row) };
+  for (const [k, v] of Object.entries(given as Row)) out[k] = filled((base as Row)[k], v);
+  return out;
+};

package/src/engine/front.ts

@@ -0,0 +1,31 @@
+// What a publishable key may call, as data the handlers' shared checks read (../semantics/shared.ts
+// publishableKeyRefused, run by ../semantics/around.ts).
+import { expandOf, render, servesCurrent, withoutEndpointSecret } from './version.ts';
+
+type Row = Record<string, unknown>;
+
+// ── 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: Record<string, { type: string; param: string }> = {
+  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/src/engine/invoices.ts

@@ -0,0 +1,71 @@
+// Invoice and InvoiceItem semantics. The machine in ../manifest.ts says which moves of an invoice's
+// `status` are legal (finalize, send, pay, mark_uncollectible, void) and what Stripe answers
+// otherwise; these handlers compute each move, keep a draft's lines and totals in step with its
+// items, and mint the PaymentIntent a finalized invoice collects through. The invoice list and the
+// item list are the derived core's.
+import type { Row } from './common.ts';
+
+export const INV = 'invoice';
+export const linesOf = (inv: Row): Row[] => (inv.lines as { data?: Row[] } | undefined)?.data ?? [];
+export const sumLines = (lines: Row[]): number => lines.reduce((s, l) => s + (Number(l.amount) || 0), 0);
+
+/** A draft's line no invoice item made (a subscription's) stays as it is when an item changes. */
+export function unlinkedLine(line: Row): Row {
+  return line;
+}
+
+/** 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 function prorationLines(out: Row[], subtotal: number, currency: string, now: number, period: number): void {
+  const half = Math.round(subtotal / 2);
+  out.unshift({ id: 'il_twin_proration_unused', object: 'line_item', type: 'invoiceitem', amount: -half, currency, proration: true, period: { start: now, end: period }, description: 'Unused time (proration credit)' });
+  out.push({ id: 'il_twin_proration_remaining', object: 'line_item', type: 'invoiceitem', amount: half, currency, proration: true, period: { start: now, end: period }, description: 'Remaining time (proration charge)' });
+}
+
+// ── invoices ──
+
+/** A draft invoice's fields before anything is on it: what a new invoice and a preview start from. */
+export const draft = (now: number): Row => ({
+  status: 'draft', livemode: false, currency: 'usd', collection_method: 'charge_automatically',
+  auto_advance: false, attempt_count: 0, attempted: false,
+  amount_due: 0, amount_paid: 0, amount_remaining: 0, amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
+  subtotal: 0, total: 0, starting_balance: 0, post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
+  period_start: now, period_end: now, default_tax_rates: [], discounts: [],
+  lines: { object: 'list', data: [], has_more: false, total_count: 0 },
+  automatic_tax: { enabled: false, liability: null, status: null },
+  status_transitions: { finalized_at: null, marked_uncollectible_at: null, paid_at: null, voided_at: null },
+  issuer: { type: 'self' },
+  payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
+  // a draft has no PaymentIntent: finalize mints it
+  payment_intent: null,
+});
+
+/** Whether leaving draft mints a PaymentIntent: only a charge_automatically invoice with a balance. */
+// "Finalizing an invoice does the following: ... It creates an incomplete payment intent for the invoice"
+// (docs.stripe.com/invoicing/integration/workflow-transitions), whichever its collection method
+export const collectsThroughIntent = (inv: Row): boolean => inv.status === 'draft' && (Number(inv.amount_due) || 0) > 0;
+
+export const transitions = (inv: Row): object => (inv.status_transitions as 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 const invoicePrefix = (customerId: string): string => customerId.replace(/[^a-z0-9]/gi, '').slice(-8).toUpperCase() || 'TWIN';
+
+/** 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 function invoicePayment(inv: Row): Row | undefined {
+  if (typeof inv.payment_intent !== 'string') return undefined;
+  const paid = inv.status === 'paid';
+  const transitions = (inv.status_transitions as Row | undefined) ?? {};
+  return {
+    id: `inpay_${String(inv.id).replace(/^in_/, '')}`, object: 'invoice_payment', invoice: inv.id, is_default: true, livemode: false,
+    amount_requested: Number(inv.amount_due ?? 0), amount_paid: paid ? Number(inv.amount_paid ?? inv.amount_due ?? 0) : null, currency: inv.currency,
+    created: inv.created, payment: { type: 'payment_intent', payment_intent: inv.payment_intent },
+    status: paid ? 'paid' : inv.status === 'void' ? 'canceled' : 'open',
+    status_transitions: { paid_at: paid ? (transitions.paid_at ?? null) : null, canceled_at: inv.status === 'void' ? (transitions.voided_at ?? null) : null },
+  };
+}

package/src/engine/issuing.ts

@@ -0,0 +1,61 @@
+// Issuing semantics: cardholders, cards, authorizations, transactions, disputes, network tokens and
+// personalization designs. An authorization's `card` is the full Card in every answer and webhook
+// (the manifest's write hook embeds it on writes; reads embed it here). The machines in
+// ../manifest.ts say how authorizations, disputes, cards, cardholders, tokens and designs move.
+//
+// The test-helper routes here (/v1/test_helpers/issuing/…) are Stripe's own doors for what no API
+// verb makes: a card presented at a merchant, a capture, a force capture, a design's review. A
+// presented authorization is decided in Stripe's order: card status, then spending controls
+// (card, then cardholder), then the real-time issuing_authorization.request webhook delivered
+// synchronously to the first enrolled endpoint; with none it is approved (card_active).
+import type { Row } from './common.ts';
+
+export const CH = 'issuing.cardholder';
+/** The id of a card's cardholder: the card answers the cardholder in full (the served spec's issuing.card.cardholder is
+ *  the Cardholder object, not an id); its id is read from it for filtering and for the objects that name it by id. */
+export const holderId = (c: Row): string => (typeof c.cardholder === 'string' ? c.cardholder : String((c.cardholder as Row | undefined)?.id ?? ''));
+export const CARD = 'issuing.card';
+export const AUTH = 'issuing.authorization';
+export const TXN = 'issuing.transaction';
+export const DSP = 'issuing.dispute';
+export const TOK = 'issuing.token';
+export const PD = 'issuing.personalization_design';
+
+/** One request_history entry; the authorization code is derived from the request time (Stripe's is not unique either). */
+export function historyEntry(o: { amount: number; currency: string; approved: boolean; reason: string; reasonMessage: string | null; createdSec: number; merchantAmount: number; merchantCurrency: string }): Row {
+  return {
+    amount: o.amount, amount_details: null, approved: o.approved,
+    authorization_code: o.approved ? `S${String(100000 + (o.createdSec % 900000))}` : null,
+    created: o.createdSec, currency: o.currency,
+    merchant_amount: o.merchantAmount, merchant_currency: o.merchantCurrency,
+    network_risk_score: null, reason: o.reason, reason_message: o.reasonMessage,
+    requested_at: o.createdSec,
+  };
+}
+
+/** The test helper's default merchant, under any merchant_data the caller gives. */
+export function merchantData(param: unknown): Row {
+  const base: Row = {
+    category: 'general', category_code: '5399', city: 'San Francisco', country: 'US',
+    name: 'Twin Test Merchant', network_id: '1234567890', postal_code: '94103', state: 'CA',
+    tax_id: null, terminal_id: null, url: null,
+  };
+  if (param && typeof param === 'object' && !Array.isArray(param)) Object.assign(base, param);
+  return base;
+}
+
+/** The card's stored id (an embedded card answers with its id). */
+export const cardId = (auth: Row): unknown => (auth.card && typeof auth.card === 'object' ? (auth.card as Row).id : auth.card);
+
+/** The real-time window: "If Stripe doesn't receive your approve or decline response within 2 seconds, the
+ *  Authorization is automatically approved or declined based on your timeout settings"
+ *  (docs.stripe.com/issuing/controls/real-time-authorizations). */
+export const REALTIME_WINDOW_SECONDS = 2;
+
+/** Stripe's physical bundles are its catalog, not the account's: the twin serves the one its reference publishes
+ *  (docs.stripe.com/api/issuing/physical_bundles: "US Visa Credit White", standard, active, a card logo required and
+ *  carrier text optional). Where the documentation stops and the twin decides: the catalog is that one bundle, and its
+ *  second_line (required by the served spec, absent from the example) is optional. */
+export const PHYSICAL_BUNDLES: Row[] = [
+  { id: 'ics_NLuXJPDYSTjFON', object: 'issuing.physical_bundle', livemode: false, name: 'US Visa Credit White', features: { card_logo: 'required', carrier_text: 'optional', second_line: 'optional' }, status: 'active', type: 'standard' },
+];

package/src/engine/ledger.ts

@@ -0,0 +1,50 @@
+// Stripe's balance ledger (docs.stripe.com/api/balance_transactions): every movement of the account's money writes
+// a balance transaction, and the balance is their sum. A captured charge adds its amount less Stripe's fee, pending
+// until its available_on; a refund takes its amount back at once; a payout takes its amount out of what is available
+// and is refused beyond it (balance_insufficient). A transaction's status is what the World clock says of its
+// available_on (the machine's time move, pending → available), so a `wait` in a story settles funds as time does.
+//
+// Where the documentation stops and the twin decides: the fee is Stripe's standard US card pricing, 2.9% + 30¢
+// (stripe.com/pricing), for every charge; funds become available two days after capture (Stripe's standard US
+// payout schedule counts business days).
+//
+// Test mode (the twin serves livemode: false), as docs.stripe.com/testing documents it:
+// - cards keep that delay but two: "Other test cards send funds from a successful payment to your pending balance",
+//   while 4000000000000077 and 4000003720000278 (and their test names pm_card_bypassPending,
+//   pm_card_bypassPendingInternational, tok_bypassPending, tok_bypassPendingInternational) "succeed. Funds are added
+//   directly to your available balance, bypassing your pending balance" (#available-balance; test-cards.ts). A
+//   PaymentMethod made from one keeps that (payment-methods.ts, after-payment.ts), so a saved card charged later by
+//   id bypasses too;
+// - a US bank account debit: "Test transactions settle instantly and are added to your available test balance. This
+//   behavior differs from live mode" (ACH Direct Debit, "Test settlement behavior");
+// - a source_transaction transfer "takes on the pending status of the associated charge"
+//   (docs.stripe.com/connect/separate-charges-and-transfers), so it is available at once when its charge is;
+// - "Test payouts simulate a live payout but aren't processed with the bank" (docs.stripe.com/payouts#test-payouts):
+//   the payout clock (semantics/balance.ts) is live's.
+// No other test-mode speed-up is documented, so 4242 4242 4242 4242 funds sit pending the two days.
+//
+// Where the documentation stops and the twin decides: every credit written available at once (a bypass or bank-debit
+// charge, a transfer, a transfer from such a charge, an application fee, a top-up, an Issuing top-up included, a reversal) is marked not yet
+// sent, and the drain sends its account balance.available for it ("Occurs whenever your Stripe balance has been
+// updated (e.g., when a charge is available to be paid out). ... This event is not fired for negative
+// transactions", docs.stripe.com/api/events/types), as it does for funds that came due after the delay. The Balance
+// it carries is the account's at the drain: a debit or an automatic payout landing first shows in it.
+//
+// Each connected account keeps its own balance (docs.stripe.com/connect/account-balances): a transaction belongs to
+// the account the request acts for (the Stripe-Account header), else to the platform. A transfer takes its amount out
+// of the platform's available balance and adds it to the destination's; a destination charge transfers its amount
+// less the application fee, available when the charge's funds are; a direct charge's application fee moves from the
+// connected account to the platform.
+import type { Row } from './common.ts';
+import { BYPASS_PENDING_CARDS } from './test-cards.ts';
+
+export const BT = 'balance_transaction';
+export const DAY = 86_400;
+/** A ledger entry's mark: available at once, its balance.available not yet sent (settleDueEntries). */
+export const UNSENT = '_availableUnsent';
+export const BYPASS_NUMBERS = new Set(Object.values(BYPASS_PENDING_CARDS).map((c) => c.number));
+
+export const feeOf = (amount: number): number => (amount > 0 ? Math.round(amount * 0.029) + 30 : 0);
+
+/** Whether a stored ledger entry is on this account's balance (undefined: the platform's). */
+export const onAccount = (t: Row, account: string | undefined): boolean => (typeof t._account === 'string' ? t._account : undefined) === account;

package/src/engine/oauth.ts

@@ -0,0 +1,19 @@
+// A connected account's OAuth connection to the platform (../screens/connect-oauth.tsx makes it), as the API reads it:
+// whether it was revoked, which account an OAuth key acts as, and a key shown as Stripe's errors show one.
+
+/** A key shown the way Stripe's errors show one: its prefix and its last four. */
+export const redactKey = (key: string): string => {
+  const prefix = /^(sk|rk|pk)_(test|live)_/.exec(key)?.[0] ?? '';
+  const rest = key.slice(prefix.length);
+  return rest.length > 4 ? `${prefix}${'*'.repeat(rest.length - 4)}${rest.slice(-4)}` : `${prefix}${'*'.repeat(rest.length)}`;
+};
+
+/** The API key a request carries: Bearer, or Basic's user (`curl -u sk_…:`, docs.stripe.com/api/authentication). */
+export function requestKey(request: Request): string {
+  const header = request.headers.get('authorization') ?? '';
+  const bearer = /^bearer\s+(\S+)/i.exec(header)?.[1];
+  if (bearer) return bearer;
+  const basic = /^basic\s+(\S+)/i.exec(header)?.[1];
+  if (basic) { try { return atob(basic).split(':')[0] ?? ''; } catch { return ''; } }
+  return '';
+}