@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/engine/connect.js

@@ -0,0 +1,108 @@
+// Connect semantics: connected accounts (and the platform's own account), their persons,
+// capabilities, external (payout) accounts, login links, onboarding links and embedded-component
+// sessions. A new connected account is not yet active: charges and payouts are off and its
+// requirements are outstanding, as on Stripe before onboarding. Account retrieve and delete and
+// the person list are the derived core's.
+import { accountRequirements, accountSettings, PLATFORM_ACCOUNT_ID } from "./stripe.js";
+import { currentlyDue, kindOf } from "./onboarding.js";
+import { externalList } from "./common.js";
+// the platform's own account: stored once it is written, otherwise Stripe's default. It "controls itself" (controller
+// type `account`, docs.stripe.com/api/accounts/object), is fully onboarded with nothing due, and takes card payments
+// and transfers. Where the documentation stops and the twin decides: it was created as the World began (2026-01-01),
+// and its bank account, which its automatic payouts reach, is not modelled, so it lists none.
+export const PLATFORM_CREATED = 1_767_225_600;
+/** The platform's own account as Stripe's default has it, before anything is written to it. */
+export const platformAccountDefault = () => ({
+    object: 'account', id: PLATFORM_ACCOUNT_ID, type: 'standard', country: 'US', default_currency: 'usd', created: PLATFORM_CREATED,
+    charges_enabled: true, payouts_enabled: true, details_submitted: true, email: null, metadata: {},
+    capabilities: { card_payments: 'active', transfers: 'active' }, controller: { type: 'account' },
+    requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+    future_requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+    external_accounts: externalList(PLATFORM_ACCOUNT_ID, []), tos_acceptance: { date: null, ip: null, user_agent: null }, business_profile: {},
+    settings: accountSettings(undefined), livemode: false,
+});
+/** A new Express account owes what its hosted onboarding will ask for (screens/connect-onboarding.tsx; the US sets
+ *  docs.stripe.com/connect/required-verification-information lists), or, where the twin does not model the set, the
+ *  generic list. */
+export function expressRequirements(params) {
+    const kind = kindOf({ country: params.country ?? 'US', business_type: params.business_type ?? 'individual' });
+    const base = accountRequirements();
+    return kind ? { ...base, currently_due: currentlyDue(kind), eventually_due: currentlyDue(kind) } : base;
+}
+/** The controller an account made with a `type` has: "Each of the three account types maps to values in the
+ *  `controller` hash", Standard to losses.payments `stripe`, fees.payer `account`, requirement_collection `stripe` and
+ *  a `full` dashboard, Express to `application`, `application_express`, `stripe` and `express`, Custom to
+ *  `application`, `application_custom`, `application` and `none`; each "type": "application", "is_controller": true
+ *  (docs.stripe.com/connect/migrate-to-controller-properties). */
+export function controllerOf(type) {
+    const [losses, payer, collection, dashboard] = type === 'express' ? ['application', 'application_express', 'stripe', 'express']
+        : type === 'custom' ? ['application', 'application_custom', 'application', 'none'] : ['stripe', 'account', 'stripe', 'full'];
+    return { type: 'application', is_controller: true, losses: { payments: losses }, fees: { payer }, requirement_collection: collection, stripe_dashboard: { type: dashboard } };
+}
+/** What a Custom account still owes, from what the platform has given for it, as Stripe's requirements endpoint lists it
+ *  for a US account with no Stripe Dashboard and the full service agreement
+ *  (docs.stripe.com/_endpoint/get-requirements-for-setups, the data behind
+ *  docs.stripe.com/connect/required-verification-information). With transfers alone, a company owes business_profile.url,
+ *  company.name, an external account and tos_acceptance.date and .ip at once (capability_limit_amount -1: paused until
+ *  given) and company.tax_id before $3,000 of payouts (payout_limit_amount 300000); an individual owes the url, its
+ *  first and last name, the bank account and the terms at once, and its date of birth and ssn_last_4 before $3,000 of
+ *  payouts. Requesting card_payments adds business_profile.mcc and the entity's address at once (and an individual's
+ *  email and ssn_last_4). A company with card_payments owes, at once, business_profile.mcc, its address, that its owners
+ *  are provided, each owner's name and email, and its representative's name, email, address, title and ssn_last_4; and
+ *  in time its phone, its statement descriptor and its representative's date of birth and phone (the endpoint's answer
+ *  for US / dashboard none / full terms / company / card_payments and transfers, saved in scratch as
+ *  req-custom-company-cards-transfers.json: capability_limit_amount -1 for the first, none for the second). The
+ *  representative and the owners are the account's persons (relationship.representative, relationship.owner).
+ *  Where the documentation stops and the twin decides: what has no limit, or is owed before $3,000 of payouts, is
+ *  eventually_due and blocks nothing (the twin keeps no payout total against it); an owner field is met when every
+ *  person marked owner has it (none marked: met). */
+export const at_path = (a, path) => path.split('.').reduce((v, k) => (v && typeof v === 'object' ? v[k] : undefined), a);
+export const CARD_COMPANY_NOW = ['business_profile.mcc', 'company.address.line1', 'company.address.city', 'company.address.state', 'company.address.postal_code', 'company.owners_provided', 'owners.first_name', 'owners.last_name', 'owners.email', 'representative.first_name', 'representative.last_name', 'representative.email', 'representative.address.line1', 'representative.address.city', 'representative.address.state', 'representative.address.postal_code', 'representative.relationship.title', 'representative.ssn_last_4'];
+export const CARD_COMPANY_LATER = ['company.phone', 'settings.payments.statement_descriptor', 'representative.dob.day', 'representative.dob.month', 'representative.dob.year', 'representative.phone'];
+export const CARD_INDIVIDUAL_NOW = ['business_profile.mcc', 'individual.address.line1', 'individual.address.city', 'individual.address.state', 'individual.address.postal_code', 'individual.email', 'individual.ssn_last_4'];
+export const personHas = (p, field) => {
+    if (field === 'ssn_last_4')
+        return p.ssn_last_4_provided === true;
+    const v = at_path(p, field);
+    return v !== undefined && v !== null && v !== '';
+};
+export const met = (a, bank, field, persons = []) => {
+    if (field === 'external_account')
+        return bank;
+    if (field.startsWith('representative.')) {
+        const rep = persons.find((p) => p.relationship?.representative === true);
+        return !!rep && personHas(rep, field.slice('representative.'.length));
+    }
+    if (field.startsWith('owners.'))
+        return persons.filter((p) => p.relationship?.owner === true).every((p) => personHas(p, field.slice('owners.'.length)));
+    if (field === 'company.tax_id')
+        return at_path(a, 'company.tax_id_provided') === true;
+    if (field === 'individual.ssn_last_4')
+        return at_path(a, 'individual.ssn_last_4_provided') === true;
+    const v = at_path(a, field);
+    return v !== undefined && v !== null && v !== '';
+};
+export function customRequirements(a, bank, persons = []) {
+    const company = a.business_type === 'company';
+    const cards = Object.keys(a.capabilities ?? {}).includes('card_payments');
+    const now = ['business_profile.url', ...(company ? ['company.name'] : ['individual.first_name', 'individual.last_name']), 'external_account', 'tos_acceptance.date', 'tos_acceptance.ip'];
+    if (cards)
+        now.push(...(company ? CARD_COMPANY_NOW : CARD_INDIVIDUAL_NOW));
+    const later = [...(company ? ['company.tax_id'] : ['individual.dob.day', 'individual.dob.month', 'individual.dob.year', 'individual.ssn_last_4']), ...(cards && company ? CARD_COMPANY_LATER : [])].filter((f) => !now.includes(f));
+    return { now: now.filter((f) => !met(a, bank, f, persons)), later: later.filter((f) => !met(a, bank, f, persons)) };
+}
+/** A request's company or individual as Stripe keeps it: a tax id or SSN given is kept only as provided (the Account
+ *  object answers company.tax_id_provided and individual.ssn_last_4_provided, never the numbers;
+ *  docs.stripe.com/api/accounts/object). */
+export function keptKyc(params) {
+    const out = { ...params };
+    if (params.company && typeof params.company === 'object') {
+        const { tax_id, ...company } = params.company;
+        out.company = { ...company, ...(tax_id !== undefined && tax_id !== '' ? { tax_id_provided: true } : {}) };
+    }
+    if (params.individual && typeof params.individual === 'object') {
+        const { ssn_last_4, id_number, ...individual } = params.individual;
+        out.individual = { ...individual, ...(ssn_last_4 !== undefined && ssn_last_4 !== '' ? { ssn_last_4_provided: true } : {}), ...(id_number !== undefined && id_number !== '' ? { id_number_provided: true } : {}) };
+    }
+    return out;
+}

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

