@volter/twin-stripe 2.0.38 → 3.0.1

package/src/engine/display.ts

@@ -0,0 +1,18 @@
+// What Stripe's pages show of an account, and where its Connect OAuth connections are kept.
+
+// 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.';
+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/files.ts

@@ -0,0 +1,28 @@
+// 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';
+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/invoices.ts

@@ -0,0 +1,102 @@
+// 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';
+import { applyCouponDiscount } from './stripe.ts';
+
+export const INV = 'invoice';
+
+/** 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 },
+  };
+}
+
+
+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);
+
+
+
+/** Credit the previous price and debit the replacement for the same remaining service time. */
+// source: https://docs.stripe.com/billing/subscriptions/prorations "Unused time on original 10 USD plan (credit)"
+// source: https://docs.stripe.com/billing/subscriptions/prorations "Remaining time on new 20 USD plan (debit)"
+// source: https://docs.stripe.com/billing/subscriptions/prorations "The current billing period’s start and end times are used to calculate the cost of the subscription before and after the change."
+// source: https://docs.stripe.com/billing/subscriptions/prorations "By default, Stripe calculates prorations down to the second."
+export function prorationLines(before: Row[], after: Row[], time: number, start: number, end: number, coupon: Row | undefined): Row[] {
+  const out: Row[] = [];
+  const discounted = (line: Row, lines: Row[]): number => {
+    const total = sumLines(lines);
+    // source: https://docs.stripe.com/billing/subscriptions/prorations "When calculating proration credits or debits, Stripe uses the subscription’s discounted price, not the original price."
+    return Number(line.amount) - (total > 0 ? applyCouponDiscount(total, coupon) * Number(line.amount) / total : 0);
+  };
+  const priceId = (line: Row): unknown => typeof line.price === 'object' ? (line.price as Row).id : line.price;
+  const append = (line: Row, lines: Row[], credit: boolean): void => {
+    const billingPeriod = line.period as Row;
+    const periodStart = Number(billingPeriod.start ?? start), periodEnd = Number(billingPeriod.end ?? end);
+    const fraction = Math.max(0, Math.min(1, (periodEnd - time) / Math.max(1, periodEnd - periodStart)));
+    const amount = Math.round(discounted(line, lines) * fraction) * (credit ? -1 : 1);
+    if (!amount) return;
+    out.push({ ...line, id: `${line.id}_${credit ? 'unused' : 'remaining'}`, amount, proration: true, discountable: false,
+      period: { start: time, end: periodEnd }, description: `${credit ? 'Unused' : 'Remaining'} time on ${String((line.price as Row)?.nickname ?? priceId(line))}` });
+  };
+  for (const old of before) {
+    const replacement = after.find(line => line.subscription_item === old.subscription_item);
+    if (replacement && priceId(replacement) === priceId(old) && replacement.quantity === old.quantity) continue;
+    append(old, before, true);
+  }
+  for (const next of after) {
+    const previous = before.find(line => line.subscription_item && line.subscription_item === next.subscription_item);
+    if (previous && priceId(previous) === priceId(next) && previous.quantity === next.quantity) continue;
+    append(next, after, false);
+  }
+  return out;
+}
+
+
+
+// ── 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,
+});

package/src/engine/issuing.ts

@@ -0,0 +1,66 @@
+// 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';
+
+/** 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;
+
+/** A virtual card's number, drawn from the World: a 16-digit Visa number ("The brand of the card": the twin issues
+ *  Visa) whose last digit is the Luhn check digit every card number carries. Where the documentation stops and the twin
+ *  decides: the digits are the World's draw, Stripe's are the issuer's. */
+export function cardNumberOf(drawn: string): string {
+  const body = `4${[...drawn].map((ch) => String(ch.charCodeAt(0) % 10)).join('').padEnd(14, '0').slice(0, 14)}`;
+  let sum = 0;
+  for (let i = 0; i < body.length; i++) {
+    let d = Number(body[body.length - 1 - i]);
+    if (i % 2 === 0) { d *= 2; if (d > 9) d -= 9; }
+    sum += d;
+  }
+  return `${body}${(10 - (sum % 10)) % 10}`;
+}
+
+/** A virtual card's CVC, drawn from the World: three digits. */
+export const cvcOf = (drawn: string): string => [...drawn].map((ch) => String(ch.charCodeAt(0) % 10)).join('').padEnd(3, '0').slice(0, 3);

package/src/engine/ledger.ts

@@ -0,0 +1,48 @@
+// 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';
+/** 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,18 @@
+// Stripe API key parsing and error redaction, from the API authentication documentation.
+
+/** 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 '';
+}

package/src/engine/onboarding.ts

@@ -0,0 +1,53 @@
+// 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,14 @@
 // 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 +47,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 +58,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,32 @@
+// 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-methods.ts

@@ -0,0 +1,24 @@
+// 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/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,3 @@
+// The published refund reasons; expired_uncaptured_charge is Stripe's own, not a request reason.
+// source: spec:/paths/~1v1~1refunds/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/reason "String indicating the reason for the refund."
+export const REFUND_REASONS = new Set(['duplicate', 'fraudulent', 'requested_by_customer']);

package/src/engine/renewals.ts

@@ -0,0 +1,72 @@
+// 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,
+    };
+  });
+}