@volter/twin-stripe 2.0.38 → 3.0.0

package/dist/src/engine/invoices.js

@@ -0,0 +1,57 @@
+export const INV = 'invoice';
+export const linesOf = (inv) => inv.lines?.data ?? [];
+export const sumLines = (lines) => 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) {
+    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, subtotal, currency, now, period) {
+    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) => ({
+    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) => inv.status === 'draft' && (Number(inv.amount_due) || 0) > 0;
+export const transitions = (inv) => inv.status_transitions ?? {};
+/** 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) => 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) {
+    if (typeof inv.payment_intent !== 'string')
+        return undefined;
+    const paid = inv.status === 'paid';
+    const transitions = inv.status_transitions ?? {};
+    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/dist/src/engine/issuing.d.ts

@@ -0,0 +1,35 @@
+import type { Row } from './common.js';
+export declare 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 declare const holderId: (c: Row) => string;
+export declare const CARD = "issuing.card";
+export declare const AUTH = "issuing.authorization";
+export declare const TXN = "issuing.transaction";
+export declare const DSP = "issuing.dispute";
+export declare const TOK = "issuing.token";
+export declare 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 declare function historyEntry(o: {
+    amount: number;
+    currency: string;
+    approved: boolean;
+    reason: string;
+    reasonMessage: string | null;
+    createdSec: number;
+    merchantAmount: number;
+    merchantCurrency: string;
+}): Row;
+/** The test helper's default merchant, under any merchant_data the caller gives. */
+export declare function merchantData(param: unknown): Row;
+/** The card's stored id (an embedded card answers with its id). */
+export declare const cardId: (auth: Row) => unknown;
+/** 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 declare 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 declare const PHYSICAL_BUNDLES: Row[];

package/dist/src/engine/issuing.js

@@ -0,0 +1,45 @@
+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) => (typeof c.cardholder === 'string' ? c.cardholder : String(c.cardholder?.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) {
+    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) {
+    const base = {
+        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) => (auth.card && typeof auth.card === 'object' ? auth.card.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 = [
+    { 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/dist/src/engine/ledger.d.ts

@@ -0,0 +1,9 @@
+import type { Row } from './common.js';
+export declare const BT = "balance_transaction";
+export declare const DAY = 86400;
+/** A ledger entry's mark: available at once, its balance.available not yet sent (settleDueEntries). */
+export declare const UNSENT = "_availableUnsent";
+export declare const BYPASS_NUMBERS: Set<string>;
+export declare const feeOf: (amount: number) => number;
+/** Whether a stored ledger entry is on this account's balance (undefined: the platform's). */
+export declare const onAccount: (t: Row, account: string | undefined) => boolean;

package/dist/src/engine/ledger.js

@@ -0,0 +1,9 @@
+import { BYPASS_PENDING_CARDS } from "./test-cards.js";
+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) => (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, account) => (typeof t._account === 'string' ? t._account : undefined) === account;

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

@@ -0,0 +1,4 @@
+/** A key shown the way Stripe's errors show one: its prefix and its last four. */
+export declare const redactKey: (key: string) => string;
+/** The API key a request carries: Bearer, or Basic's user (`curl -u sk_…:`, docs.stripe.com/api/authentication). */
+export declare function requestKey(request: Request): string;

package/dist/src/engine/oauth.js