@@ -0,0 +1,4 @@
+import type { Row } from './common.js';
+/** What a new customer answers before any invoice: its invoice_prefix and a next_invoice_sequence of 1, a zero balance,
+ *  no metadata (docs.stripe.com/api/customers/object). */
+export declare const newCustomer: (id: string) => Row;

package/dist/src/engine/customers.js

@@ -0,0 +1,8 @@
+// Customer semantics: the customer and what hangs off it (tax ids, the credit-balance ledger, the
+// cash balance, legacy sources, attached payment methods) and the top-level Source object. List,
+// update and delete of a customer, retrieve of a Source and the flat tax-id list are the derived core's.
+import { invoicePrefix } from "./invoices.js";
+/** What a new customer answers before any invoice: its invoice_prefix and a next_invoice_sequence of 1, a zero balance,
+ *  no metadata (docs.stripe.com/api/customers/object). */
+export const newCustomer = (id) => ({ invoice_prefix: invoicePrefix(id), next_invoice_sequence: 1, balance: 0, metadata: {}, invoice_settings: {} });
+// ── tax ids: a customer's, keyed under it; `type` and `value` are required ──

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

@@ -0,0 +1,11 @@
+type Row = Record<string, any>;
+/** The name an account shows its customers (Checkout, the customer portal): its public business name,
+ *  `business_profile.name` ("The customer-facing business name", docs.stripe.com/api/accounts/object), which the
+ *  operator sets on the Dashboard ("You can change a Checkout page's name by modifying the Business name field",
+ *  docs.stripe.com/payments/checkout/customization/appearance). Where the documentation stops and the twin decides:
+ *  with none set it falls back to the Dashboard's account name, `settings.dashboard.display_name` ("used on the Stripe
+ *  Dashboard to differentiate between accounts", the same object page), and with neither to "Twin Inc.", the name the
+ *  twin has always given the World's own account. */
+export declare const PLATFORM_DEFAULT_NAME = "Twin Inc.";
+export declare function publicBusinessName(account: Row | undefined): string;
+export {};

