@volter/twin-stripe 2.0.38 → 3.0.1

package/src/semantics/coupons.ts

@@ -1,20 +1,8 @@
-// Coupon and PromotionCode semantics. A coupon is exactly one of percent_off or amount_off (with
-// its currency) over a duration; a promotion code is a customer-facing code for an existing
-// coupon, active until switched off (the machine in ../manifest.ts). Coupon list, retrieve, update
-// and delete and promotion-code retrieve and update (`active`, the machine) are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { asBool } from '../stripe-twin.ts';
-import { at, at_, created, fail, list, newest, where, type Row } from './shared.ts';
-
-/** A coupon for a fixed amount off, in its currency (docs.stripe.com/api/coupons/create#create_coupon-amount_off). */
-function amountOffOf(ctx: SemanticsContext, params: Record<string, unknown>): number | Response {
-  const amountOff = Number(params.amount_off);
-  if (!Number.isInteger(amountOff) || amountOff <= 0) return fail(ctx, 'Invalid integer: amount_off must be a positive integer.', 400, 'parameter_invalid_integer');
-  if (params.currency === undefined || params.currency === '') return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
-  return amountOff;
-}
-
-const createCoupon: Semantics = async (ctx) => {
+// Stripe's coupons operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { amountOffOf, created, fail } from './shared.ts';
+export async function PostCoupons(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
   const hasPct = params.percent_off !== undefined;
   const hasAmt = params.amount_off !== undefined;
@@ -43,55 +31,4 @@ const createCoupon: Semantics = async (ctx) => {
       applies_to: null,
     }),
   );
-};
-
-// a code the caller does not give is derived from the promotion code's id
-const createPromotionCode: Semantics = async (ctx) => {
-  // what it promotes: promotion[type]=coupon and promotion[coupon] (2025-09-30.clover,
-  // docs.stripe.com/changelog/clover/2025-09-30/polymorphic-coupon), or the top-level coupon a caller pinned to an
-  // earlier version sends; the twin keeps the coupon's id on the code for its rules
-  const { promotion, coupon: legacy, ...params } = ctx.params;
-  const promo = promotion && typeof promotion === 'object' ? (promotion as Record<string, unknown>) : undefined;
-  if (promo && promo.type !== 'coupon') return fail(ctx, 'Invalid promotion[type]: must be coupon.', 400, 'parameter_invalid_string_enum');
-  const coupon = typeof promo?.coupon === 'string' ? promo.coupon : typeof legacy === 'string' ? legacy : '';
-  if (!coupon) return fail(ctx, promo ? 'Missing required param: promotion[coupon].' : 'Missing required param: promotion.', 400, 'parameter_missing');
-  if (!ctx.get('coupon', coupon)) return fail(ctx, `No such coupon: '${coupon}'`, 400, 'resource_missing');
-  const id = ctx.mint('promotion_code');
-  const code = typeof params.code === 'string' && params.code ? params.code : `TWIN${id.toUpperCase().replace(/[^A-Z0-9]/g, '')}`;
-  return ctx.reply(
-    await created(ctx, 'promotion_code', { ...params, coupon, promotion: { type: 'coupon', coupon }, id, code }, {
-      active: params.active !== undefined ? asBool(params.active) : true,
-      customer: typeof params.customer === 'string' ? params.customer : null,
-      expires_at: params.expires_at !== undefined ? Number(params.expires_at) : null,
-      max_redemptions: params.max_redemptions !== undefined ? Number(params.max_redemptions) : null,
-      times_redeemed: 0, livemode: false, metadata: {}, restrictions: { first_time_transaction: false, minimum_amount: null, minimum_amount_currency: null },
-    }),
-  );
-};
-
-/** Time's lapsing of coupons, caught up to the World's clock: a valid coupon whose redeem_by has passed is no longer
- *  valid from that moment (manifest.ts). Where the documentation stops and the twin decides: the lapse sends no event
- *  (the events page names none for it). */
-export async function lapseCoupons(ctx: SemanticsContext): Promise<void> {
-  const now = Number(ctx.now());
-  for (const c of ctx.rowsRaw('coupon')) {
-    if (c.valid !== true || typeof c.redeem_by !== 'number' || c.redeem_by > now) continue;
-    const t = await at_(ctx)(c.redeem_by);
-    t.legal('coupon', 'valid', ctx.call.operation.id, 'true', 'false', String(c.id), 'time');
-    await t.write('coupon', String(c.id), { valid: false }, 'coupon.lapsed');
-  }
 }