@@ -0,0 +1,25 @@
+// 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) => {
+    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) {
+    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/dist/src/engine/onboarding.d.ts

@@ -0,0 +1,13 @@
+type Row = Record<string, unknown>;
+export declare const OFFERED: Set<string>;
+export type Form = Record<string, string>;
+export type Kind = 'company' | 'individual';
+export declare const has: (v: Form, k: string) => boolean;
+export declare const dobPart: (v: Form, i: number) => boolean;
+/** Each requirement Stripe names, the form's answer that meets it, and which of the two sets it belongs to. */
+export declare const REQUIREMENTS: Array<[string, (v: Form) => boolean, Kind[]]>;
+/** The set an account onboards against: the two US sets the twin models, or none. */
+export declare function kindOf(account: Row): Kind | undefined;
+/** What an account of this kind still owes, given the form's answers (none: all of it). */
+export declare function currentlyDue(kind: Kind, v?: Form): string[];
+export {};

package/dist/src/engine/onboarding.js

@@ -0,0 +1,42 @@
+// 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.js";
+export const OFFERED = new Set(MCCS.map(([mcc]) => mcc));
+export const has = (v, k) => (v[k] ?? '').trim() !== '';
+export const dobPart = (v, i) => /^\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 = [
+    ['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'].flatMap((f) => [[`representative.${f}`, (v) => has(v, f), ['company']], [`individual.${f}`, (v) => has(v, f), ['individual']]]),
+    ...['day', 'month', 'year'].flatMap((f, i) => [[`representative.dob.${f}`, (v) => dobPart(v, 2 - i), ['company']], [`individual.dob.${f}`, (v) => dobPart(v, 2 - i), ['individual']]]),
+    ...['line1', 'city', 'state', 'postal_code'].flatMap((f) => [[`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) {
+    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, v = {}) {
+    return REQUIREMENTS.filter(([, met, kinds]) => kinds.includes(kind) && !met(v)).map(([req]) => req);
+}

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

@@ -1,8 +1,22 @@
-import { type DerivedCall } from '@volter/world-core';
+type Param = {
+    name: string;
+    required?: boolean;
+};
+type Op = {
+    id: string;
+    method: string;
+    query?: Param[];
+    body?: Param[];
+};
+export declare const OPS: Map<string, Op>;
+/** Parameters Stripe documents outside its published spec, each with the page that documents it. */
+export declare const DOCUMENTED: Record<string, string[]>;
 /** The version that removed payment_method_types from the intents: a caller pinned to it or later is refused. */
 export declare 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 declare const methodTypesRemoved: (pinned: string) => boolean;
+export declare const REMOVED_TYPES: Set<string>;
+export declare const TYPED: Set<string>;
 /** The payment method types there are: the PaymentMethod object's `type` in the served spec. */
 export declare const PAYMENT_METHOD_TYPES: readonly string[];
 /** The payment method types a Checkout Session takes: the vendored spec's (2026-09-30.endive) PostCheckoutSessions
@@ -10,5 +24,8 @@ export declare const PAYMENT_METHOD_TYPES: readonly string[];
  *  payment methods (e.g., `card`) this Checkout Session can accept"). It holds no in-person type (card_present,
  *  interac_present) and no `custom`. The surface keeps no request enums, so it is copied here. */
 export declare const CHECKOUT_METHOD_TYPES: readonly string[];
-/** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
-export declare function refuseParameters(call: DerivedCall): Promise<Response | undefined>;
+/** The create page each intent's refusal links to. */
+export declare const TYPES_DOC: Record<string, string>;
+/** An enum's values as Stripe lists them in a refusal: "a, b, or c". */
+export declare const oneOf: (values: readonly string[]) => string;
+export {};

package/dist/src/{stripe-params.js → engine/params.js}

@@ -9,13 +9,10 @@
 // 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 } from '@volter/world-core';
-import surface from './generated/surface.gen.json' with { type: 'json' };
-import { manifest } from "./manifest.js";
-import { SERVED_VERSION } from "./stripe-version.js";
-const OPS = new Map(surface.operations.map((o) => [o.id, o]));
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+export const OPS = new Map(surface.operations.map((o) => [o.id, o]));
 /** Parameters Stripe documents outside its published spec, each with the page that documents it. */
-const DOCUMENTED = {
+export const DOCUMENTED = {
     // a top-up into the Issuing balance (docs.stripe.com/issuing/funding/balance: "destination_balance=issuing")
     PostTopups: ['destination_balance'],
 };
@@ -45,8 +42,8 @@ const DOCUMENTED = {
 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) => 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']);
 /** The payment method types there are: the PaymentMethod object's `type` in the served spec. */
 export const PAYMENT_METHOD_TYPES = surface.resources.find((r) => r.name === 'payment_method')?.fields.find((f) => f.name === 'type')?.enum ?? [];
 /** The payment method types a Checkout Session takes: the vendored spec's (2026-09-30.endive) PostCheckoutSessions
@@ -55,59 +52,9 @@ export const PAYMENT_METHOD_TYPES = surface.resources.find((r) => r.name === 'pa
  *  interac_present) and no `custom`. The surface keeps no request enums, so it is copied here. */
 export const CHECKOUT_METHOD_TYPES = ['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 = {
+export const TYPES_DOC = {
     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) => (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, given) {
-    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) => 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) {
-    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) => (values.length > 1 ? `${values.slice(0, -1).join(', ')}, or ${values.at(-1)}` : values.join(''));

package/dist/src/engine/payment-intents.d.ts

@@ -0,0 +1,10 @@
+import type { Row } from './common.js';
+export declare 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 declare const TYPES_GIVEN = "_payment_intent_types_given";
+/** 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 declare function intentCarries(pi: Row): Row;

package/dist/src/engine/payment-intents.js

@@ -0,0 +1,27 @@
+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) {
+    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 } } : {}),
+    };
+}

package/dist/src/engine/payment-links.d.ts

@@ -0,0 +1 @@
+export declare const PL = "payment_link";

package/dist/src/engine/payment-links.js

@@ -0,0 +1,5 @@
+// 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/dist/src/engine/payment-methods.d.ts

@@ -0,0 +1,16 @@
+import type { Row } from './common.js';
+export declare const PM = "payment_method";
+export declare const noBilling: {
+    address: null;
+    email: null;
+    name: null;
+    phone: null;
+};
+export declare const TEST_PM_CARDS: Record<string, {
+    brand: string;
+    number: string;
+}>;
+/** 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 declare function testCardOf(ref: string): Row | undefined;

package/dist/src/engine/payment-methods.js

@@ -0,0 +1,22 @@
+// 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.js";
+import { AFTER_SUCCESS_CARDS } from "./after-payment.js";
+export const PM = 'payment_method';
+export const noBilling = { address: null, email: null, name: null, phone: null };
+export const TEST_PM_CARDS = {
+    ...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) {
+    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, brand: test.brand };
+}

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

@@ -0,0 +1,6 @@
+import type { Row } from './common.js';
+export declare const INTERVALS: Set<string>;
+/** A recurring price in the plan object's shape (the create page's example response). */
+export declare function planOf(price: Row): Row;
+/** Metadata after an update: an empty value unsets the key, an empty `metadata` unsets them all. */
+export declare function metadataAfter(was: Row, given: unknown): Row;

package/dist/src/engine/plans.js

@@ -0,0 +1,26 @@
+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) {
+    const r = (price.recurring ?? {});
+    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, given) {
+    if (given === '' || given === null || typeof given !== 'object')
+        return {};
+    const next = { ...was };
+    for (const [k, v] of Object.entries(given))
+        if (v === '' || v === null)
+            delete next[k];
+        else
+            next[k] = v;
+    return next;
+}

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

@@ -0,0 +1,39 @@
+import type { Row } from './common.js';
+export declare const CLIMATE_SUPPLIERS: readonly [{
+    readonly id: "climsup_charm_industrial";
+    readonly name: "Charm Industrial";
+    readonly removal_pathway: "biomass_carbon_removal_and_storage";
+    readonly info_url: "https://frontierclimate.com/portfolio/charm-industrial";
+    readonly locations: readonly [{
+        readonly city: "San Francisco";
+        readonly country: "US";
+        readonly latitude: 37.7749;
+        readonly longitude: -122.4194;
+        readonly region: "CA";
+    }];
+}];
+export declare const CLIMATE_PRODUCTS: readonly [{
+    readonly id: "climsku_frontier_offtake_portfolio_2027";
+    readonly name: "Frontier's 2027 offtake portfolio";
+    readonly subtotal: 55000;
+    readonly fees: 1650;
+    readonly currency: "usd";
+    readonly delivery_year: 2027;
+    readonly metric_tons_available: "18000";
+    readonly created: 1881439203;
+    readonly suppliers: readonly ["climsup_charm_industrial"];
+}];
+export declare const supplierView: (s: (typeof CLIMATE_SUPPLIERS)[number]) => Row;
+export declare const productView: (p: (typeof CLIMATE_PRODUCTS)[number]) => Row;
+export declare const ORDER = "climate.order";
+export declare const FCS = "financial_connections.session";
+export declare const FCA = "financial_connections.account";
+export declare const FCT = "financial_connections.transaction";
+export declare const REPORT_TYPES: Array<{
+    id: string;
+    name: string;
+}>;
+export declare const reportTypeView: (t: {
+    id: string;
+    name: string;
+}) => Row;

package/dist/src/engine/platform.js

@@ -0,0 +1,34 @@
+// ── 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' }] },
+];
+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'] },
+];
+export const supplierView = (s) => ({ 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) => ({
+    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 = [
+    { 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: 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/dist/src/engine/products.js

@@ -0,0 +1,4 @@
+"use strict";
+// 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/dist/src/engine/radar.d.ts

@@ -0,0 +1,2 @@
+export declare const VL = "radar.value_list";
+export declare const VLI = "radar.value_list_item";

package/dist/src/engine/radar.js

@@ -0,0 +1,5 @@
+// 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/dist/src/engine/refunds.d.ts

@@ -0,0 +1 @@
+export declare const REFUND_REASONS: Set<string>;