package/dist/src/engine/display.js

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

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

@@ -0,0 +1,11 @@
+import type { Row } from './common.js';
+export declare const PBC = "billing_portal.configuration";
+/** A portal configuration's features, each filled where the request leaves it: every feature is answered (the served
+ *  spec requires all five), as the create page's example answers a request that sets only customer_update and
+ *  invoice_history: payment_method_update disabled, subscription_cancel disabled at_period_end with proration_behavior
+ *  none and its five default reasons, subscription_update disabled with no allowed updates and proration_behavior none
+ *  (docs.stripe.com/api/customer_portal/configurations/create); trial_update_behavior "Defaults to a value of
+ *  `end_trial` if you don't set it during creation" (the served spec). Where the documentation stops and the twin
+ *  decides: a feature the request leaves out is disabled, and schedule_at_period_end has no conditions. */
+export declare const PORTAL_FEATURES: Row;
+export declare const filled: (base: unknown, given: unknown) => unknown;

package/dist/src/engine/files.js

@@ -0,0 +1,23 @@
+export const PBC = 'billing_portal.configuration';
+/** A portal configuration's features, each filled where the request leaves it: every feature is answered (the served
+ *  spec requires all five), as the create page's example answers a request that sets only customer_update and
+ *  invoice_history: payment_method_update disabled, subscription_cancel disabled at_period_end with proration_behavior
+ *  none and its five default reasons, subscription_update disabled with no allowed updates and proration_behavior none
+ *  (docs.stripe.com/api/customer_portal/configurations/create); trial_update_behavior "Defaults to a value of
+ *  `end_trial` if you don't set it during creation" (the served spec). Where the documentation stops and the twin
+ *  decides: a feature the request leaves out is disabled, and schedule_at_period_end has no conditions. */
+export const PORTAL_FEATURES = {
+    customer_update: { allowed_updates: [], enabled: false },
+    invoice_history: { enabled: false },
+    payment_method_update: { enabled: false, payment_method_configuration: null },
+    subscription_cancel: { cancellation_reason: { enabled: false, options: ['too_expensive', 'missing_features', 'switched_service', 'unused', 'other'] }, enabled: false, mode: 'at_period_end', proration_behavior: 'none' },
+    subscription_update: { default_allowed_updates: [], enabled: false, proration_behavior: 'none', schedule_at_period_end: { conditions: [] }, trial_update_behavior: 'end_trial' },
+};
+export const filled = (base, given) => {
+    if (!given || typeof given !== 'object' || Array.isArray(given) || !base || typeof base !== 'object' || Array.isArray(base))
+        return given === undefined ? base : given;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(given))
+        out[k] = filled(base[k], v);
+    return out;
+};

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