-
-const listPromotionCodes: Semantics = async (ctx) =>
-  list(ctx, 'promotion_code', where(ctx, newest(ctx, 'promotion_code'), {
-    code: (p, v) => p.code === v,
-    active: (p, v) => asBool(p.active) === asBool(v),
-    coupon: (p, v) => p.coupon === v,
-    customer: (p, v) => p.customer === v,
-  }));
-
-export const coupons: Record<string, Semantics> = {
-  PostCoupons: createCoupon,
-  PostPromotionCodes: createPromotionCode,
-  GetPromotionCodes: listPromotionCodes,
-};

package/src/semantics/customers.ts

@@ -1,432 +1,66 @@
-// 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');
-
+// Stripe's customers operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { newCustomer } from '../engine/customers.ts';
+import { nowUnix } from '../engine/stripe.ts';
+import { at, attachable, attachPaymentMethod, created, customerMissing, expanded, fail, search } from './shared.ts';
 // "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) => {
+export async function GetCustomersCustomer(ctx: HandlerContext): Promise<Response> {
   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,
-  };
+export async function GetCustomersSearch(ctx: HandlerContext): Promise<Response> {
+  return search(ctx, 'customer');
 }
 
-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');
+export async function PostCustomers(ctx: HandlerContext): Promise<Response> {
+  // `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 given = ctx.params;
+  const { coupon: _c, payment_method: _pm, ...rest } = given;
+  const id = ctx.mint('customer');
+  const customer = await created(ctx, 'customer', { ...rest, id }, { livemode: false, discount: null, ...newCustomer(id) });
+  // source: https://docs.stripe.com/billing/customer/balance "Represents the starting value of the customer invoice balance when a customer is created using the API with a non-zero invoice balance."
+  if (Number(customer.balance ?? 0) !== 0) {
+    await created(ctx, 'customer_balance_transaction', {
+      customer: id, amount: Number(customer.balance), ending_balance: Number(customer.balance),
+      currency: customer.currency ?? 'usd', type: 'initial', description: null, metadata: {},
+      livemode: false, invoice: null, credit_note: null, checkout_session: null, customer_account: null,
+    }, {});
   }
+  if (pmId) await attachPaymentMethod(ctx, pmId, String(customer.id));
+  return ctx.reply(customer);
 }
 
-// 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);
-};
+// ── the credit-balance ledger: a negative amount is a credit; `ending_balance` is the running sum,
+// mirrored onto the customer's `balance` ──
 
-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');
+// source: spec:PostCustomersCustomer "Updates the specified customer by setting the values of the parameters passed."
+export async function PostCustomersCustomer(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'customer');
+  const customer = ctx.get('customer', id);
+  if (!customer) return customerMissing(ctx, id);
+  const { customer: _pathCustomer, ...fields } = ctx.params;
+  // source: https://docs.stripe.com/billing/customer/balance "All modifications to the invoice balance are recorded as Transactions"
+  // source: https://docs.stripe.com/billing/customer/balance "All Transactions created with the API or in the Dashboard have a type value of adjustment"
+  if (typeof fields.balance === 'number' && fields.balance !== Number(customer.balance ?? 0)) {
+    const balance = fields.balance;
+    await created(ctx, 'customer_balance_transaction', {
+      customer: id, amount: balance - Number(customer.balance ?? 0), ending_balance: balance,
+      // Stripe inherits the customer's billing currency. Where no invoice has set it, this World's invoice currency is USD.
+      currency: customer.currency ?? 'usd', type: 'adjustment',
+      description: null, metadata: {}, livemode: false,
+      invoice: null, credit_note: null, checkout_session: null, customer_account: null,
+      created: nowUnix(ctx.occurredAt),
+    }, {});
   }
-  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' },
-  };
+  return ctx.reply(ctx.expand('customer', await ctx.write('customer', id, fields, 'customer.update')));
 }
-
-// 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,
-};