@volter/twin-stripe 3.0.0 → 3.0.1

package/dist/src/engine/connect.js

@@ -3,7 +3,7 @@
 // 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, asBool, PLATFORM_ACCOUNT_ID } from "./stripe.js";
+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
@@ -60,8 +60,6 @@ export const at_path = (a, path) => path.split('.').reduce((v, k) => (v && typeo
 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'];
-/** A field only card_payments asks for (the transfers capability's requirements leave it out). */
-export const cardOnly = (field) => [...CARD_COMPANY_NOW, ...CARD_COMPANY_LATER, ...CARD_INDIVIDUAL_NOW].includes(field);
 export const personHas = (p, field) => {
     if (field === 'ssn_last_4')
         return p.ssn_last_4_provided === true;
@@ -108,82 +106,3 @@ export function keptKyc(params) {
     }
     return out;
 }
-/** A person's details as Stripe keeps them: an SSN or ID number given is kept only as provided (the Person object
- *  answers ssn_last_4_provided and id_number_provided, never the numbers; docs.stripe.com/api/persons/object). */
-export function keptPerson(params, was = {}) {
-    const { ssn_last_4, id_number, ...rest } = params;
-    const out = { ...rest, ...(ssn_last_4 !== undefined && ssn_last_4 !== '' ? { ssn_last_4_provided: true } : {}), ...(id_number !== undefined && id_number !== '' ? { id_number_provided: true } : {}) };
-    // a relationship, address or date of birth given in part is laid over what the person holds
-    for (const k of ['relationship', 'address', 'dob'])
-        if (out[k] && typeof out[k] === 'object' && was[k] && typeof was[k] === 'object')
-            out[k] = { ...was[k], ...out[k] };
-    return out;
-}
-export const RELATIONSHIP = { director: false, executive: false, owner: false, representative: false, percent_ownership: null, title: null };
-// ── capabilities: the account's capability map is the truth; requesting one leaves it pending ──
-/** A capability as its account stands: its status, and the account's requirements that capability asks for (transfers
- *  leaves out what only card_payments asks for). Where the documentation stops and the twin decides: the account-wide
- *  fields (the bank account, the terms) belong to every capability. */
-export const capabilityBody = (acct, id, status, requested = true, requestedAt = null) => {
-    const req = acct.requirements ?? {};
-    const mine = (list) => (Array.isArray(list) ? list : []).filter((f) => id === 'card_payments' || !cardOnly(f));
-    const due = mine(req.currently_due);
-    return {
-        id, object: 'capability', account: acct.id, status, requested, requested_at: requestedAt,
-        requirements: { currently_due: due, eventually_due: mine(req.eventually_due), past_due: [], pending_verification: [], errors: [], alternatives: [], current_deadline: null, disabled_reason: due.length ? 'requirements.past_due' : null },
-    };
-};
-// a session is identified by its client_secret: the row is kept for traceability, the answer has no id
-/** Every embedded component an account session answers (the served spec requires all of them), each enabled only when
- *  the request enables it, with its features: what the request gives, else the spec's stated default, "The default
- *  value for this feature is `true`" (external_account_collection); disable_stripe_user_authentication "the opposite of
- *  the `external_account_collection` value"; edit_payout_schedule and standard_payouts "Defaults to `true` when
- *  `controller.losses.payments` is set to `stripe` for the account, otherwise `false`"; capture_payments, dispute_management
- *  and refund_management "true by default"; destination_on_behalf_of_charge_management "false by default";
- *  smart_disputes_management "Defaults to the value of `dispute_management`". Where the documentation stops and the twin
- *  decides: instant_payouts (described as `enabled` "when Stripe is responsible for negative account balances", typed
- *  boolean) is true exactly then, and the Issuing and financial-account features, which state no default, are false. */
-export const SESSION_COMPONENTS = {
-    account_management: ['external_account_collection', 'disable_stripe_user_authentication'],
-    account_onboarding: ['external_account_collection', 'disable_stripe_user_authentication'],
-    balance_report: [], documents: [], payout_details: [], payout_reconciliation_report: [], payouts_list: [], tax_registrations: [], tax_settings: [],
-    balances: ['external_account_collection', 'disable_stripe_user_authentication', 'edit_payout_schedule', 'instant_payouts', 'standard_payouts'],
-    payouts: ['external_account_collection', 'disable_stripe_user_authentication', 'edit_payout_schedule', 'instant_payouts', 'standard_payouts'],
-    disputes_list: ['capture_payments', 'destination_on_behalf_of_charge_management', 'dispute_management', 'refund_management', 'smart_disputes_management'],
-    payment_details: ['capture_payments', 'destination_on_behalf_of_charge_management', 'dispute_management', 'refund_management', 'smart_disputes_management'],
-    payments: ['capture_payments', 'destination_on_behalf_of_charge_management', 'dispute_management', 'refund_management', 'smart_disputes_management'],
-    payment_disputes: ['destination_on_behalf_of_charge_management', 'dispute_management', 'refund_management', 'smart_disputes_management'],
-    financial_account: ['external_account_collection', 'disable_stripe_user_authentication', 'send_money', 'transfer_balance'],
-    financial_account_transactions: ['card_spend_dispute_management'],
-    instant_payouts_promotion: ['external_account_collection', 'disable_stripe_user_authentication', 'instant_payouts'],
-    issuing_card: ['card_management', 'card_spend_dispute_management', 'cardholder_management', 'spend_control_management'],
-    issuing_cards_list: ['card_management', 'card_spend_dispute_management', 'cardholder_management', 'disable_stripe_user_authentication', 'spend_control_management'],
-    notification_banner: ['external_account_collection', 'disable_stripe_user_authentication'],
-    payment_method_settings: ['disable_stripe_user_authentication'],
-};
-export function sessionComponents(account, given) {
-    const stripeLosses = (account.controller?.losses?.payments) === 'stripe';
-    const out = {};
-    for (const [name, featureNames] of Object.entries(SESSION_COMPONENTS)) {
-        const c = given[name] && typeof given[name] === 'object' ? given[name] : {};
-        const asked = c.features && typeof c.features === 'object' ? c.features : {};
-        const f = {};
-        const val = (k, fallback) => (asked[k] !== undefined ? asBool(asked[k]) : fallback);
-        for (const k of featureNames) {
-            if (k === 'external_account_collection')
-                f[k] = val(k, true);
-            else if (k === 'disable_stripe_user_authentication')
-                f[k] = val(k, !val('external_account_collection', true));
-            else if (k === 'edit_payout_schedule' || k === 'standard_payouts' || k === 'instant_payouts')
-                f[k] = val(k, stripeLosses);
-            else if (k === 'capture_payments' || k === 'dispute_management' || k === 'refund_management')
-                f[k] = val(k, true);
-            else if (k === 'smart_disputes_management')
-                f[k] = val(k, val('dispute_management', true));
-            else
-                f[k] = val(k, false);
-        }
-        out[name] = { enabled: c.enabled !== undefined ? asBool(c.enabled) : false, features: f };
-    }
-    return out;
-}

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

@@ -2,11 +2,3 @@ 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;
-export declare const EU_VAT: Record<string, RegExp>;
-export declare const euVatCountry: (value: string) => string | undefined;
-/** The tax ID types Stripe checks against a government register: "Stripe automatically validates all Australian
- *  Business Numbers (ABNs)", "all European Value-Added-Tax (EU VAT) numbers" (VIES) and "all UK Value-Added-Tax (GB VAT)
- *  numbers" (HMRC); a verification's status "is pending, verified, unverified, or unavailable", and "When automatic
- *  validation is unavailable, you must manually verify the tax ID" (docs.stripe.com/billing/customer/tax-ids). Any other
- *  type answers unavailable; one of these waits pending. */
-export declare const AUTO_VALIDATED: Set<string>;

package/dist/src/engine/customers.js

@@ -6,25 +6,3 @@ import { invoicePrefix } from "./invoices.js";
  *  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 ──
-// An EU VAT number is its country's prefix and that country's format (the European Commission's VIES formats,
-// ec.europa.eu/taxation_customs/vies); Stripe refuses one that does not fit as tax_id_invalid
-// (docs.stripe.com/error-codes#tax-id-invalid). The message's wording is the twin's.
-export const EU_VAT = {
-    AT: /^U\d{8}$/, BE: /^[01]\d{9}$/, BG: /^\d{9,10}$/, CY: /^\d{8}[A-Z]$/, CZ: /^\d{8,10}$/, DE: /^\d{9}$/, DK: /^\d{8}$/,
-    EE: /^\d{9}$/, EL: /^\d{9}$/, ES: /^[A-Z0-9]\d{7}[A-Z0-9]$/, FI: /^\d{8}$/, FR: /^[A-Z0-9]{2}\d{9}$/, HR: /^\d{11}$/,
-    HU: /^\d{8}$/, IE: /^(\d{7}[A-W][A-I]?|\d[A-Z+*]\d{5}[A-W])$/, IT: /^\d{11}$/, LT: /^(\d{9}|\d{12})$/, LU: /^\d{8}$/,
-    LV: /^\d{11}$/, MT: /^\d{8}$/, NL: /^\d{9}B\d{2}$/, PL: /^\d{10}$/, PT: /^\d{9}$/, RO: /^\d{2,10}$/, SE: /^\d{12}$/,
-    SI: /^\d{8}$/, SK: /^\d{10}$/, XI: /^(\d{9}|\d{12}|GD\d{3}|HA\d{3})$/,
-};
-export const euVatCountry = (value) => {
-    const v = value.replace(/[\s.-]/g, '').toUpperCase();
-    const prefix = v.slice(0, 2);
-    const format = EU_VAT[prefix];
-    return format && format.test(v.slice(2)) ? (prefix === 'EL' ? 'GR' : prefix) : undefined;
-};
-/** The tax ID types Stripe checks against a government register: "Stripe automatically validates all Australian
- *  Business Numbers (ABNs)", "all European Value-Added-Tax (EU VAT) numbers" (VIES) and "all UK Value-Added-Tax (GB VAT)
- *  numbers" (HMRC); a verification's status "is pending, verified, unverified, or unavailable", and "When automatic
- *  validation is unavailable, you must manually verify the tax ID" (docs.stripe.com/billing/customer/tax-ids). Any other
- *  type answers unavailable; one of these waits pending. */
-export const AUTO_VALIDATED = new Set(['au_abn', 'eu_vat', 'gb_vat']);

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

@@ -7,8 +7,5 @@ type Row = Record<string, any>;
  *  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.";
-/** The bookkeeping type of a connected account's Connect OAuth connection (../screens/connect-oauth.tsx): one row per
- *  account, `revoked: true` once deauthorized or its code reused. Read by the account list and the event path too. */
-export declare const OAUTH_CONNECTIONS = "_oauth_connection";
 export declare function publicBusinessName(account: Row | undefined): string;
 export {};

package/dist/src/engine/display.js

@@ -7,9 +7,6 @@
  *  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.';
-/** The bookkeeping type of a connected account's Connect OAuth connection (../screens/connect-oauth.tsx): one row per
- *  account, `revoked: true` once deauthorized or its code reused. Read by the account list and the event path too. */
-export const OAUTH_CONNECTIONS = '_oauth_connection';
 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

@@ -1,11 +1,4 @@
 import type { Row } from './common.js';
-/** The type Stripe answers for an uploaded file: "The returned file type (for example, csv, pdf, jpg, or png)"
- *  (docs.stripe.com/api/files/object). Where the documentation stops and the twin decides: read from the name's
- *  extension (jpeg as jpg), and null for a name without one. */
-export declare function fileType(name: string): string | null;
-/** The purposes a file link may be made to: "The file's `purpose` must be one of the following: …" (the served
- *  spec, POST /v1/file_links `file`). */
-export declare const LINKABLE: readonly ["business_icon", "business_logo", "customer_signature", "dispute_evidence", "finance_report_run", "financial_account_statement", "identity_document_downloadable", "issuing_regulatory_reporting", "pci_document", "selfie", "sigma_scheduled_query", "tax_document_user_upload", "terminal_android_apk", "terminal_reader_splashscreen"];
 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

package/dist/src/engine/files.js

@@ -1,13 +1,3 @@
-/** The type Stripe answers for an uploaded file: "The returned file type (for example, csv, pdf, jpg, or png)"
- *  (docs.stripe.com/api/files/object). Where the documentation stops and the twin decides: read from the name's
- *  extension (jpeg as jpg), and null for a name without one. */
-export function fileType(name) {
-    const ext = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
-    return ext ? (ext === 'jpeg' ? 'jpg' : ext) : null;
-}
-/** The purposes a file link may be made to: "The file's `purpose` must be one of the following: …" (the served
- *  spec, POST /v1/file_links `file`). */
-export const LINKABLE = ['business_icon', 'business_logo', 'customer_signature', 'dispute_evidence', 'finance_report_run', 'financial_account_statement', 'identity_document_downloadable', 'issuing_regulatory_reporting', 'pci_document', 'selfie', 'sigma_scheduled_query', 'tax_document_user_upload', 'terminal_android_apk', 'terminal_reader_splashscreen'];
 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

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

@@ -1,14 +1,5 @@
 import type { Row } from './common.js';
 export declare const INV = "invoice";
-export declare const linesOf: (inv: Row) => Row[];
-export declare const sumLines: (lines: Row[]) => number;
-/** A draft's line no invoice item made (a subscription's) stays as it is when an item changes. */
-export declare function unlinkedLine(line: Row): Row;
-/** 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 declare function prorationLines(out: Row[], subtotal: number, currency: string, now: number, period: number): void;
-/** 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;
 /** 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;
@@ -22,3 +13,9 @@ export declare const invoicePrefix: (customerId: string) => string;
  *  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

@@ -1,33 +1,5 @@
+import { applyCouponDiscount } from "./stripe.js";
 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
@@ -55,3 +27,58 @@ export function invoicePayment(inv) {
         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

@@ -6,9 +6,6 @@ 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;
@@ -28,8 +25,9 @@ export declare const cardId: (auth: Row) => unknown;
  *  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[];
+/** 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

@@ -5,9 +5,6 @@ export const holderId = (c) => (typeof c.cardholder === 'string' ? c.cardholder
 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 {
@@ -36,10 +33,22 @@ export const cardId = (auth) => (auth.card && typeof auth.card === 'object' ? au
  *  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' },
-];
+/** 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

@@ -1,6 +1,5 @@
 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>;

package/dist/src/engine/ledger.js

@@ -1,6 +1,5 @@
 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));

package/dist/src/engine/oauth.js

@@ -1,5 +1,4 @@
-// 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.
+// 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] ?? '';

package/dist/src/engine/refunds.js

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

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

@@ -22,7 +22,6 @@ export declare function requiresAuthentication(...paramSets: Array<Record<string
 export declare function threeDsNextAction(): Record<string, unknown>;
 export declare function requiresMicrodeposits(...paramSets: Array<Record<string, unknown>>): boolean;
 export declare function microdepositsNextAction(): Record<string, unknown>;
-export declare function verifyMicrodeposits(params: Record<string, unknown>, _existing: Record<string, unknown>): StripeResponse | null;
 /** A card error's body: `charge` "For card errors, the ID of the failed charge", and `payment_intent` "The PaymentIntent
  *  object for errors returned on a request involving a PaymentIntent" (docs.stripe.com/api/errors). */
 export declare function cardError(outcome: DeclineOutcome, attach?: {
@@ -51,10 +50,6 @@ export declare function subscriptionCouponParam(params: Record<string, unknown>)
 export declare function buildDiscount(coupon: Record<string, unknown>, customer: string, at: number, on?: {
     subscription?: string;
 }): Record<string, unknown>;
-export declare function subscriptionItemPairs(sub: Record<string, unknown>): Array<{
-    price: string;
-    quantity: number;
-}>;
 export declare function subscriptionItemEntries(value: unknown): Array<Record<string, unknown>>;
 type BillingInterval = 'day' | 'week' | 'month' | 'year';
 export declare function resolveSubscriptionBillingInterval(entries: Array<Record<string, unknown>>, find: FindStored): {
@@ -81,9 +76,8 @@ export declare function resolveTrial(params: Record<string, unknown>, at: number
     start: number;
     end: number;
 } | undefined;
-export declare function embedIssuingAuthorizationCard(body: Record<string, unknown>, find: FindStored): Record<string, unknown>;
 export declare function emptySpendingControls(): Record<string, unknown>;
-export declare function normalizeSpendingControls(raw: unknown, currency: string | null): {
+export declare function normalizeSpendingControls(raw: unknown, currency: string | null, previous?: Record<string, unknown>): {
     controls?: Record<string, unknown>;
     error?: StripeResponse;
 };
@@ -124,4 +118,5 @@ export declare function resolveLineItem(entry: Record<string, unknown>, index: n
 };
 export declare function lineItemEntries(params: Record<string, unknown>): Array<Record<string, unknown>>;
 export declare function chargeDefaults(chargeId: string, amount: number, captured: boolean, occurredAt?: string): Record<string, unknown>;
+export declare function planView(price: Record<string, unknown>): Record<string, unknown>;
 export {};