@@ -0,0 +1,21 @@
+import type { Row } from './common.js';
+export declare const INV = "invoice";
+/** Whether leaving draft mints a PaymentIntent: only a charge_automatically invoice with a balance. */
+export declare const collectsThroughIntent: (inv: Row) => boolean;
+export declare const transitions: (inv: Row) => object;
+/** What finalizing assigns: the invoice's `number`, the customer's invoice_prefix and a sequence
+ *  (https://docs.stripe.com/api/invoices/object#invoice_object-number), and for send_invoice a
+ *  `due_date` days_until_due after finalization (#invoice_object-due_date). */
+/** A customer's invoice_prefix, "The prefix for the customer used to generate unique invoice numbers"
+ *  (docs.stripe.com/api/customers/object): the twin's, from the customer's id. */
+export declare const invoicePrefix: (customerId: string) => string;
+/** An invoice's payment as Stripe answers it (docs.stripe.com/api/invoice-payment/object): the PaymentIntent that
+ *  collects the invoice, open until the invoice is paid. Where the documentation stops and the twin decides: an
+ *  invoice has one payment, its default, and the payment's id is the invoice's with `inpay_`. */
+export declare function invoicePayment(inv: Row): Row | undefined;
+export declare const linesOf: (inv: Row) => Row[];
+export declare const sumLines: (lines: Row[]) => number;
+/** Credit the previous price and debit the replacement for the same remaining service time. */
+export declare function prorationLines(before: Row[], after: Row[], time: number, start: number, end: number, coupon: Row | undefined): Row[];
+/** A draft invoice's fields before anything is on it: what a new invoice and a preview start from. */
+export declare const draft: (now: number) => Row;

package/dist/src/engine/invoices.js

@@ -0,0 +1,84 @@
+import { applyCouponDiscount } from "./stripe.js";
+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) => 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 },
+    };
+}
+export const linesOf = (inv) => inv.lines?.data ?? [];
+export const sumLines = (lines) => 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, after, time, start, end, coupon) {
+    const out = [];
+    const discounted = (line, lines) => {
+        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) => typeof line.price === 'object' ? line.price.id : line.price;
+    const append = (line, lines, credit) => {
+        const billingPeriod = line.period;
+        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?.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) => ({
+    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/dist/src/engine/issuing.d.ts

@@ -0,0 +1,33 @@
+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";
+/** 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;
+/** 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 declare function cardNumberOf(drawn: string): string;
+/** A virtual card's CVC, drawn from the World: three digits. */
+export declare const cvcOf: (drawn: string) => string;

package/dist/src/engine/issuing.js

@@ -0,0 +1,54 @@
+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';
+/** 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;
+/** 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) {
+    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) => [...drawn].map((ch) => String(ch.charCodeAt(0) % 10)).join('').padEnd(3, '0').slice(0, 3);

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

@@ -0,0 +1,8 @@
+import type { Row } from './common.js';
+export declare const BT = "balance_transaction";
+/** 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,8 @@
+import { BYPASS_PENDING_CARDS } from "./test-cards.js";
+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) => (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,24 @@
+// 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) => {
+    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 {};