@volter/twin-stripe 0.1.1 → 2.0.0

package/src/semantics/tax.ts

@@ -0,0 +1,220 @@
+// Stripe Tax semantics: tax rates, the account's tax settings (a singleton), calculations,
+// registrations, and the transactions that commit a calculation or reverse one. A calculation's
+// tax comes from one flat default rate so its amounts are stable (Stripe derives it from the
+// customer's jurisdiction and the account's registrations). Rate, calculation, registration and
+// transaction retrieves and the registration list are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { asBool, lineItemEntries, paginate } from '../stripe-twin.ts';
+import { at, created, fail, list, newest, path, where, type Row } from './shared.ts';
+
+const TWIN_TAX_RATE_PCT = 10;
+
+const createRate: Semantics = async (ctx) => {
+  const params = ctx.params;
+  if (params.display_name === undefined || params.display_name === '') return fail(ctx, 'Missing required param: display_name.', 400, 'parameter_missing');
+  if (params.percentage === undefined) return fail(ctx, 'Missing required param: percentage.', 400, 'parameter_missing');
+  if (params.inclusive === undefined) return fail(ctx, 'Missing required param: inclusive.', 400, 'parameter_missing');
+  return ctx.reply(
+    await created(ctx, 'tax_rate', { ...params, inclusive: asBool(params.inclusive), percentage: Number(params.percentage) }, {
+      active: true, livemode: false, metadata: {},
+      country: null, state: null, jurisdiction: typeof params.jurisdiction === 'string' ? params.jurisdiction : null,
+      jurisdiction_level: null, description: params.description ?? null, display_name: params.display_name,
+      tax_type: null,
+    }),
+  );
+};
+
+const listRates: Semantics = async (ctx) =>
+  list(ctx, 'tax_rate', where(ctx, newest(ctx, 'tax_rate'), {
+    active: (t, v) => asBool(t.active) === asBool(v),
+    inclusive: (t, v) => asBool(t.inclusive) === asBool(v),
+  }));
+
+// percentage and inclusive are fixed once created
+const updateRate: Semantics = async (ctx) => {
+  const id = at(ctx, 'tax_rate');
+  if (!ctx.get('tax_rate', id)) return ctx.notFound('tax_rate', id);
+  const { percentage: _p, inclusive: _i, ...rest } = ctx.params;
+  return ctx.reply(await ctx.write('tax_rate', id, { ...rest, ...('active' in rest ? { active: asBool(rest.active) } : {}) }, 'tax_rate.update'));
+};
+
+// ── settings: active once a head office is set; the answer has no id ──
+
+// the defaults' provider: "The tax calculation provider this account uses. Defaults to `stripe` when not using a
+// third-party provider" (the served spec's tax settings defaults); the head office's address answers each line, the
+// lines not given null (the served spec's address: each "(string, nullable)"; the settings page's example answers
+// line2 null)
+const ADDRESS_LINES = ['city', 'country', 'line1', 'line2', 'postal_code', 'state'];
+function settingsBody(stored: Row | undefined): Row {
+  const given = (stored?.head_office ?? null) as Row | null;
+  const address = given && typeof given.address === 'object' && given.address ? (given.address as Row) : undefined;
+  const headOffice = given ? { ...given, ...(address ? { address: Object.fromEntries(ADDRESS_LINES.map((k) => [k, address[k] ?? null])) } : {}) } : null;
+  const active = !!headOffice;
+  return {
+    object: 'tax.settings', livemode: false,
+    defaults: { provider: 'stripe', ...((stored?.defaults as Row) ?? { tax_behavior: null, tax_code: null }) }, head_office: headOffice,
+    status: active ? 'active' : 'pending',
+    status_details: active ? { active: {} } : { pending: { missing_fields: ['head_office'] } },
+  };
+}
+
+const getSettings: Semantics = async (ctx) => ctx.reply(settingsBody(ctx.rows('tax.settings')[0]));
+
+const updateSettings: Semantics = async (ctx) => {
+  const existing = ctx.rows('tax.settings')[0];
+  const cur = existing ?? {};
+  const defaults = ctx.params.defaults && typeof ctx.params.defaults === 'object' ? (ctx.params.defaults as Row) : {};
+  const curDefaults = (cur.defaults as Row) ?? {};
+  const headOffice = ctx.params.head_office && typeof ctx.params.head_office === 'object' ? (ctx.params.head_office as Row) : undefined;
+  const fields = {
+    defaults: {
+      tax_behavior: typeof defaults.tax_behavior === 'string' ? defaults.tax_behavior : (curDefaults.tax_behavior ?? null),
+      tax_code: typeof defaults.tax_code === 'string' ? defaults.tax_code : (curDefaults.tax_code ?? null),
+    },
+    head_office: headOffice ?? cur.head_office ?? null,
+    livemode: false,
+  };
+  const body = await ctx.write('tax.settings', existing ? String(existing.id) : 'taxset_twin_1', fields, existing ? 'tax_settings.update' : 'tax_settings.create');
+  return ctx.reply(settingsBody(body));
+};
+
+// ── calculations: each line's tax on top of its amount; no `created`, a tax_date instead ──
+
+const calcMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such tax calculation: '${id}'`, 404, 'resource_missing');
+
+const calculate: Semantics = async (ctx) => {
+  const params = ctx.params;
+  if (params.currency === undefined || params.currency === '') return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
+  const entries = lineItemEntries(params);
+  if (entries.length === 0) return fail(ctx, 'Missing required param: line_items.', 400, 'parameter_missing');
+  const now = Number(ctx.now());
+  const id = ctx.mint('tax.calculation');
+  const items = entries.map((e, i) => {
+    const amount = Math.max(0, Math.trunc(Number(e.amount) || 0));
+    return {
+      object: 'tax.calculation_line_item', id: `tax_li_${id}_${i + 1}`,
+      amount, amount_tax: Math.round((amount * TWIN_TAX_RATE_PCT) / 100), reference: typeof e.reference === 'string' ? e.reference : null,
+      tax_behavior: 'exclusive', tax_code: typeof e.tax_code === 'string' ? e.tax_code : 'txcd_99999999',
+      quantity: e.quantity === undefined ? 1 : Math.max(1, Math.trunc(Number(e.quantity) || 1)), livemode: false,
+    };
+  });
+  const amountSubtotal = items.reduce((s, it) => s + it.amount, 0);
+  const taxExclusive = items.reduce((s, it) => s + it.amount_tax, 0);
+  const cd = params.customer_details && typeof params.customer_details === 'object' ? (params.customer_details as Row) : {};
+  return ctx.reply(
+    await created(ctx, 'tax.calculation', {
+      id, currency: String(params.currency), amount_total: amountSubtotal + taxExclusive, tax_amount_exclusive: taxExclusive, tax_amount_inclusive: 0,
+      customer: typeof params.customer === 'string' ? params.customer : null,
+      customer_details: {
+        address: cd.address ?? null, address_source: cd.address_source ?? 'shipping', ip_address: cd.ip_address ?? null,
+        tax_ids: Array.isArray(cd.tax_ids) ? cd.tax_ids : [], taxability_override: cd.taxability_override ?? 'none',
+      },
+      line_items: { object: 'list', data: items, has_more: false, url: `/v1/tax/calculations/${id}/line_items` },
+      shipping_cost: null, tax_date: now,
+      tax_breakdown: taxExclusive > 0 ? [{
+        amount: taxExclusive, inclusive: false, taxability_reason: 'standard_rated', taxable_amount: amountSubtotal,
+        tax_rate_details: { country: null, percentage_decimal: String(TWIN_TAX_RATE_PCT), state: null, tax_type: 'sales_tax' },
+      }] : [],
+      expires_at: now + 90 * 24 * 3600, livemode: false,
+    }, {}, { timeField: 'tax_date' }),
+  );
+};
+
+/** A page of the line items a stored object carries. */
+function linePage(ctx: SemanticsContext, holder: Row): Response {
+  const li = holder.line_items as { data?: Row[] } | undefined;
+  const { page, hasMore } = paginate(Array.isArray(li?.data) ? li!.data! : [], ctx.params);
+  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
+}
+
+const calculationLines: Semantics = async (ctx) => {
+  const c = ctx.get('tax.calculation', at(ctx, 'calculation'));
+  return c ? linePage(ctx, c) : calcMissing(ctx, at(ctx, 'calculation'));
+};
+
+// ── registrations ──
+
+const register: Semantics = async (ctx) => {
+  const params = ctx.params;
+  if (params.country === undefined || params.country === '') return fail(ctx, 'Missing required param: country.', 400, 'parameter_missing');
+  if (params.active_from === undefined) return fail(ctx, 'Missing required param: active_from.', 400, 'parameter_missing');
+  const now = Number(ctx.now());
+  const activeFrom = params.active_from === 'now' ? now : Number(params.active_from) || now;
+  return ctx.reply(
+    await created(ctx, 'tax.registration', { ...params, active_from: activeFrom }, {
+      status: 'active', expires_at: null, livemode: false,
+      country_options: params.country_options && typeof params.country_options === 'object' ? params.country_options : {},
+    }),
+  );
+};
+
+// ── transactions: committing a calculation, or reversing a transaction with negated amounts ──
+
+const TX = 'tax.transaction';
+const txMissing = (ctx: SemanticsContext, id: string, status = 404): Response => fail(ctx, `No such tax transaction: '${id}'`, status, 'resource_missing');
+const txLine = (id: string, i: number, l: Row, sign: 1 | -1, reversal: Row | null, type: string): Row => ({
+  object: 'tax.transaction_line_item', id: `tax_li_${id}_${i + 1}`,
+  amount: sign === 1 ? l.amount : -(Number(l.amount) || 0), amount_tax: sign === 1 ? l.amount_tax : -(Number(l.amount_tax) || 0),
+  reference: l.reference ?? null, tax_behavior: l.tax_behavior ?? 'exclusive', tax_code: l.tax_code ?? 'txcd_99999999',
+  quantity: l.quantity ?? 1, reversal, type, livemode: false, metadata: {},
+});
+const linesOf = (holder: Row): Row[] => (holder.line_items as { data?: Row[] } | undefined)?.data ?? [];
+
+const fromCalculation: Semantics = async (ctx) => {
+  const calcId = typeof ctx.params.calculation === 'string' ? ctx.params.calculation : '';
+  if (!calcId) return fail(ctx, 'Missing required param: calculation.', 400, 'parameter_missing');
+  if (ctx.params.reference === undefined || ctx.params.reference === '') return fail(ctx, 'Missing required param: reference.', 400, 'parameter_missing');
+  const calc = ctx.get('tax.calculation', calcId);
+  if (!calc) return fail(ctx, `No such tax calculation: '${calcId}'`, 400, 'resource_missing');
+  const id = ctx.mint(TX);
+  const now = ctx.now();
+  return ctx.reply(
+    await created(ctx, TX, {
+      id, _stripe_type: 'transaction', reference: ctx.params.reference, currency: calc.currency,
+      customer: calc.customer ?? null, customer_details: calc.customer_details ?? {},
+      tax_date: now, livemode: false, posted_at: now,
+      line_items: { object: 'list', data: linesOf(calc).map((l, i) => txLine(id, i, l, 1, null, 'transaction')), has_more: false, url: `/v1/tax/transactions/${id}/line_items` },
+      shipping_cost: calc.shipping_cost ?? null, reversal: null, calculation: calcId, metadata: {},
+    }, {}),
+  );
+};
+
+const reversal: Semantics = async (ctx) => {
+  const original = typeof ctx.params.original_transaction === 'string' ? ctx.params.original_transaction : '';
+  if (!original) return fail(ctx, 'Missing required param: original_transaction.', 400, 'parameter_missing');
+  if (ctx.params.reference === undefined || ctx.params.reference === '') return fail(ctx, 'Missing required param: reference.', 400, 'parameter_missing');
+  const mode = typeof ctx.params.mode === 'string' ? ctx.params.mode : '';
+  if (mode !== 'full' && mode !== 'partial') return fail(ctx, 'Missing required param: mode (full or partial).', 400, 'parameter_missing');
+  const orig = ctx.get(TX, original);
+  if (!orig) return txMissing(ctx, original, 400);
+  const id = ctx.mint(TX);
+  const now = ctx.now();
+  return ctx.reply(
+    await created(ctx, TX, {
+      id, _stripe_type: 'reversal', reference: ctx.params.reference, currency: orig.currency,
+      customer: orig.customer ?? null, customer_details: orig.customer_details ?? {},
+      tax_date: now, livemode: false, posted_at: now,
+      line_items: { object: 'list', data: linesOf(orig).map((l, i) => txLine(id, i, l, -1, { original_line_item: l.id }, 'reversal')), has_more: false, url: `/v1/tax/transactions/${id}/line_items` },
+      shipping_cost: null, reversal: { original_transaction: original, mode }, metadata: {},
+    }, {}),
+  );
+};
+
+const transactionLines: Semantics = async (ctx) => {
+  const t = ctx.get(TX, at(ctx, 'transaction'));
+  return t ? linePage(ctx, t) : txMissing(ctx, at(ctx, 'transaction'));
+};
+
+export const tax: Record<string, Semantics> = {
+  PostTaxRates: createRate,
+  GetTaxRates: listRates,
+  PostTaxRatesTaxRate: updateRate,
+  GetTaxSettings: getSettings,
+  PostTaxSettings: updateSettings,
+  PostTaxCalculations: calculate,
+  GetTaxCalculationsCalculationLineItems: calculationLines,
+  PostTaxRegistrations: register,
+  PostTaxTransactionsCreateFromCalculation: fromCalculation,
+  PostTaxTransactionsCreateReversal: reversal,
+  GetTaxTransactionsTransactionLineItems: transactionLines,
+};

package/src/semantics/terminal.ts

@@ -0,0 +1,195 @@
+// Terminal and top-up semantics: in-person locations, readers (handed a PaymentIntent to process)
+// and their configurations, the reader SDK's connection tokens, and top-ups that fund the balance
+// (a test top-up succeeds at once; only a pending one cancels, the machine in ../manifest.ts). In test mode a
+// simulated reader is presented a card by a test helper: the PaymentIntent the reader is processing is paid with a
+// card_present payment method (succeeded, or requires_capture under manual capture) and the reader's action succeeds
+// (docs.stripe.com/terminal/references/testing#simulated-test-cards,
+// docs.stripe.com/api/terminal/readers/present_payment_method). Where the documentation stops and the twin decides:
+// the presented card is the simulated reader's default Visa, and the reader answers at once.
+// Lists and retrieves are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { validateMoney } from '../stripe-twin.ts';
+import { settleTopup } from './ledger.ts';
+import { authorizeCharge, mintCharge } from './payment-intents.ts';
+import { at, at_, created, fail, send } from './shared.ts';
+
+const LOC = 'terminal.location';
+const READER = 'terminal.reader';
+const CONF = 'terminal.configuration';
+
+/** Update and delete by id, finding tombstones as the hand-written routes did, with Stripe's own operation names. */
+function patch(resource: string, param: string, missing: string, op: string): Semantics {
+  return (ctx) => patchRow(ctx, resource, param, missing, op);
+}
+async function patchRow(ctx: SemanticsContext, resource: string, param: string, missing: string, op: string): Promise<Response> {
+  const id = at(ctx, param);
+  if (!ctx.row(resource, id, { withDeleted: true })) return fail(ctx, `No such ${missing}: '${id}'`, 404, 'resource_missing');
+  return ctx.reply(await ctx.write(resource, id, ctx.params, op));
+}
+// A reader's update takes its label and metadata only; it moves to another location by registering it
+// there again (https://docs.stripe.com/api/terminal/readers/update, docs.stripe.com/terminal/fleet/locations-and-zones)
+// (the parameter check refuses anything else, as Stripe does: ../stripe-params.ts)
+const updateReader: Semantics = patch(READER, 'reader', 'reader', 'terminal_reader.updated');
+
+function remove(resource: string, param: string, missing: string, op: string, object: string): Semantics {
+  return async (ctx) => {
+    const id = at(ctx, param);
+    if (!ctx.row(resource, id, { withDeleted: true })) return fail(ctx, `No such ${missing}: '${id}'`, 404, 'resource_missing');
+    const row = ctx.get(resource, id);
+    await ctx.write(resource, id, { deleted: true }, op);
+    // a deleted reader still says what device it was
+    return ctx.reply({ id, object, deleted: true, ...(object === 'terminal.reader' && row ? { device_type: row.device_type, serial_number: row.serial_number } : {}) });
+  };
+}
+
+const createLocation: Semantics = async (ctx) => {
+  if (ctx.params.display_name === undefined || ctx.params.display_name === '') return fail(ctx, 'Missing required param: display_name.', 400, 'parameter_missing');
+  const addr = ctx.params.address && typeof ctx.params.address === 'object' ? (ctx.params.address as Record<string, unknown>) : undefined;
+  if (!addr || addr.country === undefined || addr.country === '') return fail(ctx, 'Missing required param: address[country].', 400, 'parameter_missing');
+  return ctx.reply(await created(ctx, LOC, ctx.params, { livemode: false, metadata: {} }));
+};
+
+// a test registration code (simulated-wpe) registers a simulated reader, online
+const createReader: Semantics = async (ctx) => {
+  if (ctx.params.registration_code === undefined || ctx.params.registration_code === '') return fail(ctx, 'Missing required param: registration_code.', 400, 'parameter_missing');
+  return ctx.reply(
+    await created(ctx, READER, ctx.params, {
+      status: 'online', device_type: 'simulated_wisepos_e', device_sw_version: null, ip_address: '0.0.0.0',
+      serial_number: `STR-${ctx.rowsRaw(READER, { withDeleted: true }).length + 1}`, action: null,
+      livemode: false, metadata: {}, label: ctx.params.label ?? 'Twin Reader',
+    }),
+  );
+};
+
+const readerMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such reader: '${id}'`, 404, 'resource_missing');
+
+// handing the reader a PaymentIntent puts it in an in-progress process_payment_intent action
+const processPaymentIntent: Semantics = async (ctx) => {
+  const id = at(ctx, 'reader');
+  if (!ctx.get(READER, id)) return readerMissing(ctx, id);
+  const pi = typeof ctx.params.payment_intent === 'string' ? ctx.params.payment_intent : '';
+  if (!pi) return fail(ctx, 'Missing required param: payment_intent.', 400, 'parameter_missing');
+  if (!ctx.get('payment_intent', pi)) return fail(ctx, `No such payment_intent: '${pi}'`, 400, 'resource_missing');
+  const action = { type: 'process_payment_intent', status: 'in_progress', failure_code: null, failure_message: null, process_payment_intent: { payment_intent: pi } };
+  return ctx.reply(await ctx.write(READER, id, { action }, 'terminal_reader.updated'));
+};
+
+/** A card presented to a reader with no payment in progress. */
+function nothingToPresent(ctx: SemanticsContext): Response {
+  return fail(ctx, 'This reader has no in-progress payment to present a payment method to.', 400, 'terminal_reader_invalid_state');
+}
+
+/** Under manual capture the presented card only holds the amount (docs.stripe.com/terminal/payments/collect-card-payment#capture-payment):
+ *  the hold is an uncaptured charge, as an online authorization's is (authorizeCharge), which the intent's capture takes. */
+async function holdForCapture(ctx: SemanticsContext, piId: string, pi: Record<string, unknown>, pm: string, amount: number): Promise<void> {
+  const charge = await authorizeCharge(ctx, piId, { ...pi, payment_method: pm }, amount);
+  await ctx.write('payment_intent', piId, { status: 'requires_capture', payment_method: pm, amount_capturable: amount, latest_charge: charge }, 'payment_intent.amount_capturable_updated');
+}
+
+const presentPaymentMethod: Semantics = async (ctx) => {
+  const id = at(ctx, 'reader');
+  const reader = ctx.get(READER, id);
+  if (!reader) return readerMissing(ctx, id);
+  const action = reader.action as Record<string, unknown> | null | undefined;
+  const piId = String(((action?.process_payment_intent as Record<string, unknown> | undefined)?.payment_intent) ?? '');
+  if (!action || action.type !== 'process_payment_intent' || action.status !== 'in_progress' || !piId) return nothingToPresent(ctx);
+  const pi = ctx.get('payment_intent', piId);
+  if (!pi) return fail(ctx, `No such payment_intent: '${piId}'`, 400, 'resource_missing');
+  const manual = pi.capture_method === 'manual' || pi.capture_method === 'manual_preferred';
+  const to = manual ? 'requires_capture' : 'succeeded';
+  const refused = ctx.legal('payment_intent', 'status', 'PostTestHelpersTerminalReadersReaderPresentPaymentMethod', pi.status, to, piId);
+  if (refused) return ctx.refuse(refused);
+  const pm = await created(ctx, 'payment_method', {}, {
+    type: 'card_present', customer: null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null },
+    card_present: { brand: 'visa', last4: '4242', exp_month: 12, exp_year: 2030, funding: 'credit', country: 'US', read_method: 'contactless_emv', networks: { available: ['visa'], preferred: null } },
+  });
+  const amount = Number(pi.amount) || 0;
+  if (manual) await holdForCapture(ctx, piId, pi, String(pm.id), amount);
+  else {
+    const charge = await mintCharge(ctx, piId, { ...pi, payment_method: pm.id }, amount);
+    await ctx.write('payment_intent', piId, { status: 'succeeded', payment_method: pm.id, amount_received: amount, latest_charge: charge }, 'payment_intent.succeeded');
+  }
+  return ctx.reply(await ctx.write(READER, id, { action: { ...action, status: 'succeeded' } }, 'terminal_reader.action_succeeded'));
+};
+
+const cancelAction: Semantics = async (ctx) => {
+  const id = at(ctx, 'reader');
+  if (!ctx.get(READER, id)) return readerMissing(ctx, id);
+  return ctx.reply(await ctx.write(READER, id, { action: null }, 'terminal_reader.updated'));
+};
+
+// a short-lived secret for the reader SDK, answered and not kept
+const connectionToken: Semantics = async (ctx) => {
+  const loc = typeof ctx.params.location === 'string' ? ctx.params.location : undefined;
+  return ctx.reply({ object: 'terminal.connection_token', secret: `pst_test_twin_${ctx.rowsRaw(READER, { withDeleted: true }).length + 1}`, ...(loc ? { location: loc } : {}) });
+};
+
+const createConfiguration: Semantics = async (ctx) =>
+  ctx.reply(await created(ctx, CONF, ctx.params, { is_account_default: false, livemode: false, tipping: null, name: ctx.params.name ?? null }));
+
+// ── top-ups ──
+
+// a top-up adds money to the balance it names, through the ledger, once its funds arrive: "USA (USD) ACH Debit Transfer
+// 5 days" (docs.stripe.com/connect/top-ups), and to the Issuing balance alike: "Top-ups debit your bank account. Your
+// top-ups can take up to 5 business days to become available. While they're pending, they won't be added to your
+// Issuing balance" (docs.stripe.com/issuing/funding/balance). It is pending until its expected_availability_date, then
+// settled by settleTopups. Where the documentation stops and the twin decides: every top-up takes exactly five days,
+// whatever its currency and balance, and succeeds.
+const TOPUP_DAYS = 5;
+const createTopup: Semantics = async (ctx) => {
+  const bad = validateMoney(ctx.params);
+  if (bad) return send(ctx, bad);
+  const now = Number(ctx.now());
+  return ctx.reply(await created(ctx, 'topup', ctx.params, {
+    status: 'pending', expected_availability_date: now + TOPUP_DAYS * 86_400, livemode: false,
+    metadata: {}, source: null, statement_descriptor: ctx.params.statement_descriptor ?? null,
+    balance_transaction: null, failure_code: null, failure_message: null,
+  }));
+};
+
+/** Time's settling of top-ups, caught up to the World's clock: a pending top-up succeeds on its expected_availability_date,
+ *  its funds entered then in the balance it names. */
+export async function settleTopups(ctx: SemanticsContext): Promise<void> {
+  const now = Number(ctx.now());
+  for (const t of ctx.rowsRaw('topup')) {
+    if (t.status !== 'pending' || Number(t.expected_availability_date) > now) continue;
+    const c = await at_(ctx)(Number(t.expected_availability_date));
+    c.legal('topup', 'status', ctx.call.operation.id, 'pending', 'succeeded', String(t.id), 'vendor');
+    const bt = await settleTopup(c, String(t.id), Number(t.amount), String(t.currency), t.destination_balance === 'issuing' ? 'issuing' : 'payments');
+    await c.write('topup', String(t.id), { status: 'succeeded', balance_transaction: bt }, 'topup.succeeded');
+  }
+}
+
+const cancelTopup: Semantics = async (ctx) => {
+  const id = at(ctx, 'topup');
+  const t = ctx.get('topup', id);
+  if (!t) return fail(ctx, `No such topup: '${id}'`, 404, 'resource_missing');
+  const refused = ctx.legal('topup', 'status', 'PostTopupsTopupCancel', t.status, undefined, id);
+  if (refused) return ctx.refuse(refused);
+  return ctx.reply(await ctx.write('topup', id, { status: 'canceled' }, 'topup.canceled'));
+};
+
+const updateTopup: Semantics = async (ctx) => {
+  const id = at(ctx, 'topup');
+  if (!ctx.get('topup', id)) return fail(ctx, `No such topup: '${id}'`, 404, 'resource_missing');
+  return ctx.reply(await ctx.write('topup', id, ctx.params, 'topup.updated'));
+};
+
+export const terminal: Record<string, Semantics> = {
+  PostTerminalLocations: createLocation,
+  PostTerminalLocationsLocation: patch(LOC, 'location', 'location', 'terminal_location.updated'),
+  DeleteTerminalLocationsLocation: remove(LOC, 'location', 'location', 'terminal_location.deleted', 'terminal.location'),
+  PostTerminalReaders: createReader,
+  PostTerminalReadersReader: updateReader,
+  DeleteTerminalReadersReader: remove(READER, 'reader', 'reader', 'terminal_reader.deleted', 'terminal.reader'),
+  PostTerminalReadersReaderProcessPaymentIntent: processPaymentIntent,
+  PostTerminalReadersReaderCancelAction: cancelAction,
+  PostTestHelpersTerminalReadersReaderPresentPaymentMethod: presentPaymentMethod,
+  PostTerminalConnectionTokens: connectionToken,
+  PostTerminalConfigurations: createConfiguration,
+  PostTerminalConfigurationsConfiguration: patch(CONF, 'configuration', 'configuration', 'terminal_configuration.updated'),
+  DeleteTerminalConfigurationsConfiguration: remove(CONF, 'configuration', 'configuration', 'terminal_configuration.deleted', 'terminal.configuration'),
+  PostTopups: createTopup,
+  PostTopupsTopupCancel: cancelTopup,
+  PostTopupsTopup: updateTopup,
+};

