@volter/twin-stripe 2.0.37 → 3.0.0

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

@@ -1,23 +1,14 @@
-// Stripe twin REQUEST HANDLER — the canonical Stripe API surface for the twin and
-// the QA stack's authoritative Stripe (it replaced the old hand-made in-process
-// mock). Contract: handleStripeTwinRequest({method, path, body, mode}) -> {status,
-// body}. The whole point: this is backed by the event/action-log kernel and its
-// response SHAPES are conformant to real Stripe (see stripe-conformance), instead
-// of being invented — so the SDK/API call shapes the app relies on actually match
-// Stripe. HTTP wrapper: stripe-server.ts → createStripeTwinServer.
-//
-// State lives in the action log (R18): writes are local actions, reads are the
-// projection. No real Stripe is ever called.
-import { applyTwinWrite } from '@volter/world-core';
-import { projectResources } from '@volter/world-core';
-import { createStripeTwinFetch } from "./stripe-server.js";
-import { emitStripeEvent, eventTypeFor } from "./stripe-events.js";
-import { SERVED_VERSION } from "./stripe-version.js";
-import { planOf } from "./semantics/plans.js";
-import { platformAccountDefault } from "./semantics/connect.js";
-import { OAUTH_CONNECTIONS } from "./stripe-shared.js";
-const SERVICE = 'stripe';
-// The Stripe API version a request that pins none is served in: the vendored spec's (stripe-version.ts renders
+// Stripe's own computation that its handlers share (docs/contributing/architecture.md, "Pack layout": the engine): money
+// and its declines, 3-D Secure and micro-deposits, the list page and the search grammar, a subscription's items, billing
+// intervals and discounts, Issuing's spending controls, a payment method's sub-object, a Connect account's settings and a
+// Checkout Session's line items. None of it reads or writes state: a caller hands it what it looked up (FindStored).
+import { ownFields } from '@volter/world-core';
+import { SERVED_VERSION } from "./version.js";
+/** Stripe's error body: an invalid_request_error with the message, and the code when there is one. */
+export function err(message, status = 404, code) {
+    return { status, body: { error: { type: 'invalid_request_error', message, ...(code ? { code } : {}) } } };
+}
+// The Stripe API version a request that pins none is served in: the vendored spec's (./version.ts renders
 // every answer in it). A request may override it via the `Stripe-Version` header (apiVersion);
 // the value is echoed onto every event the request produces, exactly like real Stripe,
 // whose stored Event.api_version reflects the version in force when the event was created.
@@ -28,61 +19,6 @@ const API_VERSION_RE = /^\d{4}-\d{2}-\d{2}(\.[a-z_]+)?$/;
 export function isValidApiVersion(v) {
     return API_VERSION_RE.test(v);
 }
