@volter/twin-stripe 0.1.2 → 2.0.0

package/src/semantics/credit-notes.ts

@@ -0,0 +1,168 @@
+// Credit note semantics. A credit note credits part of an invoice: pre_payment while the invoice
+// is unpaid (it lowers what is owed), post_payment once paid. The invoice carries the sums of its
+// issued credit notes, re-derived on every change so voiding one returns the invoice to where it
+// was. The machine in ../manifest.ts says a credit note is voided once. The list is the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { paginate } from '../stripe-twin.ts';
+import { refundCharge } from './refunds.ts';
+import { at, created, fail, path, type Row } from './shared.ts';
+
+const CN = 'credit_note';
+const noteMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such credit note: '${id}'`, 404, 'resource_missing');
+
+/** The credit note the request describes (the `amount` form: one custom line), or Stripe's refusal. */
+function build(ctx: SemanticsContext, id: string): Row | Response {
+  const params = ctx.params;
+  const invoiceId = typeof params.invoice === 'string' ? params.invoice : '';
+  if (!invoiceId) return fail(ctx, 'Missing required param: invoice.', 400, 'parameter_missing');
+  const invoice = ctx.get('invoice', invoiceId);
+  if (!invoice) return fail(ctx, `No such invoice: '${invoiceId}'`, 404, 'resource_missing');
+  if (params.amount === undefined) return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
+  const amount = Number(params.amount);
+  if (!Number.isInteger(amount) || amount <= 0) return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+  const vendorType = invoice.status === 'paid' ? 'post_payment' : 'pre_payment';
+  const outOfBand = Number(params.out_of_band_amount) || 0;
+  // a paid invoice's credit is paid back: "The sum of refunds, customer balance credits, and outside of Stripe credits
+  // must equal the post_payment_amount" (docs.stripe.com/api/credit_notes/create); the message's wording is the twin's
+  if (vendorType === 'post_payment') {
+    const split = (Number(params.refund_amount) || 0) + (Number(params.credit_amount) || 0) + outOfBand;
+    if (split !== amount) return fail(ctx, `The sum of refund_amount, credit_amount and out_of_band_amount (${split}) must equal the credit note's post_payment_amount (${amount}).`, 400, 'parameter_invalid_integer');
+  }
+  const line = {
+    object: 'credit_note_line_item', id: `cnli_${id}_1`, type: 'custom_line_item',
+    amount, description: typeof params.memo === 'string' ? params.memo : null,
+    // a custom line credits no invoice line: invoice_line_item ("ID of the invoice line item being credited") is left
+    // out, the served spec not letting it be null
+    discount_amount: 0, discount_amounts: [], livemode: false,
+    pretax_credit_amounts: [], quantity: null, tax_rates: [], taxes: [],
+    unit_amount: null, unit_amount_decimal: null,
+  };
+  return {
+    amount, amount_shipping: 0, created: ctx.now(), currency: typeof invoice.currency === 'string' ? invoice.currency : 'usd', customer: typeof invoice.customer === 'string' ? invoice.customer : null,
+    customer_balance_transaction: null,
+    // "The date when this credit note is in effect. Same as `created` unless overwritten" (the served spec)
+    discount_amount: 0, discount_amounts: [], effective_at: params.effective_at !== undefined ? Number(params.effective_at) : ctx.now(), invoice: invoiceId,
+    lines: { object: 'list', data: [line], has_more: false, total_count: 1, url: `/v1/credit_notes/${id}/lines` },
+    livemode: false, memo: params.memo ?? null, metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
+    number: `${invoiceId}-CN-01`, out_of_band_amount: outOfBand || null,
+    pdf: `https://files.twin.local/credit_notes/${id}.pdf`,
+    post_payment_amount: vendorType === 'post_payment' ? amount : 0,
+    pre_payment_amount: vendorType === 'pre_payment' ? amount : 0,
+    pretax_credit_amounts: [],
+    reason: typeof params.reason === 'string' ? params.reason : null,
+    refunds: [], shipping_cost: null, status: 'issued',
+    subtotal: amount, subtotal_excluding_tax: amount,
+    type: vendorType, total: amount, total_excluding_tax: amount, total_taxes: [],
+    voided_at: null,
+  };
+}
+
+/** The invoice's credit-note sums, from its issued credit notes; a pre-payment credit lowers what is owed. */
+async function syncInvoice(ctx: SemanticsContext, invoiceId: string): Promise<void> {
+  const inv = ctx.get('invoice', invoiceId);
+  if (!inv) return;
+  let pre = 0;
+  let post = 0;
+  for (const cn of ctx.rows(CN)) {
+    if (cn.invoice !== invoiceId || cn.status === 'void') continue;
+    if (cn.type === 'post_payment') post += Number(cn.amount) || 0;
+    else pre += Number(cn.amount) || 0;
+  }
+  const total = Number(inv.total ?? inv.amount_due) || 0;
+  const paid = Number(inv.amount_paid) || 0;
+  await ctx.write('invoice', invoiceId, { pre_payment_credit_notes_amount: pre, post_payment_credit_notes_amount: post, amount_remaining: Math.max(0, total - paid - pre) }, 'invoice.update');
+}
+
+// the preview computes the credit note without keeping it
+const preview: Semantics = async (ctx) => {
+  const id = 'cn_preview';
+  const cn = build(ctx, id);
+  return cn instanceof Response ? cn : ctx.reply({ object: CN, ...cn, id });
+};
+
+/** What a post-payment credit pays back: "Refunds: create a new refund (using refund_amount)"; "Customer balance credit:
+ *  credit the customer's balance (using credit_amount) which will be automatically applied to their next invoice when
+ *  it's finalized" (docs.stripe.com/api/credit_notes/create). The refund is made on the invoice's charge as a refund
+ *  call makes it (refunds.ts); the credit is a customer balance transaction of type credit_note. Where the documentation
+ *  stops and the twin decides: the refund carries no reason of its own. */
+async function payBack(ctx: SemanticsContext, id: string, cn: Row): Promise<Row | Response> {
+  const params = ctx.params;
+  const out: Row = {};
+  const refundAmount = Number(params.refund_amount) || 0;
+  if (refundAmount > 0) {
+    const invoice = ctx.get('invoice', String(cn.invoice));
+    const pi = typeof invoice?.payment_intent === 'string' ? ctx.get('payment_intent', invoice.payment_intent) : undefined;
+    const chargeId = typeof invoice?.charge === 'string' ? invoice.charge : typeof pi?.latest_charge === 'string' ? pi.latest_charge : undefined;
+    const charge = chargeId ? ctx.get('charge', chargeId) : undefined;
+    if (!charge) return fail(ctx, 'This invoice was not paid with a charge that can be refunded.', 400, 'invoice_no_charge_to_refund');
+    const answer = await refundCharge(ctx, charge, { amount: refundAmount });
+    if (answer.status >= 400) return answer;
+    const refund = (await answer.json()) as Row;
+    out.refunds = [{ amount_refunded: refundAmount, refund: refund.id, type: 'refund', payment_record_refund: null }];
+  }
+  const creditAmount = Number(params.credit_amount) || 0;
+  const customer = typeof cn.customer === 'string' ? cn.customer : undefined;
+  if (creditAmount > 0 && customer) {
+    const ending = (Number(ctx.get('customer', customer)?.balance) || 0) - creditAmount;
+    const txn = await created(ctx, 'customer_balance_transaction', { customer, amount: -creditAmount, currency: cn.currency, credit_note: id, invoice: cn.invoice }, {
+      ending_balance: ending, type: 'credit_note', livemode: false, metadata: {}, description: null, checkout_session: null,
+    });
+    await ctx.write('customer', customer, { balance: ending }, `customer.balance_adjusted:${String(txn.id)}`);
+    out.customer_balance_transaction = txn.id;
+  }
+  return out;
+}
+
+const create: Semantics = async (ctx) => {
+  const id = ctx.mint(CN);
+  const cn = build(ctx, id);
+  if (cn instanceof Response) return cn;
+  const paid = cn.type === 'post_payment' ? await payBack(ctx, id, cn) : {};
+  if (paid instanceof Response) return paid;
+  const body = await created(ctx, CN, { id, ...cn, ...paid }, {});
+  await syncInvoice(ctx, String(cn.invoice));
+  return ctx.reply(body);
+};
+
+const retrieve: Semantics = async (ctx) => {
+  const c = ctx.get(CN, at(ctx, 'id'));
+  return c ? ctx.reply(c) : noteMissing(ctx, at(ctx, 'id'));
+};
+
+const lines: Semantics = async (ctx) => {
+  const c = ctx.get(CN, at(ctx, 'credit_note'));
+  if (!c) return noteMissing(ctx, at(ctx, 'credit_note'));
+  const l = c.lines as { data?: Row[] } | undefined;
+  const { page, hasMore } = paginate(Array.isArray(l?.data) ? l!.data! : [], ctx.params);
+  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
+};
+
+const voidNote: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  const c = ctx.get(CN, id);
+  if (!c) return noteMissing(ctx, id);
+  const refused = ctx.legal(CN, 'status', 'PostCreditNotesIdVoid', c.status, undefined, id);
+  if (refused) return ctx.refuse(refused);
+  const voided = await ctx.write(CN, id, { status: 'void', voided_at: ctx.now() }, 'credit_note.void');
+  if (typeof c.invoice === 'string') await syncInvoice(ctx, c.invoice);
+  return ctx.reply(voided);
+};
+
+// only the memo and metadata change
+const update: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  if (!ctx.get(CN, id)) return noteMissing(ctx, id);
+  const patch: Row = {};
+  if (ctx.params.memo !== undefined) patch.memo = ctx.params.memo;
+  if (ctx.params.metadata !== undefined) patch.metadata = ctx.params.metadata;
+  return ctx.reply(await ctx.write(CN, id, patch, 'credit_note.update'));
+};
+
+export const creditNotes: Record<string, Semantics> = {
+  GetCreditNotesPreview: preview,
+  PostCreditNotes: create,
+  GetCreditNotesId: retrieve,
+  GetCreditNotesCreditNoteLines: lines,
+  PostCreditNotesIdVoid: voidNote,
+  PostCreditNotesId: update,
+};

