@volter/twin-stripe 3.0.0 → 3.0.2

package/src/engine/connect.ts

@@ -3,10 +3,9 @@
 // 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.ts';
+import { accountRequirements, accountSettings, PLATFORM_ACCOUNT_ID } from './stripe.ts';
 import { currentlyDue, kindOf } from './onboarding.ts';
 import { externalList, type Row } from './common.ts';
-
 // 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),
@@ -64,8 +63,6 @@ export const at_path = (a: Row, path: string): unknown => path.split('.').reduce
 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: string): boolean => [...CARD_COMPANY_NOW, ...CARD_COMPANY_LATER, ...CARD_INDIVIDUAL_NOW].includes(field);
 export const personHas = (p: Row, field: string): boolean => {
   if (field === 'ssn_last_4') return p.ssn_last_4_provided === true;
   const v = at_path(p, field);
@@ -107,78 +104,3 @@ export function keptKyc(params: Row): Row {
   }
   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: Row, was: Row = {}): Row {
-  const { ssn_last_4, id_number, ...rest } = params;
-  const out: Row = { ...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'] as const) if (out[k] && typeof out[k] === 'object' && was[k] && typeof was[k] === 'object') out[k] = { ...(was[k] as Row), ...(out[k] as Row) };
-  return out;
-}
-export const RELATIONSHIP: Row = { 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: Row, id: string, status: unknown, requested = true, requestedAt: unknown = null): Row => {
-  const req = (acct.requirements as Row | undefined) ?? {};
-  const mine = (list: unknown): string[] => (Array.isArray(list) ? (list as string[]) : []).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: Record<string, string[]> = {
-  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: Row, given: Row): Row {
-  const stripeLosses = (((account.controller as Row | undefined)?.losses as Row | undefined)?.payments) === 'stripe';
-  const out: Row = {};
-  for (const [name, featureNames] of Object.entries(SESSION_COMPONENTS)) {
-    const c = given[name] && typeof given[name] === 'object' ? (given[name] as Row) : {};
-    const asked = c.features && typeof c.features === 'object' ? (c.features as Row) : {};
-    const f: Row = {};
-    const val = (k: string, fallback: boolean): boolean => (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/src/engine/customers.ts

@@ -3,33 +3,8 @@
 // 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.ts';
 import type { Row } from './common.ts';
-
 /** 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: string): Row => ({ 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: Record<string, RegExp> = {
-  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: string): string | undefined => {
-  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/src/engine/display.ts

@@ -1,5 +1,7 @@
 // What Stripe's pages show of an account, and where its Connect OAuth connections are kept.
 
+// What Stripe's pages show of an account, and where its Connect OAuth connections are kept.
+
 type Row = Record<string, any>;
 
 /** The name an account shows its customers (Checkout, the customer portal): its public business name,
@@ -10,9 +12,6 @@ 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 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: Row | undefined): string {
   const named = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v : undefined);
   return named(account?.business_profile?.name) ?? named(account?.settings?.dashboard?.display_name) ?? PLATFORM_DEFAULT_NAME;

package/src/engine/files.ts

@@ -4,19 +4,6 @@
 // are the derived core's to list and read, as are file list and retrieve, session retrieve and
 // portal-configuration retrieve.
 import type { Row } from './common.ts';
-
-/** 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: string): string | null {
-  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'] as const;
-
 export const PBC = 'billing_portal.configuration';
 
 /** A portal configuration's features, each filled where the request leaves it: every feature is answered (the served

package/src/engine/invoices.ts

@@ -4,41 +4,9 @@
 // items, and mint the PaymentIntent a finalized invoice collects through. The invoice list and the
 // item list are the derived core's.
 import type { Row } from './common.ts';
+import { applyCouponDiscount } from './stripe.ts';
 
 export const INV = 'invoice';
-export const linesOf = (inv: Row): Row[] => (inv.lines as { data?: Row[] } | undefined)?.data ?? [];
-export const sumLines = (lines: Row[]): number => lines.reduce((s, l) => s + (Number(l.amount) || 0), 0);
-
-/** A draft's line no invoice item made (a subscription's) stays as it is when an item changes. */
-export function unlinkedLine(line: Row): Row {
-  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: Row[], subtotal: number, currency: string, now: number, period: number): void {
-  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: number): Row => ({
-  status: 'draft', livemode: false, currency: 'usd', collection_method: 'charge_automatically',
-  auto_advance: false, attempt_count: 0, attempted: false,
-  amount_due: 0, amount_paid: 0, amount_remaining: 0, amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
-  subtotal: 0, total: 0, starting_balance: 0, post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
-  period_start: now, period_end: now, default_tax_rates: [], discounts: [],
-  lines: { object: 'list', data: [], has_more: false, total_count: 0 },
-  automatic_tax: { enabled: false, liability: null, status: null },
-  status_transitions: { finalized_at: null, marked_uncollectible_at: null, paid_at: null, voided_at: null },
-  issuer: { type: 'self' },
-  payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
-  // a draft has no PaymentIntent: finalize mints it
-  payment_intent: null,
-});
 
 /** 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"
@@ -69,3 +37,66 @@ export function invoicePayment(inv: Row): Row | undefined {
     status_transitions: { paid_at: paid ? (transitions.paid_at ?? null) : null, canceled_at: inv.status === 'void' ? (transitions.voided_at ?? null) : null },
   };
 }
+
+
+export const linesOf = (inv: Row): Row[] => (inv.lines as { data?: Row[] } | undefined)?.data ?? [];
+
+
+export const sumLines = (lines: Row[]): number => lines.reduce((s, l) => s + (Number(l.amount) || 0), 0);
+
+
+
+/** Credit the previous price and debit the replacement for the same remaining service time. */
+// source: https://docs.stripe.com/billing/subscriptions/prorations "Unused time on original 10 USD plan (credit)"
+// source: https://docs.stripe.com/billing/subscriptions/prorations "Remaining time on new 20 USD plan (debit)"
+// source: https://docs.stripe.com/billing/subscriptions/prorations "The current billing period’s start and end times are used to calculate the cost of the subscription before and after the change."
+// source: https://docs.stripe.com/billing/subscriptions/prorations "By default, Stripe calculates prorations down to the second."
+export function prorationLines(before: Row[], after: Row[], time: number, start: number, end: number, coupon: Row | undefined): Row[] {
+  const out: Row[] = [];
+  const discounted = (line: Row, lines: Row[]): number => {
+    const total = sumLines(lines);
+    // source: https://docs.stripe.com/billing/subscriptions/prorations "When calculating proration credits or debits, Stripe uses the subscription’s discounted price, not the original price."
+    return Number(line.amount) - (total > 0 ? applyCouponDiscount(total, coupon) * Number(line.amount) / total : 0);
+  };
+  const priceId = (line: Row): unknown => typeof line.price === 'object' ? (line.price as Row).id : line.price;
+  const append = (line: Row, lines: Row[], credit: boolean): void => {
+    const billingPeriod = line.period as Row;
+    const periodStart = Number(billingPeriod.start ?? start), periodEnd = Number(billingPeriod.end ?? end);
+    const fraction = Math.max(0, Math.min(1, (periodEnd - time) / Math.max(1, periodEnd - periodStart)));
+    const amount = Math.round(discounted(line, lines) * fraction) * (credit ? -1 : 1);
+    if (!amount) return;
+    out.push({ ...line, id: `${line.id}_${credit ? 'unused' : 'remaining'}`, amount, proration: true, discountable: false,
+      period: { start: time, end: periodEnd }, description: `${credit ? 'Unused' : 'Remaining'} time on ${String((line.price as Row)?.nickname ?? priceId(line))}` });
+  };
+  for (const old of before) {
+    const replacement = after.find(line => line.subscription_item === old.subscription_item);
+    if (replacement && priceId(replacement) === priceId(old) && replacement.quantity === old.quantity) continue;
+    append(old, before, true);
+  }
+  for (const next of after) {
+    const previous = before.find(line => line.subscription_item && line.subscription_item === next.subscription_item);
+    if (previous && priceId(previous) === priceId(next) && previous.quantity === next.quantity) continue;
+    append(next, after, false);
+  }
+  return out;
+}
+
+
+
+// ── invoices ──
+
+/** A draft invoice's fields before anything is on it: what a new invoice and a preview start from. */
+export const draft = (now: number): Row => ({
+  status: 'draft', livemode: false, currency: 'usd', collection_method: 'charge_automatically',
+  auto_advance: false, attempt_count: 0, attempted: false,
+  amount_due: 0, amount_paid: 0, amount_remaining: 0, amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
+  subtotal: 0, total: 0, starting_balance: 0, post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
+  period_start: now, period_end: now, default_tax_rates: [], discounts: [],
+  lines: { object: 'list', data: [], has_more: false, total_count: 0 },
+  automatic_tax: { enabled: false, liability: null, status: null },
+  status_transitions: { finalized_at: null, marked_uncollectible_at: null, paid_at: null, voided_at: null },
+  issuer: { type: 'self' },
+  payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
+  // a draft has no PaymentIntent: finalize mints it
+  payment_intent: null,
+});

package/src/engine/issuing.ts

@@ -9,7 +9,6 @@
 // (card, then cardholder), then the real-time issuing_authorization.request webhook delivered
 // synchronously to the first enrolled endpoint; with none it is approved (card_active).
 import type { Row } from './common.ts';
-
 export const CH = 'issuing.cardholder';
 /** The id of a card's cardholder: the card answers the cardholder in full (the served spec's issuing.card.cardholder is
  *  the Cardholder object, not an id); its id is read from it for filtering and for the objects that name it by id. */
@@ -17,9 +16,6 @@ export const holderId = (c: Row): string => (typeof c.cardholder === 'string' ?
 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: { amount: number; currency: string; approved: boolean; reason: string; reasonMessage: string | null; createdSec: number; merchantAmount: number; merchantCurrency: string }): Row {
@@ -52,10 +48,19 @@ export const cardId = (auth: Row): unknown => (auth.card && typeof auth.card ===
  *  (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: Row[] = [
-  { 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: string): string {
+  const body = `4${[...drawn].map((ch) => String(ch.charCodeAt(0) % 10)).join('').padEnd(14, '0').slice(0, 14)}`;
+  let sum = 0;
+  for (let i = 0; i < body.length; i++) {
+    let d = Number(body[body.length - 1 - i]);
+    if (i % 2 === 0) { d *= 2; if (d > 9) d -= 9; }
+    sum += d;
+  }
+  return `${body}${(10 - (sum % 10)) % 10}`;
+}
+
+/** A virtual card's CVC, drawn from the World: three digits. */
+export const cvcOf = (drawn: string): string => [...drawn].map((ch) => String(ch.charCodeAt(0) % 10)).join('').padEnd(3, '0').slice(0, 3);

package/src/engine/ledger.ts

@@ -37,9 +37,7 @@
 // connected account to the platform.
 import type { Row } from './common.ts';
 import { BYPASS_PENDING_CARDS } from './test-cards.ts';
-
 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/src/engine/oauth.ts

@@ -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: string): string => {

package/src/engine/onboarding.ts

@@ -2,7 +2,6 @@
 // ../screens/connect-onboarding.tsx), as the Accounts API reports them (`requirements.currently_due`): the two US sets the twin
 // models, a company's and an individual's.
 import { INDUSTRIES as MCCS } from './industries.ts';
-
 type Row = Record<string, unknown>;
 
 export const OFFERED = new Set(MCCS.map(([mcc]) => mcc));

package/src/engine/params.ts

@@ -11,7 +11,6 @@
 // the values of the payment_method_types it still takes (PAYMENT_METHOD_TYPES below); nested parameters are not checked.
 
 import surface from '../generated/surface.gen.json' with { type: 'json' };
-
 type Param = { name: string; required?: boolean };
 type Op = { id: string; method: string; query?: Param[]; body?: Param[] };
 export const OPS = new Map((surface.operations as Op[]).map((o) => [o.id, o]));

package/src/engine/payment-intents.ts

@@ -2,7 +2,6 @@
 // what Stripe answers otherwise; these handlers compute what each move does. List, retrieve and
 // update are the derived core's; search is Stripe's query language over the intents.
 import type { Row } from './common.ts';
-
 export const PI = 'payment_intent';
 /** Bookkeeping: the intents whose caller named the methods (payment_method_types, allowed_payment_method_types) on
  *  create. The twin's default list (['card']) stands for Stripe's choice and restricts nothing, so only a named list

package/src/engine/payment-methods.ts

@@ -3,7 +3,6 @@
 import { paymentMethodSubObject } from './stripe.ts';
 import { AFTER_SUCCESS_CARDS } from './after-payment.ts';
 import type { Row } from './common.ts';
-
 export const PM = 'payment_method';
 export const noBilling = { address: null, email: null, name: null, phone: null };
 

package/src/engine/refunds.ts

@@ -1,29 +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/src/engine/renewals.ts

@@ -25,7 +25,6 @@
 //   (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle).
 import { priceAmount } from './stripe.ts';
 import type { Row } from './common.ts';
-
 export const SUB = 'subscription';
 export const INV = 'invoice';
 export const HOUR = 3600;