@volter/twin-stripe 2.0.38 → 3.0.0

package/src/semantics/customers.ts

@@ -1,26 +1,34 @@
-// 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';
+// 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 { deletedDiscount, type Row } from '../engine/common.ts';
+import { newCustomer } from '../engine/customers.ts';
+import { nowUnix } from '../engine/stripe.ts';
+import { at, attachable, attachPaymentMethod, cashBalance, created, customerDiscount, customerMissing, customerSource, expanded, fail, list, makeTaxId, newest, redeemCoupon, search, sourceMissing, where } from './shared.ts';
 
-const customerMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such customer: '${id}'`, 404, 'resource_missing');
+// "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)
+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 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');
+// the payment methods attached to a customer (customers.listPaymentMethods), optionally by `type`
+export async function GetCustomersCustomerPaymentMethods(ctx: HandlerContext): Promise<Response> {
+  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);
 }
 
-/** 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: {} });
+export async function GetCustomersSearch(ctx: HandlerContext): Promise<Response> {
+  return search(ctx, 'customer');
+}
 
-const create: Semantics = async (ctx) => {
+export async function PostCustomers(ctx: HandlerContext): Promise<Response> {
   // 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;
@@ -29,148 +37,18 @@ const create: Semantics = async (ctx) => {
   // (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 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: 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) => {
+export async function PostCustomersCustomerBalanceTransactions(ctx: HandlerContext): Promise<Response> {
   const customer = at(ctx, 'customer');
   if (!ctx.get('customer', customer)) return customerMissing(ctx, customer);
   const params = ctx.params;
@@ -187,246 +65,5 @@ const createBalanceTransaction: Semantics = async (ctx) => {
   // 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,
-};

package/src/semantics/disputes.ts

@@ -1,62 +1,12 @@
-// Dispute semantics. A dispute is Stripe's to open, when a charge's cardholder disputes it: the test cards
-// that are disputed open one as their charge succeeds (./after-payment.ts). It is then listed, retrieved,
-// updated with evidence and closed. Closing concedes it (status → lost), the machine's move in
-// ../manifest.ts. Evidence is submitted with the update unless `submit` is false
-// (docs.stripe.com/api/disputes/update#update_dispute-submit), and the bank then decides it: in test mode, evidence whose
-// uncategorized_text is `winning_evidence` wins it and `losing_evidence` loses it (docs.stripe.com/testing#evidence);
-// a won dispute returns the disputed amount. Where the documentation stops and the twin decides: the bank decides at
-// once, and any other evidence leaves the dispute under review. List is the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { asBool } from '../stripe-twin.ts';
-import { settleDisputeWon } from './ledger.ts';
-import { at, fail, type Row } from './shared.ts';
-
-const disputeMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such dispute: '${id}'`, 404, 'resource_missing');
-
-const retrieve: Semantics = async (ctx) => {
+// Stripe's disputes 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 type { Row } from '../engine/common.ts';
+import { asBool } from '../engine/stripe.ts';
+import { at, disputesDisputeMissing, keepEvidence, settleDisputeWon } from './shared.ts';
+
+export async function GetDisputesDispute(ctx: HandlerContext): Promise<Response> {
   const d = ctx.get('dispute', at(ctx, 'dispute'));
-  return d ? ctx.reply(d) : disputeMissing(ctx, at(ctx, 'dispute'));
-};
-
-const close: Semantics = async (ctx) => {
-  const id = at(ctx, 'dispute');
-  const d = ctx.get('dispute', id);
-  if (!d) return disputeMissing(ctx, id);
-  const refused = ctx.legal('dispute', 'status', 'PostDisputesDisputeClose', d.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  return ctx.reply(await ctx.write('dispute', id, { status: 'lost' }, 'dispute.close'));
-};
-
-/** Evidence staged without submitting it (submit=false), or on a dispute already under review or decided. */
-async function keepEvidence(ctx: SemanticsContext, id: string, fields: Row): Promise<Response> {
-  return ctx.reply(await ctx.write('dispute', id, fields, 'dispute.update'));
+  return d ? ctx.reply(d) : disputesDisputeMissing(ctx, at(ctx, 'dispute'));
 }
 
-const update: Semantics = async (ctx) => {
-  const id = at(ctx, 'dispute');
-  const d = ctx.get('dispute', id);
-  if (!d) return disputeMissing(ctx, id);
-  const params = ctx.params;
-  const given = params.evidence && typeof params.evidence === 'object' ? (params.evidence as Row) : {};
-  const evidence = { ...((d.evidence as Row | undefined) ?? {}), ...given };
-  const fields: Row = { evidence, ...(params.metadata && typeof params.metadata === 'object' ? { metadata: { ...((d.metadata as Row | undefined) ?? {}), ...(params.metadata as Row) } } : {}) };
-  const submit = params.submit === undefined ? true : asBool(params.submit);
-  const review = d.status === 'warning_needs_response' ? 'warning_under_review' : 'under_review';
-  if (!submit || ctx.legal('dispute', 'status', 'PostDisputesDispute', d.status, review, id)) return keepEvidence(ctx, id, fields);
-  const details = (d.evidence_details as Row | undefined) ?? {};
-  let body = await ctx.write('dispute', id, { ...fields, status: review, evidence_details: { ...details, has_evidence: true, submission_count: (Number(details.submission_count) || 0) + 1 } }, 'charge.dispute.updated');
-  const text = String(evidence.uncategorized_text ?? '');
-  const decided = review === 'under_review' ? (text.includes('winning_evidence') ? 'won' : text.includes('losing_evidence') ? 'lost' : undefined) : undefined;
-  if (decided && !ctx.legal('dispute', 'status', 'PostDisputesDispute', review, decided, id, 'vendor')) {
-    const bt = decided === 'won' ? await settleDisputeWon(ctx, id, Number(d.amount) || 0, String(d.currency ?? 'usd')) : undefined;
-    const kept = ((ctx.get('dispute', id)?.balance_transactions as unknown[] | undefined) ?? []);
-    body = await ctx.write('dispute', id, { status: decided, ...(bt ? { balance_transactions: [...kept, ctx.get('balance_transaction', bt) ?? bt] } : {}) }, 'charge.dispute.closed');
-  }
-  return ctx.reply(body);
-};
-
-export const disputes: Record<string, Semantics> = {
-  GetDisputesDispute: retrieve,
-  PostDisputesDispute: update,
-  PostDisputesDisputeClose: close,
-};

package/src/semantics/doors.ts

@@ -0,0 +1,80 @@
+// The World's doors (the manifest's `doors`): what stands in for an act Stripe's API does not have, each under /_twin/.
+import type { HandlerContext } from '@volter/world-core';
+import type { Row } from '../engine/common.ts';
+import { platformAccountDefault } from '../engine/connect.ts';
+import { accountSettings, nowUnix, PLATFORM_ACCOUNT_ID } from '../engine/stripe.ts';
+import { at, balanceBody, created, fail, payDuePayouts, settleDueEntries } from './shared.ts';
+
+/** The platform's own account settings (its payout schedule, its public name) change on Stripe's Dashboard, which has no
+ *  API: this stands in for that page. The account is Stripe's default until the page first changes it (the same default
+ *  GET /v1/account answers); a hash is merged into what the account holds, as an update merges it. */
+export async function account(ctx: HandlerContext): Promise<Response> {
+  const ex = ctx.get('account', PLATFORM_ACCOUNT_ID);
+  const given: Row = ctx.params;
+  const { type: _t, settings: rawSettings, business_profile: rawProfile, ...rest } = given;
+  const { id: _id, ...base } = platformAccountDefault();
+  const fields = {
+    ...(ex ? {} : base),
+    ...rest,
+    settings: accountSettings(rawSettings, ex?.settings as Row | undefined),
+    ...(rawProfile && typeof rawProfile === 'object' ? { business_profile: { ...((ex?.business_profile as Row | undefined) ?? {}), ...(rawProfile as Row) } } : {}),
+  };
+  return ctx.reply(await ctx.write('account', PLATFORM_ACCOUNT_ID, fields, 'account.update'));
+}
+
+/** Time's events, sent when a caller drives them (a runner's drainer): what time settled on each account is written —
+ *  payouts whose arrival date came (pending → paid, sent as payout.paid) and funds that came due (pending → available),
+ *  for which the account is sent one balance.available ("Occurs whenever your Stripe balance has been updated (e.g., when
+ *  a charge is available to be paid out)", docs.stripe.com/api/events/types) carrying its Balance, when an entry that
+ *  settled adds to it ("This event is not fired for negative transactions", the same page); a connected account's
+ *  events go to Connect endpoints. A read already sees these moves; the drain is what makes Stripe's events about them
+ *  arrive. Answers what it sent. */
+export async function drain(ctx: HandlerContext): Promise<Response> {
+  const accounts = [undefined, ...ctx.rows('account').map((a) => String(a.id)).filter((id) => id !== PLATFORM_ACCOUNT_ID)];
+  const delivered: Array<{ type: string; id?: string; account?: string }> = [];
+  for (const account of accounts) {
+    for (const id of await payDuePayouts(ctx, account)) delivered.push({ type: 'payout.paid', id, ...(account ? { account } : {}) });
+    if ((await settleDueEntries(ctx, account)).some((t) => Number(t.net) > 0)) {
+      // the notice the event is sent for: the account's Balance, which has no id of its own (./events.ts renders it)
+      await ctx.write('_balance_notice', `${account ?? PLATFORM_ACCOUNT_ID}:${ctx.occurredAt}`, { account: account ?? null, balance: balanceBody(ctx, account) }, 'balance.available');
+      delivered.push({ type: 'balance.available', ...(account ? { account } : {}) });
+    }
+  }
+  return Response.json({ delivered });
+}
+
+/** POST /_twin/app-credentials: the platform's API keys as the dashboard's API keys page shows them, a secret key and a
+ *  publishable key (`sk_test_…`, `pk_test_…`), held by their SHA-256, and the signing secrets its webhook endpoints
+ *  are made with. The runtime issues them to a World's applications at every boot (the descriptor's credentialDoor), so
+ *  the answer is the same each time: the account's one pair of keys, made the first time. Where the documentation
+ *  stops: the keys' length and alphabet after the prefix. */
+// source: https://docs.stripe.com/keys "Publishable keys"
+export async function appCredentials(ctx: HandlerContext): Promise<Response> {
+  const secretKey = `sk_test_51${(await ctx.secret('stripe-platform-key:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 96)}`;
+  const publishableKey = `pk_test_51${(await ctx.secret('stripe-publishable-key:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 96)}`;
+  if (!ctx.rowsRaw('_platform_key').some((k) => k.id === 'secret:app' && k._sha256 === ctx.crypto.sha256(secretKey))) {
+    await ctx.record('_platform_key', { kind: 'secret', _sha256: ctx.crypto.sha256(secretKey), created: ctx.occurredAt, deleted: false }, 'secret:app');
+    await ctx.record('_platform_key', { kind: 'publishable', _sha256: ctx.crypto.sha256(publishableKey), created: ctx.occurredAt, deleted: false }, 'publishable:app');
+  }
+  // the signing secrets the application verifies its webhooks with, its account's and its Connect endpoint's: an
+  // endpoint made for it (the webhookEndpoints door) is signed with the one of its kind, so the two agree
+  return Response.json({ secret_key: secretKey, publishable_key: publishableKey, webhook_secret: await appEndpointSecret(ctx, false), connect_webhook_secret: await appEndpointSecret(ctx, true) }, { status: 201 });
+}
+
+/** The signing secret the World's application is issued for its account's endpoints, or for its Connect endpoint. */
+const appEndpointSecret = async (ctx: HandlerContext, connect: boolean): Promise<string> =>
+  `whsec_${(await ctx.secret(connect ? 'stripe-webhook-secret:connect' : 'stripe-webhook-secret:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 32)}`;
+
+/** POST /_twin/webhook-endpoints {url, events, connect?}: an endpoint added on the Dashboard's Webhooks page, the events
+ *  it takes, signed with the secret the World's application is issued (./doors.ts `appCredentials`): the twin's
+ *  decision, since Stripe mints an endpoint's secret and lets no one choose one. */
+// source: https://docs.stripe.com/webhooks "register a webhook endpoint, Stripe pushes real-time data to it when"
+export async function webhookEndpoints(ctx: HandlerContext): Promise<Response> {
+  const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {}) as Record<string, unknown>;
+  if (typeof b.url !== 'string' || !/^https?:\/\//.test(b.url) || !Array.isArray(b.events) || !b.events.length) return Response.json({ error: 'a url and its events are required' }, { status: 400 });
+  const connect = b.connect === true;
+  const id = ctx.mint('webhook_endpoint');
+  const secret = await appEndpointSecret(ctx, connect);
+  await ctx.write('webhook_endpoint', id, { id, object: 'webhook_endpoint', url: b.url, enabled_events: b.events.map(String), status: 'enabled', connect, livemode: false, metadata: {}, api_version: null, application: null, description: null, secret, created: Math.floor(Date.parse(ctx.occurredAt) / 1000) }, 'webhook_endpoint.create');
+  return Response.json({ id, secret }, { status: 201 });
+}