package/src/semantics/test-clocks.ts

@@ -0,0 +1,77 @@
+// Test clock semantics. A test clock is Stripe's own door for a transition no API verb makes: the
+// passage of time. Advancing it moves the subscriptions of the clock's customers as a real clock tick does:
+// trials that ended end, and periods that ended renew (./renewals.ts advanceBilling). List, retrieve and delete are
+// the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { at, created, fail } from './shared.ts';
+import { advanceBilling } from './renewals.ts';
+
+const CLOCK = 'test_helpers.test_clock';
+
+const create: Semantics = async (ctx) => {
+  if (ctx.params.frozen_time === undefined) return fail(ctx, 'Missing required param: frozen_time.', 400, 'parameter_missing');
+  const frozen = Math.trunc(Number(ctx.params.frozen_time) || 0);
+  // "Simulations are automatically deleted 30 days after you create them" (docs.stripe.com/billing/testing/test-clocks/
+  // api-advanced-usage): from its creation on the account's clock, not its frozen time
+  return ctx.reply(await created(ctx, CLOCK, { name: ctx.params.name ?? null }, { frozen_time: frozen, status: 'ready', status_details: {}, livemode: false, deletes_after: Number(ctx.now()) + 30 * 24 * 3600 }));
+};
+
+/** A test clock deleted with what lives on it: "Deleting the simulation also deletes the test customers associated
+ *  with the clock and cancels their subscriptions" (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). */
+const remove: Semantics = async (ctx) => {
+  const id = at(ctx, 'test_clock');
+  if (!ctx.get(CLOCK, id)) return fail(ctx, `No such test clock: '${id}'`, 404, 'resource_missing');
+  const now = Number(ctx.now());
+  for (const c of ctx.rows('customer').filter((c) => c.test_clock === id)) {
+    for (const sub of ctx.rows('subscription').filter((s) => s.customer === c.id && s.status !== 'canceled')) {
+      ctx.legal('subscription', 'status', 'DeleteTestHelpersTestClocksTestClock', String(sub.status), 'canceled', String(sub.id));
+      await ctx.write('subscription', String(sub.id), { status: 'canceled', canceled_at: now, ended_at: now }, 'subscription.cancel');
+    }
+    await ctx.write('customer', String(c.id), { deleted: true }, 'customer.deleted');
+  }
+  await ctx.write(CLOCK, id, { deleted: true }, 'test_clock.deleted');
+  return ctx.reply({ id, object: 'test_helpers.test_clock', deleted: true });
+};
+
+const advance: Semantics = async (ctx) => {
+  const id = at(ctx, 'test_clock');
+  const clock = ctx.get(CLOCK, id);
+  if (!clock) return fail(ctx, `No such test clock: '${id}'`, 404, 'resource_missing');
+  if (ctx.params.frozen_time === undefined) return fail(ctx, 'Missing required param: frozen_time.', 400, 'parameter_missing');
+  const to = Math.trunc(Number(ctx.params.frozen_time) || 0);
+  if (to <= Number(clock.frozen_time)) return fail(ctx, 'frozen_time must be after the current clock time.', 400, 'parameter_invalid');
+  const refused = ctx.legal(CLOCK, 'status', 'PostTestHelpersTestClocksTestClockAdvance', clock.status, 'advancing', id);
+  if (refused) return ctx.refuse(refused);
+  // "After a successful API request or Dashboard operation, it takes a few seconds to advance to the specified time"
+  // (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage): the advance answers advancing toward its target,
+  // and finishClockAdvances completes it ADVANCE_SECONDS of World time later; an advance asked meanwhile is refused
+  // test_clock_not_ready (the machine's refusal).
+  return ctx.reply(await ctx.write(CLOCK, id, { status: 'advancing', status_details: { advancing: { target_frozen_time: to } } }, 'test_clock.advancing'));
+};
+
+/** How long an advance takes: "it takes a few seconds to advance to the specified time"
+ *  (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). Where the documentation stops and the twin decides:
+ *  five seconds of World time from the advance. */
+const ADVANCE_SECONDS = 5;
+
+/** Each advancing clock whose advance has taken its time reaches its target, caught up before anything is answered:
+ *  its frozen_time moves, it is ready, and its customers' trials and periods that ended by then end
+ *  (./renewals.ts advanceBilling). The advance's own write is when it began (the kernel's updatedAt). */
+export async function finishClockAdvances(ctx: SemanticsContext): Promise<void> {
+  const now = Number(ctx.now());
+  for (const clock of ctx.rowsRaw(CLOCK)) {
+    if (clock.status !== 'advancing') continue;
+    if (Date.parse(String(clock.updatedAt)) / 1000 + ADVANCE_SECONDS > now) continue;
+    const id = String(clock.id);
+    const target = Number((clock.status_details as { advancing?: { target_frozen_time?: number } } | undefined)?.advancing?.target_frozen_time);
+    ctx.legal(CLOCK, 'status', ctx.call.operation.id, 'advancing', 'ready', id, 'vendor');
+    await ctx.write(CLOCK, id, { frozen_time: target, status: 'ready', status_details: {} }, 'test_clock.ready');
+    await advanceBilling(ctx, (sub) => typeof sub.customer === 'string' && ctx.get('customer', sub.customer)?.test_clock === id);
+  }
+}
+
+export const testClocks: Record<string, Semantics> = {
+  PostTestHelpersTestClocks: create,
+  PostTestHelpersTestClocksTestClockAdvance: advance,
+  DeleteTestHelpersTestClocksTestClock: remove,
+};