package/src/semantics/customers.ts

@@ -0,0 +1,432 @@
+// Customer semantics: the customer and what hangs off it (tax ids, the credit-balance ledger, the
+// cash balance, legacy sources, attached payment methods) and the top-level Source object. List,
+// update and delete of a customer, retrieve of a Source and the flat tax-id list are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { buildDiscount } from '../stripe-twin.ts';
+import { invoicePrefix } from './invoices.ts';
+import { mintCharge } from './payment-intents.ts';
+import { attachable, attachPaymentMethod } from './payment-methods.ts';
+import { at, created, deletedDiscount, expanded, fail, list, newest, redeemCoupon, search, where, type Row } from './shared.ts';
+
+const customerMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such customer: '${id}'`, 404, 'resource_missing');
+
+/** The discount a customer's `coupon` makes, a parameter of API versions before the served one. */
+function customerDiscount(ctx: SemanticsContext, couponId: string): Row | Response {
+  const coupon = ctx.get('coupon', couponId);
+  return coupon ? buildDiscount(coupon, '', Number(ctx.now())) : fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
+}
+
+/** 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: {} });
+
+const create: Semantics = async (ctx) => {
+  // a `coupon` on create materializes the discount object on the customer (the coupon must exist)
+  const couponId = typeof ctx.params.coupon === 'string' ? ctx.params.coupon : '';
+  const discount = couponId ? customerDiscount(ctx, couponId) : null;
+  if (discount instanceof Response) return discount;
+  // `payment_method` attaches that method to the new customer; it is not a field of the customer
+  // (docs.stripe.com/api/customers/create#create_customer-payment_method)
+  const pmId = typeof ctx.params.payment_method === 'string' ? ctx.params.payment_method : '';
+  if (pmId && !attachable(ctx, pmId)) return fail(ctx, `No such PaymentMethod: '${pmId}'`, 400, 'resource_missing');
+  const { coupon: _c, payment_method: _pm, ...rest } = ctx.params;
+  const id = ctx.mint('customer');
+  const customer = await created(ctx, 'customer', { ...rest, id }, { livemode: false, discount: discount ? { ...discount, customer: id } : null, ...newCustomer(id) });
+  if (discount) await redeemCoupon(ctx, couponId);
+  if (pmId) await attachPaymentMethod(ctx, pmId, String(customer.id));
+  return ctx.reply(customer);
+};
+
+const searchCustomers: Semantics = async (ctx) => search(ctx, 'customer');
+
+// "If it’s for a deleted Customer, a subset of the customer’s information is returned, including a `deleted` property
+// that’s set to true" (docs.stripe.com/api/customers/retrieve)
+const retrieve: Semantics = async (ctx) => {
+  const id = at(ctx, 'customer');
+  const row = ctx.row('customer', id, { withDeleted: true });
+  if (!row) return customerMissing(ctx, id);
+  if (row.deleted === true) return ctx.reply({ id, object: 'customer', deleted: true });
+  return ctx.reply(expanded(ctx, 'customer', ctx.get('customer', id)!));
+};
+
+// the payment methods attached to a customer (customers.listPaymentMethods), optionally by `type`
+const paymentMethods: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  const items = where(ctx, newest(ctx, 'payment_method').filter((m) => m.customer === customer), { type: (m, v) => m.type === v });
+  return list(ctx, 'payment_method', items);
+};
+
+const paymentMethod: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  const m = ctx.get('payment_method', at(ctx, 'payment_method'));
+  return m && m.customer === customer ? ctx.reply(m) : fail(ctx, `No such PaymentMethod: '${at(ctx, 'payment_method')}'`, 404, 'resource_missing');
+};
+
+// removing the customer's discount answers the deleted-discount stub
+const deleteDiscount: Semantics = async (ctx) => {
+  const id = at(ctx, 'customer');
+  const customer = ctx.get('customer', id);
+  if (!customer) return customerMissing(ctx, id);
+  const discount = customer.discount as Row | null | undefined;
+  if (!discount) return fail(ctx, `No active discount for customer: '${id}'`, 404, 'resource_missing');
+  await ctx.write('customer', id, { discount: null }, 'customer.update');
+  return ctx.reply(deletedDiscount(discount, ctx.now()));
+};
+
+// ── 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.
+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})$/,
+};
+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. */
+const AUTO_VALIDATED = new Set(['au_abn', 'eu_vat', 'gb_vat']);
+
+/** A tax ID for its owner: the account itself, or one of its customers. */
+async function makeTaxId(ctx: SemanticsContext, customer: string | undefined): Promise<Response> {
+  const { owner: _owner, ...params } = ctx.params;
+  if (params.type === undefined || params.type === '') return fail(ctx, 'Missing required param: type.', 400, 'parameter_missing');
+  if (params.value === undefined || params.value === '') return fail(ctx, 'Missing required param: value.', 400, 'parameter_missing');
+  const vatCountry = params.type === 'eu_vat' ? euVatCountry(String(params.value)) : undefined;
+  if (params.type === 'eu_vat' && !vatCountry) return ctx.refuse({ status: 400, code: 'tax_id_invalid', param: 'value', message: `Invalid value for eu_vat.` });
+  return ctx.reply(
+    await created(ctx, 'tax_id', { ...params, ...(customer ? { customer } : {}) }, {
+      livemode: false,
+      country: vatCountry ?? (typeof params.country === 'string' ? params.country : null),
+      owner: customer ? { type: 'customer', customer } : { type: 'self' },
+      verification: { status: AUTO_VALIDATED.has(String(params.type)) ? 'pending' : 'unavailable', verified_address: null, verified_name: null },
+    }),
+  );
+}
+
+const createTaxId: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  return makeTaxId(ctx, customer);
+};
+
+/** The owner a top-level tax-ID call names: the account itself unless `owner[type]=customer` names a customer
+ *  (docs.stripe.com/api/tax_ids/list: owner defaults to self). */
+function ownerOf(ctx: SemanticsContext): { customer?: string } | Response {
+  const owner = (ctx.params.owner ?? {}) as Row;
+  const type = String(owner.type ?? 'self');
+  if (type === 'self') return {};
+  if (type !== 'customer') return fail(ctx, `Invalid owner[type]: must be one of self or customer.`, 400, 'parameter_invalid_string_enum');
+  const customer = typeof owner.customer === 'string' ? owner.customer : '';
+  if (!customer) return fail(ctx, 'Missing required param: owner[customer].', 400, 'parameter_missing');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  return { customer };
+}
+
+const createOwnedTaxId: Semantics = async (ctx) => {
+  const owner = ownerOf(ctx);
+  return owner instanceof Response ? owner : makeTaxId(ctx, owner.customer);
+};
+
+const listOwnedTaxIds: Semantics = async (ctx) => {
+  const owner = ownerOf(ctx);
+  if (owner instanceof Response) return owner;
+  return list(ctx, 'tax_id', newest(ctx, 'tax_id').filter((t) => (owner.customer ? t.customer === owner.customer : !t.customer)));
+};
+
+const taxIds: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  return list(ctx, 'tax_id', newest(ctx, 'tax_id').filter((t) => t.customer === customer));
+};
+
+const taxId: Semantics = async (ctx) => {
+  const t = ctx.get('tax_id', at(ctx, 'id'));
+  return t && t.customer === at(ctx, 'customer') ? ctx.reply(t) : fail(ctx, `No such tax_id: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+};
+
+const deleteTaxId: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  const t = ctx.get('tax_id', id);
+  if (!t || t.customer !== at(ctx, 'customer')) return fail(ctx, `No such tax_id: '${id}'`, 404, 'resource_missing');
+  await ctx.write('tax_id', id, { deleted: true }, 'tax_id.delete');
+  return ctx.reply({ id, object: 'tax_id', deleted: true });
+};
+
+// ── the credit-balance ledger: a negative amount is a credit; `ending_balance` is the running sum,
+// mirrored onto the customer's `balance` ──
+
+const createBalanceTransaction: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  const params = ctx.params;
+  if (params.amount === undefined) return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
+  const amount = Number(params.amount);
+  if (!Number.isInteger(amount)) return fail(ctx, 'Invalid integer: amount.', 400, 'parameter_invalid_integer');
+  if (params.currency === undefined || params.currency === '') return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
+  const prior = ctx.rows('customer_balance_transaction').filter((t) => t.customer === customer).reduce((s, t) => s + (Number(t.amount) || 0), 0);
+  const ending = prior + amount;
+  const body = await created(ctx, 'customer_balance_transaction', { ...params, customer, amount }, {
+    ending_balance: ending, type: 'adjustment', livemode: false, metadata: {},
+    description: params.description ?? null, credit_note: null, invoice: null, checkout_session: null,
+  });
+  // keyed by the new transaction so two adjustments at one instant are two writes, the last winning
+  await ctx.write('customer', customer, { balance: ending }, `customer.balance_adjusted:${String(body.id)}`);
+  return ctx.reply(body);
+};
+
+const balanceTransactions: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  return list(ctx, 'customer_balance_transaction', newest(ctx, 'customer_balance_transaction').filter((t) => t.customer === customer));
+};
+
+const balanceTransaction: Semantics = async (ctx) => {
+  const t = ctx.get('customer_balance_transaction', at(ctx, 'transaction'));
+  return t && t.customer === at(ctx, 'customer') ? ctx.reply(t) : fail(ctx, `No such balance transaction: '${at(ctx, 'transaction')}'`, 404, 'resource_missing');
+};
+
+// ── the cash balance: per-currency sums of the funding ledger, and the reconciliation setting ──
+
+function cashBalance(ctx: SemanticsContext, customer: string): Row {
+  const byCurrency: Record<string, number> = {};
+  for (const t of ctx.rows('customer_cash_balance_transaction')) {
+    if (t.customer !== customer) continue;
+    const cur = String(t.currency ?? 'usd');
+    byCurrency[cur] = (byCurrency[cur] ?? 0) + (Number(t.net_amount) || 0);
+  }
+  const cust = ctx.row('customer', customer);
+  const mode = typeof cust?._cash_balance_mode === 'string' ? cust._cash_balance_mode : 'automatic';
+  return {
+    object: 'cash_balance', customer,
+    available: Object.keys(byCurrency).length ? byCurrency : null,
+    settings: { reconciliation_mode: mode, using_merchant_default: mode === 'merchant_default' },
+    livemode: false,
+  };
+}
+
+const getCashBalance: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  return ctx.reply(cashBalance(ctx, customer));
+};
+
+const updateCashBalance: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  const settings = ctx.params.settings && typeof ctx.params.settings === 'object' ? (ctx.params.settings as Row) : {};
+  const mode = typeof settings.reconciliation_mode === 'string' ? settings.reconciliation_mode : 'automatic';
+  if (!['automatic', 'manual', 'merchant_default'].includes(mode)) return fail(ctx, 'Invalid settings[reconciliation_mode].', 400, 'parameter_invalid_string_enum');
+  await ctx.write('customer', customer, { _cash_balance_mode: mode }, 'cash_balance.updated');
+  return ctx.reply(cashBalance(ctx, customer));
+};
+
+const cashBalanceTransactions: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  return list(ctx, 'customer_cash_balance_transaction', newest(ctx, 'customer_cash_balance_transaction').filter((t) => t.customer === customer));
+};
+
+/** Automatic reconciliation (docs.stripe.com/payments/customer-balance/reconciliation): funds that arrive pay the
+ *  customer's open invoices that take bank transfers (payment_method_types customer_balance), the one whose number
+ *  the transfer's reference names first, then the oldest. Where the documentation stops and the twin decides: an
+ *  invoice is paid only when the balance covers all of what remains; a smaller balance waits for more funds. */
+async function reconcile(ctx: SemanticsContext, customer: string, currency: string, reference: string | null): Promise<void> {
+  const takesTransfers = (inv: Row): boolean => ((inv.payment_settings as Row | undefined)?.payment_method_types as unknown[] | undefined)?.includes('customer_balance') === true;
+  const open = ctx.rows('invoice').filter((inv) => inv.customer === customer && inv.status === 'open' && String(inv.currency ?? 'usd') === currency && takesTransfers(inv))
+    .sort((a, b) => (reference && a.number === reference ? -1 : reference && b.number === reference ? 1 : Number(a.created) - Number(b.created)));
+  for (const inv of open) {
+    const available = Number(((cashBalance(ctx, customer).available as Row | null) ?? {})[currency] ?? 0);
+    const amount = Number(inv.amount_remaining ?? inv.amount_due) || 0;
+    if (amount <= 0 || available < amount) continue;
+    const id = String(inv.id);
+    if (ctx.legal('invoice', 'status', 'PostTestHelpersCustomersCustomerFundCashBalance', inv.status, 'paid', id)) continue;
+    // the payment the balance makes: the invoice's own PaymentIntent (every invoice finalized with an amount due has one,
+    // semantics/invoices.ts), paid from the cash balance, its charge, and the ledger's entry
+    const piId = String(inv.payment_intent);
+    await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'applied_to_payment', net_amount: -amount, ending_balance: available - amount, applied_to_payment: { payment_intent: piId }, livemode: false });
+    const charge = await mintCharge(ctx, piId, { currency, customer, invoice: id }, amount);
+    await ctx.write('payment_intent', piId, { status: 'succeeded', amount_received: amount, latest_charge: charge }, 'payment_intent.succeeded');
+    await ctx.write('invoice', id, {
+      status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0, payment_intent: piId, charge,
+      status_transitions: { ...((inv.status_transitions as Row | undefined) ?? {}), paid_at: ctx.now() },
+    }, 'invoice.paid');
+  }
+}
+
+// test mode's stand-in for a bank transfer arriving (docs.stripe.com/payments/customer-balance/funding#test):
+// the customer's cash balance is funded by `amount`, and in automatic reconciliation the funds pay what waits on them
+const fundCashBalance: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  const amount = Math.trunc(Number(ctx.params.amount) || 0);
+  if (amount <= 0) return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
+  const currency = typeof ctx.params.currency === 'string' ? ctx.params.currency : '';
+  if (!currency) return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
+  const before = Number(((cashBalance(ctx, customer).available as Row | null) ?? {})[currency] ?? 0);
+  const reference = typeof ctx.params.reference === 'string' ? ctx.params.reference : null;
+  const funded = await created(ctx, 'customer_cash_balance_transaction', { customer }, {
+    currency, type: 'funded', net_amount: amount, ending_balance: before + amount, livemode: false,
+    funded: { bank_transfer: { reference, type: 'us_bank_transfer', us_bank_transfer: { network: 'ach', sender_name: null } } },
+  });
+  if ((cashBalance(ctx, customer).settings as Row).reconciliation_mode !== 'manual') await reconcile(ctx, customer, currency, reference);
+  return ctx.reply(funded);
+};
+
+const cashBalanceTransaction: Semantics = async (ctx) => {
+  const t = ctx.get('customer_cash_balance_transaction', at(ctx, 'transaction'));
+  return t && t.customer === at(ctx, 'customer') ? ctx.reply(t) : fail(ctx, `No such cash balance transaction: '${at(ctx, 'transaction')}'`, 404, 'resource_missing');
+};
+
+// ── legacy sources: attaching a token mints a card with only the safe fields; the first becomes
+// the customer's default_source, and detaching the default promotes the next ──
+
+const attachSource: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  const c = ctx.get('customer', customer);
+  if (!c) return customerMissing(ctx, customer);
+  const src = typeof ctx.params.source === 'string' ? ctx.params.source : '';
+  if (!src) return fail(ctx, 'Missing required param: source.', 400, 'parameter_missing');
+  // a card token becomes the card it carries, the token spent: "you can only use tokens once" (the served spec's
+  // token.used); any other source reference keeps the twin's stand-in card
+  const token = src.startsWith('tok_') ? ctx.get('token', src) : undefined;
+  if (token?.used === true) return fail(ctx, `You cannot use a Stripe token more than once: ${src}.`, 400, 'token_already_used');
+  const tokenCard = token?.card && typeof token.card === 'object' ? (token.card as Row) : undefined;
+  const last4 = String(4242 + ctx.rows('source').length + 1).slice(-4);
+  const body = await created(ctx, 'source', { customer, ...(tokenCard ? { id: String(tokenCard.id) } : {}) }, tokenCard
+    ? { ...tokenCard, customer, _source_token: src }
+    : { object: 'card', last4, brand: 'Visa', exp_month: 12, exp_year: 2030, funding: 'credit', country: 'US', metadata: {}, _source_token: src });
+  if (token) await ctx.write('token', src, { used: true }, 'token.used');
+  const existing = ctx.rows('source').filter((s) => s.customer === customer);
+  if (!c.default_source || existing.length === 1) await ctx.write('customer', customer, { default_source: body.id }, 'customer.updated');
+  return ctx.reply(body);
+};
+
+const sources: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
+  const items = newest(ctx, 'source').filter((s) => s.customer === customer);
+  return list(ctx, 'source', typeof ctx.params.object === 'string' ? items.filter((s) => s.object === ctx.params.object) : items);
+};
+
+/** The customer's source the path names, or undefined. */
+const customerSource = (ctx: SemanticsContext): Row | undefined => {
+  const s = ctx.get('source', at(ctx, 'id'));
+  return s && s.customer === at(ctx, 'customer') ? s : undefined;
+};
+const sourceMissing = (ctx: SemanticsContext): Response => fail(ctx, `No such source: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+
+const source: Semantics = async (ctx) => {
+  const s = customerSource(ctx);
+  return s ? ctx.reply(s) : sourceMissing(ctx);
+};
+
+const updateSource: Semantics = async (ctx) => {
+  if (!customerSource(ctx)) return sourceMissing(ctx);
+  return ctx.reply(await ctx.write('source', at(ctx, 'id'), ctx.params, 'source.updated'));
+};
+
+const detachSource: Semantics = async (ctx) => {
+  const customer = at(ctx, 'customer');
+  const id = at(ctx, 'id');
+  const c = ctx.get('customer', customer);
+  const s = customerSource(ctx);
+  if (!c || !s) return sourceMissing(ctx);
+  await ctx.write('source', id, { deleted: true, customer: null }, 'source.detached');
+  if (c.default_source === id) {
+    const remaining = ctx.rows('source').filter((x) => x.customer === customer && x.id !== id);
+    await ctx.write('customer', customer, { default_source: remaining[0]?.id ?? null }, 'customer.updated');
+  }
+  return ctx.reply({ id, object: s.object ?? 'card', deleted: true });
+};
+
+// ── the top-level Source: `type` is required; a card is chargeable at once, anything else pending ──
+
+const createSource: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const srcType = typeof params.type === 'string' ? params.type : '';
+  if (!srcType) return fail(ctx, 'Missing required param: type.', 400, 'parameter_missing');
+  return ctx.reply(
+    await created(ctx, 'source', { customer: null }, {
+      object: 'source',
+      status: srcType === 'card' ? 'chargeable' : 'pending',
+      flow: srcType === 'card' ? 'none' : 'receiver',
+      usage: (params.usage as string) ?? 'reusable',
+      currency: typeof params.currency === 'string' ? params.currency : null,
+      livemode: false,
+      type: srcType,
+      client_secret: `src_client_secret_twin_${ctx.rows('source').length + 1}`,
+      owner: params.owner && typeof params.owner === 'object' ? params.owner : { name: null, email: null, address: null, phone: null, verified_name: null, verified_email: null, verified_address: null, verified_phone: null },
+      metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
+      statement_descriptor: null,
+      ...(srcType === 'ach_credit_transfer' ? achCreditTransfer(ctx) : {}),
+    }),
+  );
+};
+
+/** An ACH credit transfer source's account for the customer to wire to, and its receiver flow, as the sources create
+ *  page's example answers one (docs.stripe.com/api/sources/create): a test account number, "TEST BANK", routing
+ *  110000000 and SWIFT TSTEZ122; the receiver's address "routing-account" with nothing yet charged, received or
+ *  returned, refund attributes by email and missing. Where the documentation stops and the twin decides: the account
+ *  number is the source's own. */
+function achCreditTransfer(ctx: SemanticsContext): Row {
+  const account = `test_${String(ctx.rows('source').length + 1).padStart(12, '0')}`;
+  return {
+    ach_credit_transfer: { account_number: account, bank_name: 'TEST BANK', fingerprint: `twin_acct_${account}`, refund_account_holder_name: null, refund_account_holder_type: null, refund_routing_number: null, routing_number: '110000000', swift_code: 'TSTEZ122' },
+    receiver: { address: `110000000-${account}`, amount_charged: 0, amount_received: 0, amount_returned: 0, refund_attributes_method: 'email', refund_attributes_status: 'missing' },
+  };
+}
+
+// a Source update changes only its metadata and owner
+const updateTopSource: Semantics = async (ctx) => {
+  const id = at(ctx, 'source');
+  if (!ctx.get('source', id)) return fail(ctx, `No such source: '${id}'`, 404, 'resource_missing');
+  const patch: Row = {};
+  if (ctx.params.metadata !== undefined) patch.metadata = ctx.params.metadata;
+  if (ctx.params.owner !== undefined) patch.owner = ctx.params.owner;
+  return ctx.reply(await ctx.write('source', id, patch, 'source.updated'));
+};
+
+export const customers: Record<string, Semantics> = {
+  PostCustomers: create,
+  GetCustomersCustomer: retrieve,
+  GetCustomersSearch: searchCustomers,
+  GetCustomersCustomerPaymentMethods: paymentMethods,
+  GetCustomersCustomerPaymentMethodsPaymentMethod: paymentMethod,
+  DeleteCustomersCustomerDiscount: deleteDiscount,
+  PostCustomersCustomerTaxIds: createTaxId,
+  PostTaxIds: createOwnedTaxId,
+  GetTaxIds: listOwnedTaxIds,
+  GetCustomersCustomerTaxIds: taxIds,
+  GetCustomersCustomerTaxIdsId: taxId,
+  DeleteCustomersCustomerTaxIdsId: deleteTaxId,
+  PostCustomersCustomerBalanceTransactions: createBalanceTransaction,
+  GetCustomersCustomerBalanceTransactions: balanceTransactions,
+  GetCustomersCustomerBalanceTransactionsTransaction: balanceTransaction,
+  GetCustomersCustomerCashBalance: getCashBalance,
+  PostCustomersCustomerCashBalance: updateCashBalance,
+  GetCustomersCustomerCashBalanceTransactions: cashBalanceTransactions,
+  GetCustomersCustomerCashBalanceTransactionsTransaction: cashBalanceTransaction,
+  PostTestHelpersCustomersCustomerFundCashBalance: fundCashBalance,
+  PostCustomersCustomerSources: attachSource,
+  GetCustomersCustomerSources: sources,
+  GetCustomersCustomerSourcesId: source,
+  PostCustomersCustomerSourcesId: updateSource,
+  DeleteCustomersCustomerSourcesId: detachSource,
+  PostSources: createSource,
+  PostSourcesSource: updateTopSource,
+};