@volter/twin-stripe 2.0.38 → 3.0.0

package/src/engine/onboarding.ts

@@ -0,0 +1,54 @@
+// What a connected account owes Stripe before it can take payments (the requirements its onboarding collects,
+// ../screens/connect-onboarding.tsx), as the Accounts API reports them (`requirements.currently_due`): the two US sets the twin
+// models, a company's and an individual's.
+import { INDUSTRIES as MCCS } from './industries.ts';
+
+type Row = Record<string, unknown>;
+
+export const OFFERED = new Set(MCCS.map(([mcc]) => mcc));
+
+export type Form = Record<string, string>;
+
+export type Kind = 'company' | 'individual';
+
+export const has = (v: Form, k: string): boolean => (v[k] ?? '').trim() !== '';
+
+export const dobPart = (v: Form, i: number): boolean => /^\d{4}-\d{2}-\d{2}$/.test(v.dob ?? '') && Number((v.dob ?? '').split('-')[i]) > 0;
+
+/** Each requirement Stripe names, the form's answer that meets it, and which of the two sets it belongs to. */
+export const REQUIREMENTS: Array<[string, (v: Form) => boolean, Kind[]]> = [
+  ['business_profile.mcc', (v) => OFFERED.has((v.mcc ?? '').trim()), ['company', 'individual']],
+  ['business_profile.url', (v) => has(v, 'url'), ['company', 'individual']],
+  ['settings.payments.statement_descriptor', (v) => has(v, 'statement_descriptor'), ['company', 'individual']],
+  ['company.name', (v) => has(v, 'company_name'), ['company']],
+  ['company.tax_id', (v) => has(v, 'company_tax_id'), ['company']],
+  ['company.phone', (v) => has(v, 'company_phone'), ['company']],
+  ['company.address.line1', (v) => has(v, 'company_line1'), ['company']],
+  ['company.address.city', (v) => has(v, 'company_city'), ['company']],
+  ['company.address.state', (v) => has(v, 'company_state'), ['company']],
+  ['company.address.postal_code', (v) => has(v, 'company_postal_code'), ['company']],
+  ['company.owners_provided', (v) => v.owners_provided === 'provided', ['company']],
+  ['owners.first_name', (v) => has(v, 'owner_first_name'), ['company']],
+  ['owners.last_name', (v) => has(v, 'owner_last_name'), ['company']],
+  ['owners.email', (v) => has(v, 'owner_email'), ['company']],
+  ...(['first_name', 'last_name', 'email', 'phone'] as const).flatMap((f): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.${f}`, (v) => has(v, f), ['company']], [`individual.${f}`, (v) => has(v, f), ['individual']]]),
+  ...(['day', 'month', 'year'] as const).flatMap((f, i): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.dob.${f}`, (v) => dobPart(v, 2 - i), ['company']], [`individual.dob.${f}`, (v) => dobPart(v, 2 - i), ['individual']]]),
+  ...(['line1', 'city', 'state', 'postal_code'] as const).flatMap((f): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.address.${f}`, (v) => has(v, f), ['company']], [`individual.address.${f}`, (v) => has(v, f), ['individual']]]),
+  ['representative.relationship.title', (v) => has(v, 'title'), ['company']],
+  ['representative.ssn_last_4', (v) => /^\d{4}$/.test(v.ssn_last_4 ?? ''), ['company']],
+  ['individual.ssn_last_4', (v) => /^\d{4}$/.test(v.ssn_last_4 ?? ''), ['individual']],
+  ['tos_acceptance.date', (v) => v.tos === 'accepted', ['company', 'individual']],
+  ['tos_acceptance.ip', (v) => v.tos === 'accepted', ['company', 'individual']],
+  ['external_account', (v) => has(v, 'routing_number') && has(v, 'account_number'), ['company', 'individual']],
+];
+
+/** The set an account onboards against: the two US sets the twin models, or none. */
+export function kindOf(account: Row): Kind | undefined {
+  const type = account.business_type ?? 'individual';
+  return (account.country ?? 'US') === 'US' && (type === 'company' || type === 'individual') ? type : undefined;
+}
+
+/** What an account of this kind still owes, given the form's answers (none: all of it). */
+export function currentlyDue(kind: Kind, v: Form = {}): string[] {
+  return REQUIREMENTS.filter(([, met, kinds]) => kinds.includes(kind) && !met(v)).map(([req]) => req);
+}

package/src/{stripe-params.ts → engine/params.ts}

@@ -9,17 +9,15 @@
 // Where the evidence stops: the check knows only the served version's parameters (the spec's, surface.version). A
 // request pinning an earlier version with Stripe-Version is not checked, since the pack holds no earlier spec, beyond
 // the values of the payment_method_types it still takes (PAYMENT_METHOD_TYPES below); nested parameters are not checked.
-import { readParams, vendorError, type DerivedCall } from '@volter/world-core';
-import surface from './generated/surface.gen.json' with { type: 'json' };
-import { manifest } from './manifest.ts';
-import { SERVED_VERSION } from './stripe-version.ts';
+
+import surface from '../generated/surface.gen.json' with { type: 'json' };
 
 type Param = { name: string; required?: boolean };
 type Op = { id: string; method: string; query?: Param[]; body?: Param[] };
-const OPS = new Map((surface.operations as Op[]).map((o) => [o.id, o]));
+export const OPS = new Map((surface.operations as Op[]).map((o) => [o.id, o]));
 
 /** Parameters Stripe documents outside its published spec, each with the page that documents it. */
-const DOCUMENTED: Record<string, string[]> = {
+export const DOCUMENTED: Record<string, string[]> = {
   // a top-up into the Issuing balance (docs.stripe.com/issuing/funding/balance: "destination_balance=issuing")
   PostTopups: ['destination_balance'],
 };
@@ -50,8 +48,8 @@ const DOCUMENTED: Record<string, string[]> = {
 export const METHOD_TYPES_REMOVED_IN = '2026-08-26.preview';
 /** Whether a pinned version is at or after the removal: versions order by their date (YYYY-MM-DD). */
 export const methodTypesRemoved = (pinned: string): boolean => pinned.slice(0, 10) >= METHOD_TYPES_REMOVED_IN.slice(0, 10);
-const REMOVED_TYPES = new Set(['PostPaymentIntents', 'PostPaymentIntentsIntent', 'PostPaymentIntentsIntentConfirm', 'PostSetupIntents', 'PostSetupIntentsIntent']);
-const TYPED = new Set([...REMOVED_TYPES, 'PostCheckoutSessions']);
+export const REMOVED_TYPES = new Set(['PostPaymentIntents', 'PostPaymentIntentsIntent', 'PostPaymentIntentsIntentConfirm', 'PostSetupIntents', 'PostSetupIntentsIntent']);
+export const TYPED = new Set([...REMOVED_TYPES, 'PostCheckoutSessions']);
 type Resource = { name: string; fields: Array<{ name: string; enum?: string[] }> };
 /** The payment method types there are: the PaymentMethod object's `type` in the served spec. */
 export const PAYMENT_METHOD_TYPES: readonly string[] = (surface.resources as Resource[]).find((r) => r.name === 'payment_method')?.fields.find((f) => f.name === 'type')?.enum ?? [];
@@ -61,56 +59,10 @@ export const PAYMENT_METHOD_TYPES: readonly string[] = (surface.resources as Res
  *  interac_present) and no `custom`. The surface keeps no request enums, so it is copied here. */
 export const CHECKOUT_METHOD_TYPES: readonly string[] = ['acss_debit', 'affirm', 'afterpay_clearpay', 'alipay', 'alma', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'billie', 'bizum', 'blik', 'boleto', 'card', 'cashapp', 'crypto', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'kakao_pay', 'klarna', 'konbini', 'kr_card', 'link', 'mb_way', 'mobilepay', 'multibanco', 'naver_pay', 'nz_bank_account', 'oxxo', 'p24', 'pay_by_bank', 'payco', 'paynow', 'paypal', 'paypay', 'payto', 'pix', 'promptpay', 'revolut_pay', 'samsung_pay', 'satispay', 'scalapay', 'sepa_debit', 'sequra', 'sofort', 'sunbit', 'swish', 'twint', 'upi', 'us_bank_account', 'wechat_pay', 'zip'];
 /** The create page each intent's refusal links to. */
-const TYPES_DOC: Record<string, string> = {
+export const TYPES_DOC: Record<string, string> = {
   payment_intents: 'https://stripe.com/docs/api/payment_intents/create#create_payment_intent-payment_method_types',
   setup_intents: 'https://stripe.com/docs/api/setup_intents/create#create_setup_intent-payment_method_types',
 };
 
 /** An enum's values as Stripe lists them in a refusal: "a, b, or c". */
-const oneOf = (values: readonly string[]): string => (values.length > 1 ? `${values.slice(0, -1).join(', ')}, or ${values.at(-1)}` : values.join(''));
-
-/** An earlier version's payment_method_types refused: the first value that names no payment method type the
- *  operation takes, in the intent's words or (a Checkout Session) the enum's. */
-function unknownMethodType(opId: string, given: unknown): Response | undefined {
-  const values = Array.isArray(given) ? given : given && typeof given === 'object' ? Object.values(given) : [given];
-  const checkout = opId === 'PostCheckoutSessions';
-  const known = checkout ? CHECKOUT_METHOD_TYPES : PAYMENT_METHOD_TYPES;
-  const i = values.findIndex((v) => !known.includes(String(v)));
-  if (i < 0) return undefined;
-  if (checkout) {
-    const param = `payment_method_types[${i}]`;
-    return vendorError(manifest, { status: 400, param, message: `Invalid ${param}: must be one of ${oneOf(known)}` });
-  }
-  const doc = TYPES_DOC[opId.startsWith('PostSetupIntents') ? 'setup_intents' : 'payment_intents'];
-  return vendorError(manifest, { status: 400, param: 'payment_method_types', message: `The payment method type "${String(values[i])}" is invalid. See ${doc} for the full list of supported payment method types.` });
-}
-
-/** payment_method_types refused where the caller's version removed it. */
-const noLongerSupported = (version: string): Response =>
-  vendorError(manifest, { status: 400, code: 'payment_method_types_no_longer_supported', param: 'payment_method_types', message: `payment_method_types is no longer supported in API version ${version}. Use allowed_payment_method_types, or dynamic payment methods, instead.` });
-
-/** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
-export async function refuseParameters(call: DerivedCall): Promise<Response | undefined> {
-  const op = OPS.get(call.operation.id);
-  if (!op) return undefined;
-  const pinned = call.request.headers.get('stripe-version');
-  if (pinned && pinned < SERVED_VERSION) {
-    if (!TYPED.has(op.id)) return undefined;
-    const earlier = await readParams(manifest, call.request.clone(), call.operation);
-    if (earlier.payment_method_types === undefined) return undefined;
-    if (REMOVED_TYPES.has(op.id) && methodTypesRemoved(pinned)) return noLongerSupported(pinned);
-    return unknownMethodType(op.id, earlier.payment_method_types);
-  }
-  const method = call.request.method.toUpperCase();
-  const known = new Set([...(op.query ?? []), ...(op.body ?? [])].map((p) => p.name).concat(DOCUMENTED[op.id] ?? []));
-  const params = await readParams(manifest, call.request.clone(), call.operation);
-  if (REMOVED_TYPES.has(op.id) && params.payment_method_types !== undefined) return noLongerSupported(pinned ?? SERVED_VERSION);
-  for (const name of Object.keys(params)) {
-    if (!known.has(name)) return vendorError(manifest, { status: 400, code: 'parameter_unknown', param: name, message: `Received unknown parameter: ${name}` });
-  }
-  const required = method === 'GET' || method === 'DELETE' ? (op.query ?? []) : (op.body ?? []);
-  for (const p of required) {
-    if (p.required && params[p.name] === undefined) return vendorError(manifest, { status: 400, code: 'parameter_missing', param: p.name, message: `Missing required param: ${p.name}.` });
-  }
-  return undefined;
-}
+export const oneOf = (values: readonly string[]): string => (values.length > 1 ? `${values.slice(0, -1).join(', ')}, or ${values.at(-1)}` : values.join(''));

package/src/engine/payment-intents.ts

@@ -0,0 +1,33 @@
+// PaymentIntent semantics. The machine in ../manifest.ts says which moves of `status` are legal and
+// what Stripe answers otherwise; these handlers compute what each move does. List, retrieve and
+// update are the derived core's; search is Stripe's query language over the intents.
+import type { Row } from './common.ts';
+
+export const PI = 'payment_intent';
+/** Bookkeeping: the intents whose caller named the methods (payment_method_types, allowed_payment_method_types) on
+ *  create. The twin's default list (['card']) stands for Stripe's choice and restricts nothing, so only a named list
+ *  refuses a confirm with a method of another type. Kept apart from the intent: a `_` subject is never pushed
+ *  (world-core isTwinBookkeeping). */
+export const TYPES_GIVEN = '_payment_intent_types_given';
+
+// ── THE MONEY MODEL, continued: a succeeded intent has a Charge ──
+//
+// Real Stripe always materializes a Charge when a PaymentIntent succeeds and points the intent's
+// `latest_charge` at it: the charge is what a refund lands on, so an intent that succeeds without
+// one cannot answer "refund this payment" at all. Idempotent against a repeated confirm: an intent
+// that already names a successful charge keeps it (a second one would double the money collected); a
+// declined attempt's failed charge is history, and the payment that succeeds makes its own. The id is
+// returned so the caller folds `latest_charge` into the same intent write (one write, one event). The
+// charge is written as the event Stripe sends for it, `charge.succeeded` ("Occurs whenever a charge is
+// successful", docs.stripe.com/api/events/types); Stripe has no `charge.created`.
+/** What every charge an intent makes carries of it: its transfer_group, which "identifies the resulting payment as part
+ *  of a group" (docs.stripe.com/api/payment_intents/object), its description and its metadata. */
+export function intentCarries(pi: Row): Row {
+  return {
+    ...(typeof pi.transfer_group === 'string' ? { transfer_group: pi.transfer_group } : {}),
+    ...(typeof pi.description === 'string' ? { description: pi.description } : {}),
+    // "When a PaymentIntent creates a Charge, the metadata copies to the Charge in a one-time snapshot"
+    // (docs.stripe.com/metadata, "Copy metadata to another object")
+    ...(pi.metadata && typeof pi.metadata === 'object' ? { metadata: { ...(pi.metadata as Row) } } : {}),
+  };
+}

package/src/engine/payment-links.ts

@@ -0,0 +1,6 @@
+// Payment Link and Quote semantics. Both carry line items resolved from existing prices. A payment
+// link is a reusable hosted-checkout URL, active until switched off; a quote moves draft → open
+// (finalize) → accepted or canceled, the machine in ../manifest.ts. Link retrieve and update
+// (`active`, its machine), quote retrieve and the quote list are the derived core's.
+
+export const PL = 'payment_link';

package/src/engine/payment-methods.ts

@@ -0,0 +1,25 @@
+// PaymentMethod semantics: a PaymentMethod is created detached, attached to a customer, and
+// detached again. The list is the derived core's.
+import { paymentMethodSubObject } from './stripe.ts';
+import { AFTER_SUCCESS_CARDS } from './after-payment.ts';
+import type { Row } from './common.ts';
+
+export const PM = 'payment_method';
+export const noBilling = { address: null, email: null, name: null, phone: null };
+
+export const TEST_PM_CARDS: Record<string, { brand: string; number: string }> = {
+  ...AFTER_SUCCESS_CARDS,
+  pm_card_mastercard: { brand: 'mastercard', number: '5555555555554444' },
+  pm_card_amex: { brand: 'amex', number: '378282246310005' },
+  pm_card_discover: { brand: 'discover', number: '6011111111111117' },
+};
+
+/** Attach a payment method to a customer (both known to exist or be attachable): a stored one moves to the
+ *  customer; a test name mints a new PaymentMethod on the customer carrying that card's outcome. */
+/** The card a test name (pm_card_*, tok_*) stands for, never stored as a PaymentMethod (docs.stripe.com/testing#cards). */
+export function testCardOf(ref: string): Row | undefined {
+  const name = ref.replace(/^tok_/, 'pm_card_');
+  if (!name.startsWith('pm_card_')) return undefined;
+  const test = TEST_PM_CARDS[name] ?? { brand: 'visa', number: '4242424242424242' };
+  return { ...(paymentMethodSubObject('card', { card: { number: test.number } }).card as Row), brand: test.brand };
+}

package/src/engine/plans.ts

@@ -0,0 +1,42 @@
+// Plan semantics. Stripe's Prices API "replaces the Plans API and is backwards compatible" (docs.stripe.com/api/plans/create),
+// and "Existing plans can be used wherever recurring prices are accepted", a plan being one "which can be used
+// interchangeably with a price" (docs.stripe.com/billing/migration/migrating-prices). So a plan is stored as the recurring
+// price it is, under the plan's id, and the Plans API answers recurring prices in the plan's shape: a plan made here is
+// read, listed, updated and subscribed to as a price, and a recurring price made through the Prices API is a plan.
+// The plan's id: "An identifier randomly generated by Stripe ... You can optionally override this ID, but the ID must be
+// unique across all plans in your Stripe account" (the create page's `id`). `amount_decimal` is "Same as `amount`, but
+// accepts a decimal value with at most 12 decimal places. Only one of `amount` and `amount_decimal` can be set", and the
+// plan answers it as "a decimal string", its `amount` "a whole integer if possible" (spec/openapi.json.gz, the plan
+// object). Plan writes send the plan events, plan.created / plan.updated / plan.deleted, each carrying the plan object
+// (docs.stripe.com/api/events/types; the write hook renders it, ./stripe.ts afterStripeWrite). "Deleting plans
+// means new subscribers can't be added. Existing subscribers aren't affected." (docs.stripe.com/api/plans/delete), and
+// deleting one twice is an error. Where the documentation stops and the twin decides: a minted plan id is `plan_` over
+// the price counter, a duplicate id is refused with resource_already_exists, the refusals are worded by the twin, and only
+// the per_unit scheme is modelled (a tiered plan is refused, naming the gap); a deleted plan is gone from the Plans API
+// while the recurring price it was stays readable through the Prices API, inactive, so the subscription items that name
+// it still resolve (the docs do not say what the Prices API answers for it).
+import type { Row } from './common.ts';
+
+export const INTERVALS = new Set(['day', 'week', 'month', 'year']);
+
+/** A recurring price in the plan object's shape (the create page's example response). */
+export function planOf(price: Row): Row {
+  const r = (price.recurring ?? {}) as Row;
+  const amount = typeof price.unit_amount === 'number' ? price.unit_amount : null;
+  const decimal = typeof price.unit_amount_decimal === 'string' ? price.unit_amount_decimal : amount === null ? null : String(amount);
+  return {
+    id: price.id, object: 'plan', active: price.active ?? true, amount, amount_decimal: decimal,
+    billing_scheme: price.billing_scheme ?? 'per_unit', created: price.created, currency: price.currency, interval: r.interval ?? null,
+    interval_count: r.interval_count ?? 1, livemode: false, metadata: price.metadata ?? {}, meter: r.meter ?? null, nickname: price.nickname ?? null,
+    product: price.product, tiers_mode: price.tiers_mode ?? null, transform_usage: price.transform_quantity ?? null,
+    trial_period_days: r.trial_period_days ?? null, usage_type: r.usage_type ?? 'licensed',
+  };
+}
+
+/** Metadata after an update: an empty value unsets the key, an empty `metadata` unsets them all. */
+export function metadataAfter(was: Row, given: unknown): Row {
+  if (given === '' || given === null || typeof given !== 'object') return {};
+  const next: Row = { ...was };
+  for (const [k, v] of Object.entries(given as Row)) if (v === '' || v === null) delete next[k]; else next[k] = v;
+  return next;
+}

package/src/engine/platform.ts

@@ -0,0 +1,47 @@
+// Handler for Stripe's smaller products: Climate (a fixed product and supplier catalog, and
+// orders against it), Financial Connections (sessions, linked accounts, their transactions),
+// PAN forwarding requests, and Reporting (a report-type catalog and report runs, which the twin
+// completes at once). Lists and retrieves of what is stored are the derived core's.
+import type { Handler } from '@volter/world-core';
+import type { Row } from './common.ts';
+
+// ── Climate: Stripe's catalog is managed and account-independent. The twin serves the catalog Stripe's reference
+// publishes (docs.stripe.com/api/climate/product/object, /api/climate/supplier/object): Frontier's 2027 offtake
+// portfolio at $550 a ton plus Frontier's service fees of $16.50 (3%), 18,000 tons, from Charm Industrial.
+// Where the documentation stops and the twin decides: the catalog is that one product and supplier. ──
+
+export const CLIMATE_SUPPLIERS = [
+  { id: 'climsup_charm_industrial', name: 'Charm Industrial', removal_pathway: 'biomass_carbon_removal_and_storage', info_url: 'https://frontierclimate.com/portfolio/charm-industrial', locations: [{ city: 'San Francisco', country: 'US', latitude: 37.7749, longitude: -122.4194, region: 'CA' }] },
+] as const;
+export const CLIMATE_PRODUCTS = [
+  { id: 'climsku_frontier_offtake_portfolio_2027', name: "Frontier's 2027 offtake portfolio", subtotal: 55000, fees: 1650, currency: 'usd', delivery_year: 2027, metric_tons_available: '18000', created: 1881439203, suppliers: ['climsup_charm_industrial'] },
+] as const;
+export const supplierView = (s: (typeof CLIMATE_SUPPLIERS)[number]): Row => ({ id: s.id, object: 'climate.supplier', name: s.name, removal_pathway: s.removal_pathway, info_url: s.info_url, locations: s.locations, livemode: false });
+export const productView = (p: (typeof CLIMATE_PRODUCTS)[number]): Row => ({
+  id: p.id, object: 'climate.product', name: p.name, livemode: false, delivery_year: p.delivery_year,
+  metric_tons_available: p.metric_tons_available, created: p.created,
+  current_prices_per_metric_ton: { [p.currency]: { amount_fees: p.fees, amount_subtotal: p.subtotal, amount_total: p.subtotal + p.fees } },
+  suppliers: p.suppliers.map((id) => supplierView(CLIMATE_SUPPLIERS.find((s) => s.id === id)!)),
+});
+
+export const ORDER = 'climate.order';
+
+// ── Financial Connections: a session is created for an account holder and its permissions; accounts
+// are linked in the authentication flow Stripe.js opens (../screens/financial-connections.tsx) ──
+
+export const FCS = 'financial_connections.session';
+export const FCA = 'financial_connections.account';
+export const FCT = 'financial_connections.transaction';
+
+// ── Reporting: a representative subset of Stripe's report types; a run succeeds at once ──
+
+export const REPORT_TYPES: Array<{ id: string; name: string }> = [
+  { id: 'balance.summary.1', name: 'Balance summary' },
+  { id: 'balance_change_from_activity.summary.1', name: 'Balance change from activity (summary)' },
+  { id: 'payouts.summary.1', name: 'Payouts (summary)' },
+  { id: 'payout_reconciliation.by_id.itemized.4', name: 'Payout reconciliation (itemized)' },
+];
+export const reportTypeView = (t: { id: string; name: string }): Row => ({
+  id: t.id, object: 'reporting.report_type', name: t.name, version: 1,
+  data_available_start: 0, data_available_end: 0, default_columns: null, updated: 0, livemode: false,
+});

package/src/engine/products.ts

@@ -0,0 +1,3 @@
+// Product and Price semantics, with the entitlement features granted to a product. Retrieve of a
+// product and the product and price updates (archiving and restoring by `active`, the machines in
+// ../manifest.ts) are the derived core's.

package/src/engine/radar.ts

@@ -0,0 +1,6 @@
+// Radar semantics: reviews of payments Radar held (approving closes one, the machine in
+// ../manifest.ts) and the value lists custom rules reference, with their items. Review list and
+// retrieve, value-list list and retrieve, and value-list-item retrieve are the derived core's.
+
+export const VL = 'radar.value_list';
+export const VLI = 'radar.value_list_item';

package/src/engine/refunds.ts

@@ -0,0 +1,29 @@
+// Refund semantics. A refund always names what it took money out of and lands there: a refund
+// naming nothing, an id nobody minted, or more than the charge has left is refused as Stripe
+// refuses it. The machine in ../manifest.ts says only a refund waiting on the customer
+// (requires_action) may be canceled. List and update are the derived core's.
+//
+// Refunding a destination charge can take back the connected account's share (reverse_transfer: a reversal of the
+// charge's transfer, in proportion to the refund) and the platform's (refund_application_fee: a refund of the
+// application fee, in proportion) (docs.stripe.com/api/refunds/create#create_refund-reverse_transfer,
+// docs.stripe.com/connect/destination-charges#issue-refunds). Where the documentation stops and the twin decides: the
+// twin's destination charge transfers the amount less the fee (the fee is kept back rather than collected from the
+// connected account), so a fee refund moves no money of its own; the reversal and the refund settle both shares.
+//
+// A payment made by bank transfer (from the customer's cash balance) is refunded to the customer's bank account: Stripe
+// emails the customer (instructions_email, else the customer's email) for their bank details and the refund waits in
+// requires_action, moving no money, until they answer; only then can it still be canceled. With origin=customer_balance
+// it goes back to the cash balance at once (docs.stripe.com/payments/customer-balance/refunding,
+// docs.stripe.com/api/refunds/cancel). Where the documentation stops and the twin decides: the customer never answers
+// the email in the World, and its link expires 30 days on.
+//
+// An uncaptured charge holds an authorization, not money. A PaymentIntent's is not refunded: "the charge attached to the
+// PaymentIntent remains uncaptured and can't be refunded directly. You must cancel the PaymentIntent"
+// (docs.stripe.com/refunds), which releases it (charges.ts cancelAuthorization). A charge made with capture=false is
+// released by its refund, as its authorization would be "automatically refunded if uncaptured" (spec/openapi.json.gz,
+// `capture_before`): refunded in full, no balance moved, and its capture refused afterwards. Where the documentation
+// stops and the twin decides: the refusal's code (payment_intent_unexpected_state) and wording, and that a refund of a
+// capture=false charge releases the whole authorization, so an `amount` short of it is refused.
+
+// the reasons a caller may give; `expired_uncaptured_charge` is Stripe's own
+export const REFUND_REASONS = new Set(['duplicate', 'fraudulent', 'requested_by_customer']);

package/src/engine/renewals.ts

@@ -0,0 +1,73 @@
+// A subscription's invoices over time: the first one Checkout pays, and each renewal. Time's moves are made
+// as the twin's trial end already made them: caught up to the customer's clock (the World's, or its test
+// clock) whenever the twin is asked anything (./front.ts), each checked against the machines in
+// ../manifest.ts.
+//
+// - Checkout's subscription session pays the first invoice with the card the customer entered, which becomes the
+//   subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works); nothing is due
+//   on a trial's.
+// - At each period's end Stripe drafts a `subscription_cycle` invoice for the next period and advances the
+//   period; a trial's end is the first such renewal, and the subscription is active from then
+//   (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions,
+//   docs.stripe.com/billing/subscriptions/trials).
+// - About an hour after, Stripe finalizes the draft and charges the subscription's default payment method,
+//   else the customer's (docs.stripe.com/invoicing/integration/workflow-transitions#finalized,
+//   docs.stripe.com/api/subscriptions/object#subscription_object-default_payment_method).
+// - A declined renewal leaves the invoice open with its attempt counted and the subscription past_due
+//   (docs.stripe.com/billing/subscriptions/overview#payment-status); paying the invoice later, through the API
+//   (docs.stripe.com/api/invoices/pay) or on the customer portal (docs.stripe.com/customer-management), makes it
+//   active again.
+//
+// Where the documentation stops and the twin decides: Stripe retries a failed renewal on its Smart Retries
+// schedule and may then cancel or mark the subscription unpaid; the twin makes no retry (next_payment_attempt
+// is null) and leaves it past_due until the invoice is paid. A paused subscription (pause_collection) is not renewed.
+// - One set to cancel at its period's end is canceled when the period ends, with no renewal
+//   (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle).
+import { priceAmount } from './stripe.ts';
+import type { Row } from './common.ts';
+
+export const SUB = 'subscription';
+export const INV = 'invoice';
+export const HOUR = 3600;
+/** The statuses a subscription renews in. */
+export const RENEWING = ['trialing', 'active', 'past_due'];
+
+export const itemsOf = (sub: Row): Row[] => ((sub.items as { data?: Row[] } | undefined)?.data) ?? [];
+
+/** An item's quantity as it bills: 1 when none is set, and 0 when 0 is (a quantity of 0 bills nothing). */
+export function itemQuantity(it: Row): number {
+  return it.quantity === undefined || it.quantity === null ? 1 : Math.max(0, Math.trunc(Number(it.quantity) || 0));
+}
+
+/** The subscription's discounts with a `once` coupon's spent: "When a subscription uses a coupon with `duration=once`, the
+ *  coupon is considered used after the invoice finalizes and is removed from the subscription's `discounts` array"
+ *  (docs.stripe.com/billing/subscriptions/coupons#coupon-duration). */
+export function unspentDiscounts(discounts: unknown): Row[] {
+  return ((discounts as Row[] | undefined) ?? []).filter((d) => !(d && typeof d === 'object' && (d.coupon as Row | undefined)?.duration === 'once'));
+}
+
+/** The coupon ids an invoice's discounts name. */
+export const couponsOf = (discounts: unknown): Set<string> => new Set(((discounts as Row[] | undefined) ?? []).map((d) => {
+  const c = d && typeof d === 'object' ? d.coupon : undefined;
+  return typeof c === 'string' ? c : c && typeof c === 'object' ? String((c as Row).id ?? '') : '';
+}).filter(Boolean));
+
+/** A subscription's discounts after `invoice` finalizes: less the `once` coupons it took. */
+export function keptAfter(discounts: Row[], invoice: Row): Row[] {
+  const taken = couponsOf(invoice.discounts);
+  return discounts.filter((d) => !(unspentDiscounts([d]).length === 0 && [...couponsOf([d])].some((c) => taken.has(c))));
+}
+
+/** A Checkout session's one-time line items as lines of its subscription's first invoice, numbered after its `after` lines. */
+export function oneTimeLines(invoiceId: string, sub: Row, items: Row[], after: number, at: number, currency: string) {
+  return items.map((it, i) => {
+    const price = it.price && typeof it.price === 'object' ? (it.price as Row) : null;
+    const quantity = itemQuantity(it);
+    return {
+      id: `il_twin_${invoiceId}_${after + i + 1}`, object: 'line_item', type: 'subscription',
+      amount: priceAmount(price ?? undefined, quantity), currency, quantity, proration: false,
+      price, subscription: sub.id, subscription_item: null, invoice_item: null,
+      period: { start: at, end: at }, description: typeof it.description === 'string' ? it.description : null,
+    };
+  });
+}

package/src/engine/setup-intents.ts

@@ -0,0 +1,5 @@
+// SetupIntent semantics. The machine in ../manifest.ts says which moves of `status` are legal and
+// what Stripe answers otherwise; these handlers compute what each move does. List, retrieve and
+// update are the derived core's.
+
+export const SI = 'setup_intent';