package/src/semantics/tokens.ts

@@ -0,0 +1,52 @@
+// Token semantics: the older integrations' single-use tokens for a card, a bank account or PII. A
+// token carries only the safe fields of its instrument, never the card or account number. Retrieve
+// is the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { paymentMethodSubObject } from '../stripe-twin.ts';
+import { created, fail, type Row } from './shared.ts';
+
+/** The Card object a card token carries, as the served spec's `card` describes it: its brand as a name ("Card brand.
+ *  Can be `American Express`, ... `MasterCard`, `UnionPay`, `Visa`, or `Unknown`"), the holder's name and address as
+ *  given ("Cardholder name"), and the CVC's check when one was given ("If a CVC was provided, results of the check:
+ *  pass, fail, unavailable, or unchecked"). Where the documentation stops and the twin decides: a test card's CVC passes. */
+const BRAND_NAMES: Record<string, string> = { amex: 'American Express', cartes_bancaires: 'Cartes Bancaires', diners: 'Diners Club', discover: 'Discover', eftpos_au: 'Eftpos Australia', girocard: 'Girocard', jcb: 'JCB', mastercard: 'MasterCard', unionpay: 'UnionPay', visa: 'Visa' };
+export function legacyCard(id: string, card: Row): Row {
+  const pm = paymentMethodSubObject('card', { card }).card as Row;
+  const given = (k: string): unknown => (typeof card[k] === 'string' && card[k] !== '' ? card[k] : null);
+  return {
+    id, object: 'card', brand: BRAND_NAMES[String(pm.brand)] ?? 'Unknown', last4: pm.last4, exp_month: pm.exp_month, exp_year: pm.exp_year,
+    funding: pm.funding ?? 'credit', country: pm.country ?? null, fingerprint: pm.fingerprint ?? null, name: given('name'),
+    address_line1: given('address_line1'), address_line2: given('address_line2'), address_city: given('address_city'), address_state: given('address_state'),
+    address_zip: given('address_zip'), address_country: given('address_country'), address_line1_check: null, address_zip_check: null,
+    cvc_check: card.cvc !== undefined && card.cvc !== '' ? 'pass' : null, dynamic_last4: null, tokenization_method: null, metadata: {}, customer: null,
+  };
+}
+
+/** A token asked for none of what a token holds. */
+function noTokenSource(ctx: SemanticsContext): Response {
+  return fail(ctx, 'You must provide one of the following parameters: card, bank_account, pii.', 400, 'parameter_missing');
+}
+
+/** A bank account token's account, as the legacy BankAccount object holds it. */
+function bankAccountOf(ctx: SemanticsContext, ba: Row): Row {
+  const acct = typeof ba.account_number === 'string' ? ba.account_number.replace(/\D/g, '') : '';
+  return {
+    id: ctx.mint('external_account'), object: 'bank_account', account_holder_name: ba.account_holder_name ?? null,
+    account_holder_type: ba.account_holder_type ?? null, bank_name: 'STRIPE TEST BANK',
+    country: ba.country ?? 'US', currency: ba.currency ?? 'usd', fingerprint: 'twin_ba_fp',
+    last4: acct ? acct.slice(-4) : '6789', routing_number: ba.routing_number ?? '110000000', status: 'new',
+  };
+}
+
+const create: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const isObject = (v: unknown): v is Row => !!v && typeof v === 'object';
+  const type = isObject(params.card) ? 'card' : isObject(params.bank_account) ? 'bank_account' : isObject(params.pii) ? 'pii' : undefined;
+  if (!type) return noTokenSource(ctx);
+  const sub: Row = type === 'card'
+    ? { card: legacyCard(ctx.mint('payment_method').replace('pm_', 'card_'), params.card as Row) }
+    : type === 'bank_account' ? { bank_account: bankAccountOf(ctx, params.bank_account as Row) } : {};
+  return ctx.reply(await created(ctx, 'token', { type }, { ...sub, client_ip: null, used: false, livemode: false }));
+};
+
+export const tokens: Record<string, Semantics> = { PostTokens: create };