-// resource type → id prefix (Stripe's conventions).
-const PREFIX = {
-    charge: 'ch', customer: 'cus', payment_intent: 'pi', setup_intent: 'seti', payment_method: 'pm',
-    subscription: 'sub', price: 'price', product: 'prod', invoice: 'in', invoiceitem: 'ii',
-    refund: 're', verification_session: 'vs', ephemeral_key: 'ephkey', file_link: 'link',
-    dispute: 'dp', payout: 'po', balance_transaction: 'txn', event: 'evt',
-    checkout_session: 'cs', billing_portal_session: 'bps', billing_portal_configuration: 'bpc',
-    account: 'acct', transfer: 'tr',
-    tax_rate: 'txr', tax_calculation: 'taxcalc', tax_registration: 'taxreg',
-    credit_note: 'cn', tax_id: 'txi', customer_balance_transaction: 'cbtxn',
-    coupon: 'coupon', promotion_code: 'promo', payment_link: 'plink', quote: 'qt',
-    webhook_endpoint: 'we',
-    subscription_schedule: 'sub_sched', billing_meter: 'mtr', billing_meter_event: 'mtr_evt',
-    usage_record: 'mbur', test_clock: 'clock',
-    token: 'tok', mandate: 'mandate', application_fee: 'fee', fee_refund: 'fr',
-    transfer_reversal: 'trr', account_link: 'acctlink', person: 'person',
-    external_account: 'ba', file: 'file',
-    subscription_item: 'si', tax_transaction: 'tax', radar_review: 'prv',
-    radar_value_list: 'rsl', radar_value_list_item: 'rsli', radar_rule: 'rule',
-    // Issuing family (vendor-faithful Stripe id prefixes).
-    issuing_cardholder: 'ich', issuing_card: 'ic', issuing_authorization: 'iauth',
-    issuing_transaction: 'ipi', issuing_dispute: 'idp',
-    // Terminal family.
-    terminal_location: 'tml', terminal_reader: 'tmr', terminal_configuration: 'tmc',
-    // Top-ups, identity reports, reporting runs.
-    topup: 'tu', verification_report: 'vr', report_run: 'frr',
-    // Customer cash balance ledger + legacy sources.
-    cash_balance_transaction: 'ccsbtxn', source: 'src',
-    // Billing: prepaid credit grants + usage alerts.
-    credit_grant: 'credgr', billing_alert: 'alert',
-    // Entitlements: account-level features + per-customer active entitlements.
-    entitlements_feature: 'feat', active_entitlement: 'ent',
-    // Connect: embedded account sessions + apps secret store.
-    account_session: 'accts', apps_secret: 'apmc',
-    // Issuing: network tokens + card personalization designs.
-    issuing_token: 'iss_tok', personalization_design: 'pd',
-    // Treasury: financial accounts + money-movement flows + ledger.
-    financial_account: 'fa',
-    outbound_payment: 'obp', outbound_transfer: 'obt', inbound_transfer: 'ibt',
-    received_credit: 'rc', received_debit: 'rd',
-    treasury_transaction: 'trxn', treasury_transaction_entry: 'trxne',
-    // Climate (carbon removal): orders. (products/suppliers are a fixed read-only catalog.)
-    climate_order: 'climorder',
-    // Financial Connections: sessions + linked accounts + account transactions.
-    fc_session: 'fcsess', fc_account: 'fca', fc_transaction: 'fctxn',
-    // Forwarding (PAN forwarding) requests + Crypto onramp sessions.
-    forwarding_request: 'fwdr', onramp_session: 'cos',
-    // Entitlements: a product↔feature grant.
-    product_feature: 'prodft',
-    // Tax settings singleton.
-    tax_settings: 'taxset',
-};
-function err(message, status = 404, code) {
-    return { status, body: { error: { type: status === 404 ? 'invalid_request_error' : 'invalid_request_error', message, ...(code ? { code } : {}) } } };
-}
 // Fidelity: real Stripe rejects a charge/payment_intent missing or with a non-positive
 // amount, or missing currency, before any state change.
 export function validateMoney(params) {
@@ -270,19 +206,6 @@ export function cardError(outcome, attach = {}) {
 export function nowUnix(occurredAt) {
     return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
 }
-function rows(type, root) {
-    return projectResources(SERVICE, root).filter((r) => r.type === type);
-}
-function nextId(type, root) {
-    const prefix = PREFIX[type] ?? type;
-    let max = 0;
-    for (const r of rows(type, root)) {
-        const m = new RegExp(`^${prefix}_twin_(\\d+)$`).exec(r.id);
-        if (m)
-            max = Math.max(max, Number(m[1]));
-    }
-    return `${prefix}_twin_${max + 1}`;
-}
 // Real Stripe embeds the resource's OWN id inside its client_secret (format
 // `<id>_secret_<random>`) — Stripe.js's confirmPayment/confirmSetup parse the id back
 // out of the client_secret (splitting on `_secret`) to build the same-origin confirm
@@ -290,25 +213,14 @@ function nextId(type, root) {
 // A secret that doesn't carry the real id breaks that round trip: a browser Stripe.js
 // call would try to confirm a resource whose id it invented from the string
 // (`'pi_twin_secret'` → `'pi_twin'`, which was never actually created). Every PI/SI a
-// caller might confirm CLIENT-SIDE (real Stripe.js — see the QA proxy's browserRouting
-// in packages/twin/stripe/src/index.ts) must mint a secret this way.
-export function mintClientSecret(id) {
-    return `${id}_secret_twin`;
-}
-// Stripe resource view: inject `object` + `id`, drop kernel meta.
-//
-// The kernel reserves the field name `type` as its resource-type discriminator, so a
-// stored vendor field literally named `type` is dropped on projection (see actions.ts
-// META). Several Stripe objects (payout.type, balance_transaction.type, event.type,
-// dispute uses `reason` not `type`) DO have a vendor `type`, so the create path stashes
-// it under the reserved key `_stripe_type` (a `_`-prefixed twin-internal field that the
-// conformance gate exempts) and we restore it to `type` here. This keeps the vendor
-// field faithful without touching the kernel discriminator. (price.type stays a declared
-// deviation — its create path predates this and one_time/recurring is derivable.)
-// A few Stripe objects have a DOTTED `object` value that differs from the twin's
-// (identifier-safe) resource type — e.g. type 'checkout_session' emits object
-// 'checkout.session'. Map them on emit so the `object` field is vendor-faithful.
-// (stripe-conformance.ts emitted() mirrors this map.)
+// caller might confirm CLIENT-SIDE (real Stripe.js) must mint a secret this way.
+/** An intent's client secret: its id, `_secret_`, and a secret the World holds for it (ctx.secret, passed in), so no one
+ *  derives it from the intent's id; Stripe.js confirms an intent with it and the publishable key. */
+export function mintClientSecret(id, secret) {
+    return `${id}_secret_${secret.replace(/[^A-Za-z0-9]/g, '').slice(0, 24)}`;
+}
+// A few Stripe objects have a DOTTED `object` value that differs from the twin's (identifier-safe) resource type: type
+// 'checkout_session' is object 'checkout.session'.
 export const OBJECT_NAME = {
     checkout_session: 'checkout.session',
     billing_portal_session: 'billing_portal.session',
@@ -369,18 +281,11 @@ export const OBJECT_NAME = {
     // Forwarding + Crypto onramp.
     forwarding_request: 'forwarding.request', onramp_session: 'crypto.onramp_session',
 };
-// Exported for the pack's own modules that must render the SAME vendor view of a stored
-// resource (stripe-emit.ts synthesizes `data.object` for emitted events from it) — one
-// projection, no drift. Not a public API for consumers.
+/** A stored row as Stripe answers it: its `object`, its own fields (the vendor's `type` among them, which the tree's
+ *  shadows: world-core ownFields) without the twin's `_` bookkeeping, and its id. */
 export function view(type, r) {
-    // `_subscription_data` is twin-internal (a Checkout Session's create-only
-    // subscription_data, held for the completion transition to copy onto the created
-    // subscription) — real Stripe never returns it on the Session, so strip it here.
-    const { type: _t, updatedAt: _u, _stripe_type, _subscription_data, ...rest } = r;
-    const out = { object: OBJECT_NAME[type] ?? type, ...rest, id: r.id };
-    if (_stripe_type !== undefined)
-        out.type = _stripe_type;
-    return out;
+    const own = Object.fromEntries(Object.entries(ownFields(r)).filter(([k]) => !k.startsWith('_') && k !== 'updatedAt'));
+    return { object: OBJECT_NAME[type] ?? type, ...own, id: r.id };
 }
 // Real Stripe list pagination. Honors limit (default 10, max 100, min 1),
 // starting_after (cursor: exclude up to & including that id), ending_before
@@ -414,90 +319,6 @@ export function paginate(items, params) {
     const page = items.slice(from, from + limit);
     return { page, hasMore: from + limit < items.length };
 }
-async function writeResource(type, id, fields, op, root, occurredAt, apiVersion) {
-    const { resource } = await applyTwinWrite(SERVICE, { operation: op, subjectType: type, subjectId: id, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
-    const out = view(type, resource);
-    await afterStripeWrite(type, op, out, root, occurredAt, apiVersion);
-    return out;
-}
-/** What follows every stored Stripe write: the webhook for the state change and the stored Event
- *  the Events API lists. The derived pack's write hook (manifest.ts) is this same function. */
-export async function afterStripeWrite(type, op, out, root, occurredAt, apiVersion, stripeAccount) {
-    // R17: fire the Stripe event/webhook for this state change (no-op if none registered). An event is a connected
-    // account's when its resource lives in one (a request made as it, the Stripe-Account header) or is a connected
-    // account itself (its account.updated): docs.stripe.com/connect/webhooks, "Connected accounts" scope.
-    // A write with no header is still a connected account's when the row it wrote is kept on that account's books (a
-    // payout or ledger entry's `_account`: an automatic payout time makes for it, semantics/balance.ts).
-    const account = stripeAccount ?? (type === 'account' && typeof out.id === 'string' && out.id !== PLATFORM_ACCOUNT_ID ? out.id : undefined) ?? ownerOf(type, out.id, root);
-    // a plan is stored as the recurring price it is; its own events carry the plan object (semantics/plans.ts)
-    const object = type === 'price' && op.startsWith('plan.') ? planOf(out) : out;
-    // events.full_types: the Stripe `event` envelope for this state change is also stored, so it appears in GET
-    // /v1/events (independent of webhook registration), exactly like real Stripe's stored Events API. Skip when the op
-    // has no mapped event type, and never for event/_idempotency writes themselves (no recursion / no meta-events). The
-    // event's id is minted once and is the delivered webhook's id and the stored event's alike: one event, one id, which
-    // a consumer deduplicates by and retrieves by.
-    const eventType = type !== 'event' && type !== IDEMPOTENCY_TYPE ? eventTypeFor(op) : null;
-    const id = eventType ? nextStripeEventId(root) : undefined;
-    // stored before it is delivered: a consumer that looks its webhook's event up finds it
-    if (eventType)
-        await persistStripeEvent(eventType, object, root, occurredAt, apiVersion, account, id);
-    // a connected account whose OAuth connection was revoked "can't be accessed by your platform" (docs.stripe.com/connect/
-    // oauth-reference): its events (a payout time makes, a renewal) are its own and no longer reach the platform's Connect
-    // endpoints, except the account.application.deauthorized that says so (screens/connect-oauth.tsx)
-    if (account && eventType !== 'account.application.deauthorized' && rows(OAUTH_CONNECTIONS, root).some((c) => c.id === account && c.revoked === true))
-        return;
-    await emitStripeEvent(op, object, { occurredAt: occurredAt ?? '1970-01-01T00:00:00.000Z', endpoints: webhookTargets(root), ...(account ? { account } : {}), ...(id ? { id } : {}) });
-}
-/** Event numbers taken in this process, per root, before their events are stored: two writes whose events overlap
- *  (a webhook handler calling back in, concurrent requests) never take the same number. */
-const takenEventNumbers = new Map();
-/** The id the World's next event takes: its place in the World's events, so it is deterministic and never repeats
- *  within a World (a Balance has no id of its own, so nothing about the object can tell two events apart). The number
- *  is taken synchronously — the count of stored events, or the last number taken, whichever is higher. */
-export function nextStripeEventId(root) {
-    const key = root ?? '';
-    const n = Math.max(rows('event', root).length, takenEventNumbers.get(key) ?? 0) + 1;
-    takenEventNumbers.set(key, n);
-    return `evt_twin_${n}`;
-}
-/** The connected account whose books a stored row is kept on (its `_account`), if any. */
-function ownerOf(type, id, root) {
-    if (typeof id !== 'string')
-        return undefined;
-    const owner = rows(type, root).find((r) => r.id === id)?._account;
-    return typeof owner === 'string' ? owner : undefined;
-}
-// Persist a Stripe `event` resource (object 'event') for a state change into the action
-// log so the Events API (GET /v1/events) lists/retrieves it. Deterministic id derived
-// from the per-root event count; data.object carries the resource snapshot. Written via
-// applyTwinWrite directly (NOT writeResource) to avoid re-emitting an event for the event.
-export async function persistStripeEvent(eventType, resource, root, occurredAt, apiVersion, account, id) {
-    const eventId = id ?? nextStripeEventId(root);
-    const fields = {
-        object: 'event', _stripe_type: eventType, created: nowUnix(occurredAt), livemode: false,
-        pending_webhooks: 0, api_version: apiVersion && isValidApiVersion(apiVersion) ? apiVersion : TWIN_API_VERSION,
-        request: { id: null, idempotency_key: null },
-        data: { object: resource },
-        // a connected account's event names it, and is listed to requests made as it (semantics/webhook-endpoints.ts)
-        ...(account ? { account } : {}),
-    };
-    await applyTwinWrite(SERVICE, { operation: 'event.record', subjectType: 'event', subjectId: eventId, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'system' } }, root);
-}
-function getOne(type, id, root) {
-    const r = rows(type, root).find((x) => x.id === id);
-    return r ? view(type, r) : undefined;
-}
-// Stripe list order: newest first by `created` (or `date` for invoiceitem), ties
-// broken by id descending so the order is stable for cursor pagination.
-/** The World's live webhook endpoints, from its tree: delivery survives a restart and belongs to
- *  this World alone. A disabled or deleted endpoint receives nothing, like the vendor. */
-function webhookTargets(root) {
-    // `connect` is a create parameter the endpoint object does not answer, so it is read off the stored row
-    return rows('webhook_endpoint', root)
-        .map((r) => ({ w: view('webhook_endpoint', r), connect: asBool(r.connect) }))
-        .filter(({ w }) => !w.deleted && w.status !== 'disabled' && typeof w.url === 'string')
-        .map(({ w, connect }) => ({ url: String(w.url), ...(typeof w.secret === 'string' ? { secret: w.secret } : {}), ...(Array.isArray(w.enabled_events) ? { enabledEvents: w.enabled_events.map(String) } : {}), connect }));
-}
 // Stripe's `active=true|false` filters arrive as strings/booleans; normalize.
 export function asBool(v) {
     return v === true || v === 'true' || v === 1 || v === '1';
@@ -748,35 +569,15 @@ export function resolveTrial(params, at) {
     }
     return undefined;
 }
-// Create a resource from form params, stamping object + id + created + the given
-// defaults. Only real Stripe field names are emitted (conformance-checked).
-// A vendor `type` field (a price's one_time or recurring, a payout's bank_account) always collides with the kernel's
-// row type, so it is stashed under `_stripe_type` and restored by view().
-export function stashVendorType(_type, fields) {
-    if (!('type' in fields))
-        return fields;
-    const { type: vt, ...rest } = fields;
-    return { ...rest, _stripe_type: vt };
-}
-async function create(type, params, defaults, req, opts = {}) {
-    // honor a caller-provided id (seeding uses the catalog's real prod_*/price_* ids);
-    // otherwise assign one. The id is identity, not a stored field.
-    const { id: providedId, ...rest } = params;
-    const id = typeof providedId === 'string' && providedId ? providedId : nextId(type, req.root);
-    // Most Stripe objects stamp `created`; a few (invoiceitem) use a differently-named
-    // timestamp instead (`date`) and have NO `created` field — honor that, don't fabricate.
-    const fields = stashVendorType(type, { object: OBJECT_NAME[type] ?? type, [opts.timeField ?? 'created']: nowUnix(req.occurredAt), ...defaults, ...rest });
-    return { status: 200, body: await writeResource(type, id, fields, `${type}.create`, req.root, req.occurredAt, req.apiVersion) };
-}
 // ── ISSUING helpers: spending controls, real-time-auth shapes ─────────────────────────
 // Authorization.card is the FULL Card object in every vendor egress (API responses and
 // webhook payloads) — it is not expandable (stripe@22.3.0 Issuing.Authorization.card:
 // Stripe.Issuing.Card). The twin stores the id internally and embeds at the boundary;
 // cardholder stays an id string (expandable, unexpanded default). Caught live: the
 // issuing-bridge reads event.data.object.card.id and refused every twin presentment.
-export function embedIssuingAuthorizationCard(body, root) {
+export function embedIssuingAuthorizationCard(body, find) {
     if (typeof body.card === 'string') {
-        const cardRow = getOne('issuing_card', body.card, root);
+        const cardRow = find('issuing_card', body.card);
         if (cardRow !== undefined)
             body.card = cardRow;
     }
@@ -1121,18 +922,6 @@ export function lineItemEntries(params) {
     const li = params.line_items;
     return Array.isArray(li) ? li.filter((x) => x && typeof x === 'object') : [];
 }
-// ---- IDEMPOTENCY KEYS (vendor-faithful) ----
-// Real Stripe honors the `Idempotency-Key` header on POST: the first request with a
-// key executes and the (status + body) response is stored against the key; a replay
-// with the SAME key returns the SAME stored response WITHOUT re-applying the write.
-// We persist the stored response as an `_idempotency` resource in the action log
-// (per-root, so a fork has its own keyspace). `_idempotency` is a twin-internal type
-// (never served as a Stripe object), so it does not affect spec conformance.
-//
-// Note: real Stripe only persists idempotency for responses it considers "completed"
-// (2xx and most 4xx, including card 402s) and scopes the key to the account; here we
-// store every executed POST response (success and error alike), keyed per-root.
-const IDEMPOTENCY_TYPE = '_idempotency';
 // ── THE MONEY MODEL: a charge and the refunds taken out of it ──────────────────────────
 //
 // The rule this section exists to hold: A FACT RECORDED ON ONE MONEY OBJECT IS VISIBLE FROM
@@ -1154,79 +943,5 @@ export function chargeDefaults(chargeId, amount, captured, occurredAt) {
         billing_details: { address: null, email: null, name: null, phone: null }, livemode: false,
     };
 }
-/**
- * Public entry: honors the Idempotency-Key (replay → stored response, no re-write)
- * then delegates to the router. Only POSTs are idempotent (matches Stripe; GET/DELETE
- * pass straight through). A read-only twin never stores (it cannot write).
- */
-/** Stripe's API as one call: the request goes through the pack's own dispatch (the derived dispatch over
- *  its semantics, its derived core and the hand-written routes below), so a caller that holds no
- *  HTTP server reaches exactly what an SDK does. `occurredAt` pins the World instant. */
-export async function handleStripeTwinRequest(req) {
-    const twin = createStripeTwinFetch({ ...(req.root !== undefined ? { root: req.root } : {}), readOnly: req.readOnly ?? false, ...(req.occurredAt ? { clock: () => req.occurredAt } : {}) });
-    const method = req.method.toUpperCase();
-    const headers = { 'content-type': 'application/x-www-form-urlencoded' };
-    if (req.idempotencyKey)
-        headers['idempotency-key'] = req.idempotencyKey;
-    if (req.apiVersion !== undefined)
-        headers['stripe-version'] = req.apiVersion;
-    if (req.stripeAccount)
-        headers['stripe-account'] = req.stripeAccount;
-    // a GET carries its parameters in the query; a caller that handed them as a body keeps them
-    let path = req.path.startsWith('/') ? req.path : `/${req.path}`;
-    if ((method === 'GET' || method === 'HEAD') && req.body)
-        path += (path.includes('?') ? '&' : '?') + req.body;
-    const response = await twin(new Request(`http://stripe.test${path}`, { method, headers, ...(method !== 'GET' && method !== 'HEAD' && req.body ? { body: req.body } : {}) }));
-    const text = await response.text();
-    return { status: response.status, body: text ? JSON.parse(text) : null };
-}
-/**
- * The twin's doors: what stands in for an act Stripe's API does not have, each under `/_twin/`. The
- * platform's own account settings (its payout schedule) change on Stripe's Dashboard, which has no API:
- * POST /_twin/account stands in for that page. Answers nothing for any other path.
- */
-export async function handleStripeDoor(req, params) {
-    const method = req.method.toUpperCase();
-    const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
-    const seg = path.replace(/^\/+/, '').split('/');
-    if (seg[0] !== '_twin')
-        return undefined;
-    if (req.readOnly)
-        return err('twin is read-only; omit readOnly to accept writes', 405);
-    if (path === '/_twin/account' && method === 'POST') {
-        const ex = getOne('account', PLATFORM_ACCOUNT_ID, req.root);
-        const { type: _t, settings: rawSettings, business_profile: rawProfile, ...rest } = params;
-        // the platform's account is Stripe's default until the page first changes it (semantics/connect.ts, the same
-        // default GET /v1/account answers and the Public details page stores)
-        const fields = {
-            ...(ex ? {} : (({ id: _id, ...base }) => base)(platformAccountDefault())),
-            ...rest,
-            settings: accountSettings(rawSettings, ex?.settings),
-            // a hash is merged into what the account holds, as an update merges it (the name the Public details page saved stays)
-            ...(rawProfile && typeof rawProfile === 'object' ? { business_profile: { ...(ex?.business_profile ?? {}), ...rawProfile } } : {}),
-        };
-        return { status: 200, body: await writeResource('account', PLATFORM_ACCOUNT_ID, stashVendorType('account', fields), 'account.update', req.root, req.occurredAt) };
-    }
-    // Issuing network tokens are minted by the card network when a cardholder adds the card to a
-    // phone's wallet (docs.stripe.com/issuing/cards/digital-wallets): there is no API create, and the
-    // act happens in the phone's wallet app, not on a Stripe page. POST /_twin/issuing/cards/:card/wallets
-    // stands in for that act ({wallet_provider, network}); the API reads the token and moves its status.
-    // Where the documentation stops and the twin decides: the network approves at once (the token is active).
-    if (seg[0] === '_twin' && seg[1] === 'issuing' && seg[2] === 'cards' && seg[3] && seg[4] === 'wallets' && seg.length === 5 && method === 'POST') {
-        const card = decodeURIComponent(seg[3]);
-        const c = getOne('issuing_card', card, req.root);
-        if (!c)
-            return err(`No such card: '${card}'`, 400, 'resource_missing');
-        const wallet = typeof params.wallet_provider === 'string' && ['apple_pay', 'google_pay', 'samsung_pay'].includes(params.wallet_provider)
-            ? params.wallet_provider : 'apple_pay';
-        const network = typeof params.network === 'string' && ['visa', 'mastercard'].includes(params.network) ? params.network : 'visa';
-        const last4 = typeof c.last4 === 'string' ? c.last4 : '0000';
-        return create('issuing_token', { card, cardholder: typeof c.cardholder === 'string' ? c.cardholder : (c.cardholder?.id ?? null) }, {
-            status: 'active', wallet_provider: wallet, network, last4, livemode: false,
-            device_fingerprint: null, network_data: null, network_updated_at: nowUnix(req.occurredAt),
-        }, req);
-    }
-    return undefined;
-}
 // collection path segment → resource type, for the generic list of a collection Stripe does not
 // list at that path (the twin's test clocks, which Stripe lists under /v1/test_helpers).

package/dist/src/engine/subscription-schedules.d.ts

@@ -0,0 +1,3 @@
+import { addBillingInterval } from './stripe.js';
+export declare const SS = "subscription_schedule";
+export type Interval = Parameters<typeof addBillingInterval>[1];

package/dist/src/engine/subscription-schedules.js

@@ -0,0 +1 @@
+export const SS = 'subscription_schedule';

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

@@ -0,0 +1,12 @@
+import type { Row } from './common.js';
+export declare const SUB = "subscription";
+/** pause_collection pauses billing (the paused event fires) and clearing it resumes
+ *  (docs.stripe.com/billing/subscriptions/pause-payment); answers the event, or nothing for a value it does not take. */
+export declare function pauseCollection(pc: unknown, fields: Row): string | undefined;
+/** The longest trial Stripe takes: `trial_end` "Can be at most two years from `billing_cycle_anchor`"
+ *  (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end); "The trial period must be 730 days (2 years)
+ *  or less" (docs.stripe.com/billing/subscriptions/trials/free-trials). */
+export declare const MAX_TRIAL: number;
+/** A trial moved to end at `end`, or a new one to `end` on a subscription out of its trial (applyTrialEnd). */
+export declare function movedTrial(sub: Row, fields: Row, end: number, now: number): undefined;
+export declare const ITEM_ATTRIBUTES: Set<string>;

package/dist/src/engine/subscriptions.js

@@ -0,0 +1,31 @@
+export const SUB = 'subscription';
+// pause_collection pauses billing (the subscription stays active; the paused event fires) and
+// clearing it resumes; cancel_at_period_end schedules or withdraws a cancel; a coupon replaces the
+// discount and an empty one clears it
+/** pause_collection pauses billing (the paused event fires) and clearing it resumes
+ *  (docs.stripe.com/billing/subscriptions/pause-payment); answers the event, or nothing for a value it does not take. */
+export function pauseCollection(pc, fields) {
+    const isClear = pc === '' || pc === null || (typeof pc === 'object' && pc !== null && Object.keys(pc).length === 0);
+    if (isClear) {
+        fields.pause_collection = null;
+        return 'customer.subscription.resumed';
+    }
+    if (!pc || typeof pc !== 'object')
+        return undefined;
+    const p = pc;
+    fields.pause_collection = { behavior: typeof p.behavior === 'string' ? p.behavior : 'void', resumes_at: p.resumes_at !== undefined ? Number(p.resumes_at) : null };
+    return 'customer.subscription.paused';
+}
+/** The longest trial Stripe takes: `trial_end` "Can be at most two years from `billing_cycle_anchor`"
+ *  (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end); "The trial period must be 730 days (2 years)
+ *  or less" (docs.stripe.com/billing/subscriptions/trials/free-trials). */
+export const MAX_TRIAL = 730 * 86400;
+/** A trial moved to end at `end`, or a new one to `end` on a subscription out of its trial (applyTrialEnd). */
+export function movedTrial(sub, fields, end, now) {
+    Object.assign(fields, {
+        status: 'trialing', trial_end: end, trial_start: sub.trial_start ?? now, billing_cycle_anchor: end,
+        current_period_end: end, ...(sub.status !== 'trialing' ? { current_period_start: now } : {}),
+    });
+    return undefined;
+}
+export const ITEM_ATTRIBUTES = new Set(['billing_thresholds', 'discounts', 'metadata', 'price', 'quantity', 'tax_rates']);

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

@@ -0,0 +1,7 @@
+import type { Row } from './common.js';
+export declare const TWIN_TAX_RATE_PCT = 10;
+export declare const ADDRESS_LINES: string[];
+export declare function settingsBody(stored: Row | undefined): Row;
+export declare const TX = "tax.transaction";
+export declare const txLine: (id: string, i: number, l: Row, sign: 1 | -1, reversal: Row | null, type: string) => Row;
+export declare const linesOf: (holder: Row) => Row[];

package/dist/src/engine/tax.js

@@ -0,0 +1,28 @@
+export const TWIN_TAX_RATE_PCT = 10;
+// ── settings: active once a head office is set; the answer has no id ──
+// the defaults' provider: "The tax calculation provider this account uses. Defaults to `stripe` when not using a
+// third-party provider" (the served spec's tax settings defaults); the head office's address answers each line, the
+// lines not given null (the served spec's address: each "(string, nullable)"; the settings page's example answers
+// line2 null)
+export const ADDRESS_LINES = ['city', 'country', 'line1', 'line2', 'postal_code', 'state'];
+export function settingsBody(stored) {
+    const given = (stored?.head_office ?? null);
+    const address = given && typeof given.address === 'object' && given.address ? given.address : undefined;
+    const headOffice = given ? { ...given, ...(address ? { address: Object.fromEntries(ADDRESS_LINES.map((k) => [k, address[k] ?? null])) } : {}) } : null;
+    const active = !!headOffice;
+    return {
+        object: 'tax.settings', livemode: false,
+        defaults: { provider: 'stripe', ...(stored?.defaults ?? { tax_behavior: null, tax_code: null }) }, head_office: headOffice,
+        status: active ? 'active' : 'pending',
+        status_details: active ? { active: {} } : { pending: { missing_fields: ['head_office'] } },
+    };
+}
+// ── transactions: committing a calculation, or reversing a transaction with negated amounts ──
+export const TX = 'tax.transaction';
+export const txLine = (id, i, l, sign, reversal, type) => ({
+    object: 'tax.transaction_line_item', id: `tax_li_${id}_${i + 1}`,
+    amount: sign === 1 ? l.amount : -(Number(l.amount) || 0), amount_tax: sign === 1 ? l.amount_tax : -(Number(l.amount_tax) || 0),
+    reference: l.reference ?? null, tax_behavior: l.tax_behavior ?? 'exclusive', tax_code: l.tax_code ?? 'txcd_99999999',
+    quantity: l.quantity ?? 1, reversal, type, livemode: false, metadata: {},
+});
+export const linesOf = (holder) => holder.line_items?.data ?? [];

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

@@ -0,0 +1,4 @@
+export declare const LOC = "terminal.location";
+export declare const READER = "terminal.reader";
+export declare const CONF = "terminal.configuration";
+export declare const TOPUP_DAYS = 5;

package/dist/src/engine/terminal.js

@@ -0,0 +1,20 @@
+// Terminal and top-up semantics: in-person locations, readers (handed a PaymentIntent to process)
+// and their configurations, the reader SDK's connection tokens, and top-ups that fund the balance
+// (a test top-up succeeds at once; only a pending one cancels, the machine in ../manifest.ts). In test mode a
+// simulated reader is presented a card by a test helper: the PaymentIntent the reader is processing is paid with a
+// card_present payment method (succeeded, or requires_capture under manual capture) and the reader's action succeeds
+// (docs.stripe.com/terminal/references/testing#simulated-test-cards,
+// docs.stripe.com/api/terminal/readers/present_payment_method). Where the documentation stops and the twin decides:
+// the presented card is the simulated reader's default Visa, and the reader answers at once.
+// Lists and retrieves are the derived core's.
+export const LOC = 'terminal.location';
+export const READER = 'terminal.reader';
+export const CONF = 'terminal.configuration';
+// ── top-ups ──
+// a top-up adds money to the balance it names, through the ledger, once its funds arrive: "USA (USD) ACH Debit Transfer
+// 5 days" (docs.stripe.com/connect/top-ups), and to the Issuing balance alike: "Top-ups debit your bank account. Your
+// top-ups can take up to 5 business days to become available. While they're pending, they won't be added to your
+// Issuing balance" (docs.stripe.com/issuing/funding/balance). It is pending until its expected_availability_date, then
+// settled by settleTopups. Where the documentation stops and the twin decides: every top-up takes exactly five days,
+// whatever its currency and balance, and succeeds.
+export const TOPUP_DAYS = 5;

package/dist/src/engine/test-clocks.d.ts

@@ -0,0 +1,5 @@
+export declare const CLOCK = "test_helpers.test_clock";
+/** How long an advance takes: "it takes a few seconds to advance to the specified time"
+ *  (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). Where the documentation stops and the twin decides:
+ *  five seconds of World time from the advance. */
+export declare const ADVANCE_SECONDS = 5;

package/dist/src/engine/test-clocks.js

@@ -0,0 +1,9 @@
+// Test clock semantics. A test clock is Stripe's own door for a transition no API verb makes: the
+// passage of time. Advancing it moves the subscriptions of the clock's customers as a real clock tick does:
+// trials that ended end, and periods that ended renew (./renewals.ts advanceBilling). List, retrieve and delete are
+// the derived core's.
+export const CLOCK = 'test_helpers.test_clock';
+/** How long an advance takes: "it takes a few seconds to advance to the specified time"
+ *  (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). Where the documentation stops and the twin decides:
+ *  five seconds of World time from the advance. */
+export const ADVANCE_SECONDS = 5;

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

@@ -0,0 +1,7 @@
+import type { Row } from './common.js';
+/** The Card object a card token carries, as the served spec's `card` describes it: its brand as a name ("Card brand.
+ *  Can be `American Express`, ... `MasterCard`, `UnionPay`, `Visa`, or `Unknown`"), the holder's name and address as
+ *  given ("Cardholder name"), and the CVC's check when one was given ("If a CVC was provided, results of the check:
+ *  pass, fail, unavailable, or unchecked"). Where the documentation stops and the twin decides: a test card's CVC passes. */
+export declare const BRAND_NAMES: Record<string, string>;
+export declare function legacyCard(id: string, card: Row): Row;

package/dist/src/engine/tokens.js

@@ -0,0 +1,20 @@
+// Token semantics: the older integrations' single-use tokens for a card, a bank account or PII. A
+// token carries only the safe fields of its instrument, never the card or account number. Retrieve
+// is the derived core's.
+import { paymentMethodSubObject } from "./stripe.js";
+/** The Card object a card token carries, as the served spec's `card` describes it: its brand as a name ("Card brand.
+ *  Can be `American Express`, ... `MasterCard`, `UnionPay`, `Visa`, or `Unknown`"), the holder's name and address as
+ *  given ("Cardholder name"), and the CVC's check when one was given ("If a CVC was provided, results of the check:
+ *  pass, fail, unavailable, or unchecked"). Where the documentation stops and the twin decides: a test card's CVC passes. */
+export const BRAND_NAMES = { amex: 'American Express', cartes_bancaires: 'Cartes Bancaires', diners: 'Diners Club', discover: 'Discover', eftpos_au: 'Eftpos Australia', girocard: 'Girocard', jcb: 'JCB', mastercard: 'MasterCard', unionpay: 'UnionPay', visa: 'Visa' };
+export function legacyCard(id, card) {
+    const pm = paymentMethodSubObject('card', { card }).card;
+    const given = (k) => (typeof card[k] === 'string' && card[k] !== '' ? card[k] : null);
+    return {
+        id, object: 'card', brand: BRAND_NAMES[String(pm.brand)] ?? 'Unknown', last4: pm.last4, exp_month: pm.exp_month, exp_year: pm.exp_year,
+        funding: pm.funding ?? 'credit', country: pm.country ?? null, fingerprint: pm.fingerprint ?? null, name: given('name'),
+        address_line1: given('address_line1'), address_line2: given('address_line2'), address_city: given('address_city'), address_state: given('address_state'),
+        address_zip: given('address_zip'), address_country: given('address_country'), address_line1_check: null, address_zip_check: null,
+        cvc_check: card.cvc !== undefined && card.cvc !== '' ? 'pass' : null, dynamic_last4: null, tokenization_method: null, metadata: {}, customer: null,
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { Row } from './common.js';
+export declare const emptyList: (url: string) => Row;

package/dist/src/engine/transfers.js

@@ -0,0 +1 @@
+export const emptyList = (url) => ({ object: 'list', data: [], has_more: false, total_count: 0, url });

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

@@ -0,0 +1,23 @@
+import type { Row } from './common.js';
+export declare const FA = "treasury.financial_account";
+export declare const TX = "treasury.transaction";
+export declare const ENTRY = "treasury.transaction_entry";
+export declare const ENTRY_TYPES: Set<string>;
+/** A financial account's features as the served spec's treasury.financial_account_features gives them: a toggle
+ *  (card_issuing, deposit_insurance, intra_stripe_flows) or a feature per network (financial_addresses.aba,
+ *  inbound_transfers.ach, outbound_payments.ach and .us_domestic_wire, outbound_transfers likewise), each
+ *  { requested, status, status_details }. What a request asks for is laid over what the account had. Where the
+ *  documentation stops and the twin decides: a requested feature is active at once (test mode), and one never requested
+ *  is left out (each is optional in the served spec). Answers the features and the active features' paths. */
+export declare const NETWORKS: Record<string, string[]>;
+export declare const TOGGLES: string[];
+export declare function featuresOf(requested: Row, had?: Row): {
+    features: Row;
+    active: string[];
+};
+export declare const noTransitions: {
+    canceled_at: null;
+    failed_at: null;
+    posted_at: null;
+    returned_at: null;
+};