@volter/twin-stripe 0.1.2 → 2.0.0

package/src/semantics/balance.ts

@@ -0,0 +1,209 @@
+// Balance and payout semantics. The balance is computed from the balance-transaction ledger (./ledger.ts), never
+// stored: funds past their available_on are available, the rest pending, and Issuing funds their own section. The
+// balance, the payouts and the ledger are the acting account's: the platform's, or a connected account's under the
+// Stripe-Account header. A payout comes out of what that account has available and goes to its bank account, which a
+// connected account must have (docs.stripe.com/connect/payouts-connected-accounts). A pending payout can be canceled,
+// which returns its money; a connected account's paid payout can be reversed, which debits its bank account back
+// into its balance (docs.stripe.com/api/payouts/reverse). The machine in ../manifest.ts says how a payout's status
+// moves.
+//
+// Stripe also pays each account out on its own schedule (settings.payouts.schedule: daily by default, weekly or monthly
+// on an anchor, or manual): an automatic payout takes what has become available since the last one, and the ledger
+// lists the entries it paid (docs.stripe.com/payouts#payout-schedule, docs.stripe.com/connect/manage-payout-schedule).
+// A connected account is paid out once it can be (payouts_enabled, with a bank account).
+//
+// Where the documentation stops and the twin decides: a payout arrives two days after it is made (Stripe's standard
+// US schedule counts business days) and reads paid from then on; an automatic payout is made at midnight UTC on the
+// first scheduled day on or after its funds become available, only when what it would pay is positive.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { validateMoney } from '../stripe-twin.ts';
+import { accountSettings, PLATFORM_ACCOUNT_ID } from '../stripe-twin.ts';
+import { actingAccount, balanceOf, refusePayout, settleAutomaticPayout, settlePayout, unpaidEntries } from './ledger.ts';
+import { at, at_, created, fail, inRange, list, newest, send, where, type Row, kept } from './shared.ts';
+
+const account = actingAccount;
+const DAY = 86_400;
+const payoutMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such payout: '${id}'`, 404, 'resource_missing');
+
+/** The acting account's Balance object (docs.stripe.com/api/balance/balance_object). */
+export function balanceBody(ctx: SemanticsContext): Row {
+  const { available, pending, issuing } = balanceOf(ctx);
+  const toArr = (m: Map<string, number>) => {
+    const out = [...m.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } }));
+    return out.length ? out : [{ amount: 0, currency: 'usd', source_types: { card: 0 } }];
+  };
+  // a platform's balance holds its connected accounts' reserve, "Funds held due to negative balances on connected accounts
+  // where account.controller.requirement_collection is `application`" (docs.stripe.com/api/balance/balance_object, whose
+  // example answers `[{"amount": 0, "currency": "usd"}]`); the twin models no such reserve, so it is zero in each currency
+  const reserved = account(ctx) ? {} : { connect_reserved: toArr(available).map((b) => ({ amount: 0, currency: b.currency })) };
+  return {
+    object: 'balance', available: toArr(available), pending: toArr(pending), ...reserved, livemode: false,
+    ...(issuing.size ? { issuing: { available: [...issuing.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } })) } } : {}),
+  };
+}
+
+const balance: Semantics = async (ctx) => ctx.reply(balanceBody(ctx));
+
+/** Time's arrivals, written: each of the acting account's payouts whose arrival date has come moves pending → paid
+ *  (the clock's move, as asOf reads it), written as `payout.paid`, the event Stripe sends for it. Answers their ids. */
+export async function payDuePayouts(ctx: SemanticsContext): Promise<string[]> {
+  const acct = account(ctx);
+  const now = Number(ctx.now());
+  const paid: string[] = [];
+  for (const p of newest(ctx, 'payout')) {
+    if ((acct ? kept(ctx, 'payout', p, '_account') !== acct : !!kept(ctx, 'payout', p, '_account')) || p.status !== 'pending' || Number(p.arrival_date) > now) continue;
+    if (ctx.legal('payout', 'status', ctx.call.operation.id, 'pending', 'paid', String(p.id), 'time')) continue;
+    await ctx.write('payout', String(p.id), { status: 'paid' }, 'payout.paid');
+    paid.push(String(p.id));
+  }
+  return paid;
+}
+
+/** Where a connected account's payout goes: "ID of the bank account or card the payout is sent to" (served spec,
+ *  payout.destination), its default external account for the currency, "When multiple accounts are available for a given
+ *  currency, Stripe uses the one set as `default_for_currency`" (docs.stripe.com/connect/payouts-bank-accounts), the
+ *  newest such. Where the documentation stops and the twin decides: the platform's own bank account is not modelled, so
+ *  its payouts name none. */
+function payoutBank(ctx: SemanticsContext, account: string, currency: string): string | null {
+  const banks = newest(ctx, 'external_account').filter((e) => e.account === account && String(e.currency ?? currency) === currency);
+  return String((banks.find((e) => e.default_for_currency === true) ?? banks[0])?.id ?? '') || null;
+}
+
+const payoutDefaults = (ctx: SemanticsContext): Row => ({
+  method: 'standard', type: 'bank_account', source_type: 'card', automatic: false,
+  reconciliation_status: 'not_applicable', arrival_date: Number(ctx.now()) + 2 * DAY, livemode: false, metadata: {},
+});
+
+/** A payout as the clock reads it: paid once its arrival date has come, the clock's move, asked of the
+ *  machine as a write asks it. */
+function asOf(ctx: SemanticsContext, p: Row): Row {
+  if (p.status !== 'pending' || Number(p.arrival_date) > Number(ctx.now())) return p;
+  ctx.legal('payout', 'status', ctx.call.operation.id, 'pending', 'paid', String(p.id), 'time');
+  return { ...p, status: 'paid' };
+}
+
+/** A connected account's payout in a currency none of its bank accounts takes. */
+function noExternalAccount(ctx: SemanticsContext, currency: string): Response {
+  return fail(ctx, `Sorry, you don't have any external accounts in that currency (${currency}).`, 400);
+}
+
+const createPayout: Semantics = async (ctx) => {
+  const bad = validateMoney(ctx.params);
+  if (bad) return send(ctx, bad);
+  const acct = account(ctx);
+  if (acct && !ctx.get('account', acct)) return fail(ctx, `No such account: '${acct}'`, 400, 'account_invalid');
+  const amount = Math.trunc(Number(ctx.params.amount) || 0);
+  const currency = String(ctx.params.currency ?? 'usd');
+  // a connected account is paid out to its own bank account
+  if (acct && !ctx.rows('external_account').some((e) => e.account === acct && (e.currency ?? currency) === currency)) return noExternalAccount(ctx, currency);
+  const refused = refusePayout(ctx, amount, currency);
+  if (refused) return refused;
+  const id = ctx.mint('payout');
+  const bt = await settlePayout(ctx, id, -amount, currency);
+  return ctx.reply(await created(ctx, 'payout', { ...ctx.params, id }, { status: 'pending', ...payoutDefaults(ctx), balance_transaction: bt, destination: acct ? payoutBank(ctx, acct, currency) : null, ...(acct ? { _account: acct } : {}) }));
+};
+
+const listPayouts: Semantics = async (ctx) => {
+  const acct = account(ctx);
+  const scoped = newest(ctx, 'payout').filter((p) => (acct ? kept(ctx, 'payout', p, '_account') === acct : !kept(ctx, 'payout', p, '_account'))).map((p) => asOf(ctx, p));
+  return list(ctx, 'payout', where(ctx, scoped, { status: (p, v) => p.status === v, created: (p, v) => inRange(p.created, v), arrival_date: (p, v) => inRange(p.arrival_date, v) }));
+};
+
+const DAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+/** The first scheduled payout time on or after `from`: midnight UTC of a day the schedule pays out on. */
+function payoutDay(from: number, schedule: Row): number {
+  const first = Math.ceil(from / DAY) * DAY;
+  const pays = (day: number): boolean => {
+    const d = new Date(day * 1000);
+    if (schedule.interval === 'weekly') return DAYS[d.getUTCDay()] === String(schedule.weekly_anchor ?? 'monday');
+    if (schedule.interval === 'monthly') return d.getUTCDate() === Math.min(Number(schedule.monthly_anchor ?? 1), new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate());
+    return true;
+  };
+  return Array.from({ length: 62 }, (_, i) => first + i * DAY).find(pays) ?? first;
+}
+
+/** Time's payouts, caught up to the World's clock: each account on an automatic schedule is paid out, on each of its
+ *  scheduled days that has come, what became available by then. */
+export async function advancePayouts(ctx: SemanticsContext): Promise<void> {
+  const now = Number(ctx.now());
+  const platform = ctx.get('account', PLATFORM_ACCOUNT_ID);
+  const accounts: Array<{ id: string | undefined; settings: unknown }> = [{ id: undefined, settings: platform?.settings }];
+  for (const a of ctx.rows('account')) {
+    if (a.id === PLATFORM_ACCOUNT_ID || a.payouts_enabled !== true) continue;
+    if (!ctx.rows('external_account').some((e) => e.account === a.id)) continue;
+    accounts.push({ id: String(a.id), settings: a.settings });
+  }
+  for (const acct of accounts) {
+    const schedule = ((accountSettings(acct.settings, (acct.settings as Row | undefined) ?? undefined).payouts as Row).schedule ?? {}) as Row;
+    if (schedule.interval === 'manual') continue;
+    const unpaid = unpaidEntries(ctx, acct.id);
+    const days = [...new Set(unpaid.map((t) => payoutDay(Number(t.available_on) || 0, schedule)))].filter((d) => d <= now).sort((x, y) => x - y);
+    const paid = new Set<unknown>();
+    for (const day of days) {
+      const due = unpaid.filter((t) => !paid.has(t.id) && (Number(t.available_on) || 0) <= day);
+      const byCurrency = new Map<string, Row[]>();
+      for (const t of due) byCurrency.set(String(t.currency ?? 'usd'), [...(byCurrency.get(String(t.currency ?? 'usd')) ?? []), t]);
+      for (const [currency, entries] of byCurrency) {
+        const amount = entries.reduce((n, t) => n + (Number(t.net) || 0), 0);
+        // nothing to pay yet: what came due is carried to the next payout
+        if (amount <= 0) continue;
+        // made on its day, as Stripe makes it, whenever the request that catches it up comes
+        const c = await at_(ctx)(day);
+        const id = c.mint('payout');
+        const bt = await settleAutomaticPayout(c, id, amount, currency, acct.id, day, entries);
+        await created(c, 'payout', { id, amount, currency }, {
+          status: 'pending', ...payoutDefaults(c), arrival_date: day + 2 * DAY, automatic: true, balance_transaction: bt, destination: acct.id ? payoutBank(c, String(acct.id), currency) : null,
+          description: 'STRIPE PAYOUT', ...(acct.id ? { _account: acct.id } : {}),
+        });
+        for (const t of entries) paid.add(t.id);
+      }
+    }
+  }
+}
+
+const retrievePayout: Semantics = async (ctx) => {
+  const p = ctx.get('payout', at(ctx, 'payout'));
+  return p ? ctx.reply(asOf(ctx, p)) : payoutMissing(ctx, at(ctx, 'payout'));
+};
+
+const cancelPayout: Semantics = async (ctx) => {
+  const id = at(ctx, 'payout');
+  const po = ctx.get('payout', id);
+  if (!po) return payoutMissing(ctx, id);
+  const refused = ctx.legal('payout', 'status', 'PostPayoutsPayoutCancel', asOf(ctx, po).status, undefined, id);
+  if (refused) return ctx.refuse(refused);
+  // the money comes back to the balance it left
+  const owner = kept(ctx, 'payout', po, '_account');
+  await settlePayout(ctx, id, Number(po.amount) || 0, String(po.currency ?? 'usd'), typeof owner === 'string' ? owner : null);
+  return ctx.reply(await ctx.write('payout', id, { status: 'canceled' }, 'payout.cancel'));
+};
+
+// a reversal is itself a payout in the other direction, back into the connected account's balance, as the reverse page's
+// example answers it: a negative amount, pending until it arrives, carrying the request's metadata
+// (docs.stripe.com/api/payouts/reverse); the original stays paid and names it
+const reversePayout: Semantics = async (ctx) => {
+  const id = at(ctx, 'payout');
+  const po = ctx.get('payout', id);
+  if (!po) return payoutMissing(ctx, id);
+  const owner = kept(ctx, 'payout', po, '_account');
+  if (typeof owner !== 'string') return fail(ctx, "Payout reversals are only supported for payouts to connected accounts' bank accounts.", 400);
+  const status = String(asOf(ctx, po).status);
+  if (po.reversed_by || status !== 'paid') return ctx.refuse({ status: 400, code: 'payout_reversal_not_allowed', message: po.reversed_by ? 'This payout has already been reversed.' : `This payout cannot be reversed because it has a status of ${status}. A pending payout can be canceled instead.` });
+  const reversalId = ctx.mint('payout');
+  const bt = await settlePayout(ctx, reversalId, Number(po.amount) || 0, String(po.currency ?? 'usd'), owner);
+  const metadata = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? { metadata: ctx.params.metadata } : {};
+  const reversal = await created(ctx, 'payout', { id: reversalId, amount: -(Number(po.amount) || 0), currency: po.currency, ...metadata }, {
+    status: 'pending', ...payoutDefaults(ctx), balance_transaction: bt, original_payout: id, destination: po.destination ?? null, _account: owner,
+  });
+  await ctx.write('payout', id, { reversed_by: reversal.id }, 'payout.reversed');
+  return ctx.reply(reversal);
+};
+
+export const balances: Record<string, Semantics> = {
+  GetBalance: balance,
+  PostPayouts: createPayout,
+  GetPayouts: listPayouts,
+  GetPayoutsPayout: retrievePayout,
+  PostPayoutsPayoutCancel: cancelPayout,
+  PostPayoutsPayoutReverse: reversePayout,
+};

package/src/semantics/billing.ts

@@ -0,0 +1,216 @@
+// Billing semantics: meters (how usage events aggregate), the meter events that report usage and
+// the summaries that aggregate them, prepaid credit grants and the balance they leave, and usage
+// alerts. The machines in ../manifest.ts say how a meter and an alert move. Lists and retrieves
+// with no scoping of their own are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { at, created, fail, list, newest, path, where, type Row } from './shared.ts';
+
+const METER = 'billing.meter';
+const meterMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such meter: '${id}'`, 404, 'resource_missing');
+const objectOf = (v: unknown): Row => (v && typeof v === 'object' ? (v as Row) : {});
+
+// a meter needs a display name, the event name it counts, and how it aggregates (sum or count)
+const createMeter: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const displayName = typeof params.display_name === 'string' ? params.display_name : '';
+  if (!displayName) return fail(ctx, 'Missing required param: display_name.', 400, 'parameter_missing');
+  if (!((params.event_name as string) ?? '')) return fail(ctx, 'Missing required param: event_name.', 400, 'parameter_missing');
+  const formula = objectOf(params.default_aggregation).formula;
+  if (typeof formula !== 'string' || !formula) return fail(ctx, 'Missing required param: default_aggregation[formula] (sum or count).', 400, 'parameter_missing');
+  return ctx.reply(
+    await created(ctx, METER, params, {
+      status: 'active', livemode: false,
+      customer_mapping: (params.customer_mapping as object) ?? { event_payload_key: 'stripe_customer_id', type: 'by_id' },
+      event_time_window: (params.event_time_window as string) ?? null,
+      value_settings: (params.value_settings as object) ?? { event_payload_key: 'value' },
+      status_transitions: { deactivated_at: null }, updated: ctx.now(),
+    }),
+  );
+};
+
+function activation(kind: 'deactivate' | 'reactivate'): Semantics {
+  return async (ctx) => {
+    const id = at(ctx, 'id');
+    const m = ctx.get(METER, id);
+    if (!m) return meterMissing(ctx, id);
+    const refused = ctx.legal(METER, 'status', kind === 'deactivate' ? 'PostBillingMetersIdDeactivate' : 'PostBillingMetersIdReactivate', m.status, undefined, id);
+    if (refused) return ctx.refuse(refused);
+    const fields = { ...(kind === 'deactivate' ? { status: 'inactive', status_transitions: { deactivated_at: ctx.now() } } : { status: 'active', status_transitions: { deactivated_at: null } }), updated: ctx.now() };
+    return ctx.reply(await ctx.write(METER, id, fields, `billing_meter.${kind}`));
+  };
+}
+
+// a meter event has no id of its own on Stripe (it carries an `identifier`); its object is billing.meter_event
+const reportUsage: Semantics = async (ctx) => {
+  const params = ctx.params;
+  if (typeof params.event_name !== 'string' || !params.event_name) return fail(ctx, 'Missing required param: event_name.', 400, 'parameter_missing');
+  const payload = objectOf(params.payload);
+  const body = await created(ctx, 'billing.meter_event', { ...params }, {
+    livemode: false, timestamp: params.timestamp !== undefined ? Math.trunc(Number(params.timestamp)) : ctx.now(),
+    identifier: payload.identifier ?? null, payload,
+  });
+  return ctx.reply({ ...body, object: 'billing.meter_event' });
+};
+
+// the meter's events for one customer in [start_time, end_time), aggregated by its formula
+const eventSummaries: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  const m = ctx.get(METER, id);
+  if (!m) return meterMissing(ctx, id);
+  const params = ctx.params;
+  const customer = typeof params.customer === 'string' ? params.customer : '';
+  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+  if (params.start_time === undefined) return fail(ctx, 'Missing required param: start_time.', 400, 'parameter_missing');
+  if (params.end_time === undefined) return fail(ctx, 'Missing required param: end_time.', 400, 'parameter_missing');
+  const startTime = Math.trunc(Number(params.start_time) || 0);
+  const endTime = Math.trunc(Number(params.end_time) || 0);
+  // "Must be aligned with minute boundaries" (start_time, end_time); "For hourly granularity, start and end times must
+  // align with hour boundaries … For daily granularity, … with UTC day boundaries (00:00 UTC)" (value_grouping_window;
+  // the served spec). Where the documentation stops and the twin decides: Stripe documents no error for it, so the
+  // twin answers a 400 naming the parameter and the boundary.
+  const window = params.value_grouping_window === 'hour' ? 3600 : params.value_grouping_window === 'day' ? 86_400 : 60;
+  const unit = window === 3600 ? 'hour' : window === 86_400 ? 'UTC day' : 'minute';
+  for (const [name, t] of [['start_time', startTime], ['end_time', endTime]] as const) {
+    if (t % window !== 0) return fail(ctx, `Invalid ${name}: ${t} is not aligned with ${unit} boundaries.`, 400);
+  }
+  const mapKey = typeof objectOf(m.customer_mapping).event_payload_key === 'string' ? String(objectOf(m.customer_mapping).event_payload_key) : 'stripe_customer_id';
+  const valueKey = typeof objectOf(m.value_settings).event_payload_key === 'string' ? String(objectOf(m.value_settings).event_payload_key) : 'value';
+  const formula = (objectOf(m.default_aggregation).formula as string) ?? 'sum';
+  let aggregate = 0;
+  for (const ev of ctx.rowsRaw('billing.meter_event', { withDeleted: true })) {
+    if (ev.event_name !== String(m.event_name ?? '')) continue;
+    const ts = Number(ev.timestamp) || 0;
+    if (ts < startTime || ts >= endTime) continue;
+    const payload = objectOf(ev.payload);
+    if (String(payload[mapKey] ?? '') !== customer) continue;
+    aggregate += formula === 'count' ? 1 : Number(payload[valueKey]) || 0;
+  }
+  return ctx.reply({
+    object: 'list', url: path(ctx), has_more: false,
+    data: [{ id: `mtrusg_twin_${id}_${customer}`, object: 'billing.meter_event_summary', meter: id, aggregated_value: aggregate, start_time: startTime, end_time: endTime, livemode: false }],
+  });
+};
+
+// ── credit grants: a customer's prepaid credit, paid or promotional, in a monetary amount ──
+
+const GRANT = 'billing.credit_grant';
+const grantMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such credit grant: '${id}'`, 404, 'resource_missing');
+
+const createGrant: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const customer = typeof params.customer === 'string' ? params.customer : '';
+  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+  if (!ctx.row('customer', customer, { withDeleted: true })) return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
+  const category = typeof params.category === 'string' ? params.category : '';
+  if (category !== 'paid' && category !== 'promotional') return fail(ctx, 'Invalid category: must be paid or promotional.', 400, 'parameter_invalid_string_enum');
+  const monetary = params.amount && typeof params.amount === 'object' ? objectOf((params.amount as Row).monetary) : undefined;
+  if (!monetary || monetary.value === undefined || monetary.currency === undefined) return fail(ctx, 'Missing required param: amount[monetary][value] and amount[monetary][currency].', 400, 'parameter_missing');
+  return ctx.reply(
+    await created(ctx, GRANT, { customer }, {
+      category, livemode: false, name: params.name ?? null,
+      amount: { type: 'monetary', monetary: { currency: String(monetary.currency), value: Math.trunc(Number(monetary.value) || 0) } },
+      applicability_config: params.applicability_config && typeof params.applicability_config === 'object' ? params.applicability_config : { scope: { price_type: 'metered' } },
+      effective_at: params.effective_at !== undefined ? Math.trunc(Number(params.effective_at)) : ctx.now(),
+      expires_at: params.expires_at !== undefined ? Math.trunc(Number(params.expires_at)) : null,
+      priority: params.priority !== undefined ? Math.trunc(Number(params.priority)) : 50,
+      voided_at: null, metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {}, updated: ctx.now(),
+    }),
+  );
+};
+
+// expiring or voiding a grant stamps the instant; it no longer counts toward the balance
+function endGrant(kind: 'expire' | 'void'): Semantics {
+  return async (ctx) => {
+    const id = at(ctx, 'id');
+    if (!ctx.get(GRANT, id)) return grantMissing(ctx, id);
+    return ctx.reply(await ctx.write(GRANT, id, { ...(kind === 'void' ? { voided_at: ctx.now() } : { expires_at: ctx.now() }), updated: ctx.now() }, `credit_grant.${kind}`));
+  };
+}
+
+// only the expiry and metadata change
+const updateGrant: Semantics = async (ctx) => {
+  const id = at(ctx, 'id');
+  if (!ctx.get(GRANT, id)) return grantMissing(ctx, id);
+  const patch: Row = { updated: ctx.now() };
+  if (ctx.params.expires_at !== undefined) patch.expires_at = Math.trunc(Number(ctx.params.expires_at));
+  if (ctx.params.metadata !== undefined) patch.metadata = ctx.params.metadata;
+  return ctx.reply(await ctx.write(GRANT, id, patch, 'credit_grant.update'));
+};
+
+// the customer's live (unvoided, unexpired) monetary grants, summed per currency
+const creditBalance: Semantics = async (ctx) => {
+  const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
+  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+  if (!ctx.row('customer', customer, { withDeleted: true })) return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
+  const now = Number(ctx.now());
+  const byCurrency: Record<string, number> = {};
+  for (const g of ctx.rows(GRANT)) {
+    if (g.customer !== customer || g.voided_at != null) continue;
+    if (typeof g.expires_at === 'number' && g.expires_at <= now) continue;
+    const monetary = objectOf(objectOf(g.amount).monetary);
+    const cur = String(monetary.currency ?? 'usd');
+    byCurrency[cur] = (byCurrency[cur] ?? 0) + (Number(monetary.value) || 0);
+  }
+  const balances = Object.entries(byCurrency).map(([currency, value]) => ({
+    available_balance: { type: 'monetary', monetary: { currency, value } },
+    ledger_balance: { type: 'monetary', monetary: { currency, value } },
+  }));
+  return ctx.reply({ object: 'billing.credit_balance_summary', customer, balances, livemode: false });
+};
+
+// ── alerts: a usage threshold on a meter ──
+
+const ALERT = 'billing.alert';
+
+const createAlert: Semantics = async (ctx) => {
+  const params = ctx.params;
+  if (params.alert_type !== 'usage_threshold') return fail(ctx, 'Invalid alert_type: must be usage_threshold.', 400, 'parameter_invalid_string_enum');
+  if (typeof params.title !== 'string' || !params.title) return fail(ctx, 'Missing required param: title.', 400, 'parameter_missing');
+  const ut = params.usage_threshold && typeof params.usage_threshold === 'object' ? (params.usage_threshold as Row) : undefined;
+  if (!ut || ut.gte === undefined || typeof ut.meter !== 'string') return fail(ctx, 'Missing required param: usage_threshold[gte] and usage_threshold[meter].', 400, 'parameter_missing');
+  // the spec requires recurrence too (one_time: the alert fires once)
+  if (ut.recurrence === undefined || ut.recurrence === '') return fail(ctx, 'Missing required param: usage_threshold[recurrence].', 400, 'parameter_missing');
+  if (!ctx.get(METER, ut.meter)) return fail(ctx, `No such meter: '${ut.meter}'`, 400, 'resource_missing');
+  return ctx.reply(
+    await created(ctx, ALERT, {}, {
+      alert_type: 'usage_threshold', livemode: false, status: 'active', title: params.title,
+      usage_threshold: { gte: Math.trunc(Number(ut.gte) || 0), meter: ut.meter, recurrence: String(ut.recurrence), filters: null },
+    }),
+  );
+};
+
+const listAlerts: Semantics = async (ctx) =>
+  list(ctx, ALERT, where(ctx, newest(ctx, ALERT), {
+    alert_type: (a, v) => a.alert_type === v,
+    meter: (a, v) => objectOf(a.usage_threshold).meter === v,
+  }));
+
+function alertMove(kind: 'activate' | 'deactivate' | 'archive', operationId: string): Semantics {
+  return async (ctx) => {
+    const id = at(ctx, 'id');
+    const a = ctx.get(ALERT, id);
+    if (!a) return fail(ctx, `No such alert: '${id}'`, 404, 'resource_missing');
+    const refused = ctx.legal(ALERT, 'status', operationId, a.status, undefined, id);
+    if (refused) return ctx.refuse(refused);
+    const status = kind === 'activate' ? 'active' : kind === 'deactivate' ? 'inactive' : 'archived';
+    return ctx.reply(await ctx.write(ALERT, id, { status }, `billing_alert.${kind}`));
+  };
+}
+
+export const billing: Record<string, Semantics> = {
+  PostBillingMeters: createMeter,
+  PostBillingMetersIdDeactivate: activation('deactivate'),
+  PostBillingMetersIdReactivate: activation('reactivate'),
+  PostBillingMeterEvents: reportUsage,
+  GetBillingMetersIdEventSummaries: eventSummaries,
+  PostBillingCreditGrants: createGrant,
+  PostBillingCreditGrantsIdExpire: endGrant('expire'),
+  PostBillingCreditGrantsIdVoid: endGrant('void'),
+  PostBillingCreditGrantsId: updateGrant,
+  GetBillingCreditBalanceSummary: creditBalance,
+  PostBillingAlerts: createAlert,
+  GetBillingAlerts: listAlerts,
+  PostBillingAlertsIdActivate: alertMove('activate', 'PostBillingAlertsIdActivate'),
+  PostBillingAlertsIdDeactivate: alertMove('deactivate', 'PostBillingAlertsIdDeactivate'),
+  PostBillingAlertsIdArchive: alertMove('archive', 'PostBillingAlertsIdArchive'),
+};

package/src/semantics/charges.ts

@@ -0,0 +1,211 @@
+// Charge semantics. The machine in ../manifest.ts says a charge is captured once; these handlers
+// compute the money: a charge's `refunds` sub-list is derived on every read from the refunds that
+// point at it, never a stored snapshot, while the cumulative `amount_refunded` / `refunded` stay
+// stored (a partial capture moves them for a reason that is also a Refund row).
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { asBool, cardError, chargeDefaults, declineFor, searchOver, validateMoney } from '../stripe-twin.ts';
+import { afterCharge } from './after-payment.ts';
+import { settleCharge } from './ledger.ts';
+import { paymentMethodDetails } from './payment-methods.ts';
+import { refundCharge } from './refunds.ts';
+import { at, created, expanded, fail, finder, list, newest, path, refundDestination, send, where, type Row } from './shared.ts';
+
+const chargeMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such charge: '${id}'`, 404, 'resource_missing');
+
+/** Every egress of a charge carries its refunds, derived from the refund rows in list order. */
+export function chargeBody(ctx: SemanticsContext, c: Row): Row {
+  const data = newest(ctx, 'refund').filter((r) => r.charge === c.id);
+  return { ...c, refunds: { object: 'list', data, has_more: false, total_count: data.length, url: `/v1/charges/${String(c.id)}/refunds` } };
+}
+
+// A charge is written as the event Stripe sends for it (docs.stripe.com/api/events/types; Stripe has no
+// `charge.created`): charge.succeeded, "Occurs whenever a charge is successful", for one made or authorized
+// (capture=false: its status is succeeded, captured false), and charge.failed, "Occurs whenever a failed charge attempt
+// occurs", for a declined attempt. The twin makes no pending charge (charge.pending, "Occurs whenever a pending charge is
+// created"): its charges settle when made.
+/** A Charges-API charge a declining test card refuses: a 402 card_error naming the failed charge Stripe records for the
+ *  attempt (docs.stripe.com/declines). */
+async function declinedCharge(ctx: SemanticsContext, decline: { code: string; decline_code?: string; message: string }): Promise<Response> {
+  const params = ctx.params;
+  const failedId = ctx.mint('charge');
+  const amount = Number(params.amount) || 0;
+  await created(ctx, 'charge', { ...params, id: failedId }, {
+    ...chargeDefaults(failedId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
+    failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
+    outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
+    payment_method_details: paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card) ?? null,
+  }, { operation: 'charge.failed' });
+  return send(ctx, cardError(decline, { charge: failedId }));
+}
+
+/** A charge's fraud report: "user_report … Assessments reported by you. If set, possible values of are `safe` and
+ *  `fraudulent`" (docs.stripe.com/api/charges/object, fraud_details). */
+function fraudReport(ctx: SemanticsContext, existing: Row, fd: Row): Row | Response {
+  const report = String(fd.user_report);
+  if (report !== 'safe' && report !== 'fraudulent') return fail(ctx, "Invalid fraud_details[user_report]: must be 'safe' or 'fraudulent'.", 400, 'parameter_invalid_string_enum');
+  const prior = existing.fraud_details && typeof existing.fraud_details === 'object' ? (existing.fraud_details as Row) : {};
+  return { user_report: report, stripe_report: prior.stripe_report ?? null };
+}
+
+const create: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const bad = validateMoney(params);
+  if (bad) return send(ctx, bad);
+  // a declining test card answers a 402 card_error naming the failed charge Stripe records for the attempt
+  const decline = declineFor(finder(ctx), params);
+  if (decline) return declinedCharge(ctx, decline);
+  // capture=false authorizes only: succeeded and paid, but not captured, with a capture deadline
+  const captured = !(params.capture !== undefined && !asBool(params.capture));
+  // the id comes first so the charge's own `refunds` list can carry its URL
+  const id = typeof params.id === 'string' && params.id ? params.id : ctx.mint('charge');
+  const amount = Number(params.amount) || 0;
+  // a captured charge credits the balance; an authorization does when it is captured
+  const card = String(params.source ?? params.payment_method ?? (params.card as Row | undefined)?.number ?? '');
+  const bt = captured ? await settleCharge(ctx, id, amount, String(params.currency ?? 'usd'), card) : null;
+  const details = paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card);
+  await created(ctx, 'charge', { ...params, id }, { ...chargeDefaults(id, amount, captured, ctx.occurredAt), balance_transaction: bt, payment_method_details: details ?? null }, { operation: 'charge.succeeded' });
+  await afterCharge(ctx, id, { amount, currency: String(params.currency ?? 'usd'), application_fee_amount: params.application_fee_amount, destination: (params.transfer_data as Row | undefined)?.destination }, params.payment_method ?? params.source ?? params.card);
+  return ctx.reply(chargeBody(ctx, ctx.get('charge', id)!));
+};
+
+// capture takes `amount` (the whole authorization by default; docs.stripe.com/api/charges/capture); the rest of a
+// partial capture is released with no Refund (captureAuthorization). `amount_to_capture` is the
+// PaymentIntent capture's parameter, which a charge's capture does not know.
+const capture: Semantics = async (ctx) => {
+  const id = at(ctx, 'charge');
+  const ch = ctx.get('charge', id);
+  if (!ch) return chargeMissing(ctx, id);
+  const refused = ctx.legal('charge', 'captured', 'PostChargesChargeCapture', ch.captured === true ? 'true' : 'false', undefined, id);
+  if (refused) return ctx.refuse(refused);
+  // "Capturing a charge will always succeed, unless the charge is already refunded, expired, captured, or an invalid
+  // capture amount is specified" (docs.stripe.com/api/charges/capture): a released authorization is refunded
+  if (ch.refunded === true) return fail(ctx, `Charge ${id} has already been refunded.`, 400, 'charge_already_refunded');
+  // a canceled PaymentIntent's authorization is released: "After it's canceled, no additional charges are made by the
+  // PaymentIntent and any operations on the PaymentIntent fail with an error" (docs.stripe.com/api/payment_intents/cancel).
+  // Where the documentation stops and the twin decides: its charge's capture answers payment_intent_unexpected_state
+  // ("The PaymentIntent's state was incompatible with the operation", docs.stripe.com/error-codes), in the twin's words.
+  const intent = typeof ch.payment_intent === 'string' ? ctx.get('payment_intent', ch.payment_intent) : undefined;
+  if (intent?.status === 'canceled') return fail(ctx, `Charge ${id} belongs to PaymentIntent ${String(intent.id)}, which is canceled; its authorization was released.`, 400, 'payment_intent_unexpected_state');
+  const full = Number(ch.amount) || 0;
+  const toCapture = ctx.params.amount !== undefined ? Math.min(full, Math.max(0, Math.trunc(Number(ctx.params.amount) || 0))) : full;
+  return ctx.reply(chargeBody(ctx, await captureAuthorization(ctx, ch, toCapture, 'PostChargesChargeCapture')));
+};
+
+/** A capture=false charge refunded while uncaptured: its authorization is released by the refund, as it would be
+ *  "automatically refunded if uncaptured" (spec/openapi.json.gz, `capture_before`). The charge stays uncaptured and
+ *  becomes refunded in full, a Refund records the release, and no money moves: none was ever received. Written as
+ *  charge.refunded. Where the documentation stops and the twin decides: Stripe's basil change ("Partially capturing or
+ *  canceling payments no longer creates a Refund", docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-
+ *  capture-and-payment-cancellation-flow) names partial capture and cancellation, not a refund asked for, so a refund
+ *  still makes one; its reason is null and it has no balance transaction. Answers the Refund. */
+export async function releaseAuthorization(ctx: SemanticsContext, ch: Row, operationId: string, given: Row = {}): Promise<Row> {
+  const id = String(ch.id);
+  const full = Number(ch.amount) || 0;
+  if (ch.refunded !== true) ctx.legal('charge', 'refunded', operationId, 'false', 'true', id);
+  const refund = await created(ctx, 'refund', { ...given, charge: id, amount: full - (Number(ch.amount_refunded) || 0), currency: String(ch.currency ?? 'usd') }, {
+    status: 'succeeded', metadata: {}, reason: null, receipt_number: null,
+    balance_transaction: null, source_transfer_reversal: null, transfer_reversal: null, ...refundDestination(ch, 'reversal'),
+    ...(typeof ch.payment_intent === 'string' ? { payment_intent: ch.payment_intent } : {}),
+  });
+  await ctx.write('charge', id, { amount_refunded: full, refunded: true }, 'charge.refunded');
+  return refund;
+}
+
+/** A PaymentIntent's authorization released by its cancel: "For PaymentIntents with a `status` of `requires_capture`, the
+ *  remaining `amount_capturable` is automatically refunded" (docs.stripe.com/api/payment_intents/cancel), and since basil
+ *  a cancellation makes no Refund: "`amount_captured` will be 0 instead of `nil` in payment cancellation flows",
+ *  "`amount_refunded` will no longer be updated by these actions", "`refunded` will no longer be `true` for payment
+ *  cancellation flows", and no charge.refunded is sent (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-
+ *  partial-capture-and-payment-cancellation-flow). The charge stays uncaptured; nothing is written as an event. */
+export async function cancelAuthorization(ctx: SemanticsContext, ch: Row): Promise<Row> {
+  return ctx.write('charge', String(ch.id), { amount_captured: 0 }, 'charge.authorization_released');
+}
+
+/** An authorized charge captured, by the charge's capture or its PaymentIntent's: what is captured credits the balance.
+ *  Written as charge.captured, "Occurs whenever a previously uncaptured charge is captured" (docs.stripe.com/api/events/types).
+ *  A partial capture releases the rest with no Refund and leaves amount_refunded and refunded as they were: "The following
+ *  flows no longer result in a `Refund` object created and linked to the payment: Partial capture", "`amount_refunded`
+ *  will no longer be updated by these actions", and "There will only be a single balance transaction for partial captures"
+ *  (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-capture-and-payment-cancellation-flow).
+ *  The caller has asked the machine whether it may capture. */
+export async function captureAuthorization(ctx: SemanticsContext, ch: Row, toCapture: number, _operationId: string): Promise<Row> {
+  const id = String(ch.id);
+  const bt = toCapture > 0 ? await settleCharge(ctx, id, toCapture, String(ch.currency ?? 'usd'), String(ch.source ?? ch.payment_method ?? '')) : null;
+  return ctx.write('charge', id, { captured: true, amount_captured: toCapture, balance_transaction: bt }, 'charge.captured');
+}
+
+const listCharges: Semantics = async (ctx) => {
+  const items = where(ctx, newest(ctx, 'charge'), {
+    customer: (c, v) => c.customer === v,
+    payment_intent: (c, v) => c.payment_intent === v,
+  });
+  return list(ctx, 'charge', items.map((c) => chargeBody(ctx, c)));
+};
+
+const searchCharges: Semantics = async (ctx) => {
+  const found = searchOver(newest(ctx, 'charge'), ctx.params, path(ctx));
+  const body = found.body as { data?: Row[] };
+  if (found.status === 200 && Array.isArray(body.data)) body.data = body.data.map((c) => chargeBody(ctx, c));
+  return send(ctx, found);
+};
+
+const retrieve: Semantics = async (ctx) => {
+  const c = ctx.get('charge', at(ctx, 'charge'));
+  return c ? ctx.reply(expanded(ctx, 'charge', chargeBody(ctx, c))) : chargeMissing(ctx, at(ctx, 'charge'));
+};
+
+// fraud_details[user_report] marks a charge safe or fraudulent; Stripe keeps its own stripe_report
+const update: Semantics = async (ctx) => {
+  const id = at(ctx, 'charge');
+  const existing = ctx.get('charge', id);
+  if (!existing) return chargeMissing(ctx, id);
+  const fields: Row = { ...ctx.params };
+  const fd = ctx.params.fraud_details;
+  const fraud = fd && typeof fd === 'object' && 'user_report' in (fd as Row) ? fraudReport(ctx, existing, fd as Row) : undefined;
+  if (fraud instanceof Response) return fraud;
+  if (fraud) fields.fraud_details = fraud;
+  return ctx.reply(chargeBody(ctx, await ctx.write('charge', id, fields, 'charge.update')));
+};
+
+// ── the charge's own refunds: listed, created and read through it; another charge's refund is not found ──
+
+const refunds: Semantics = async (ctx) => {
+  const id = at(ctx, 'charge');
+  if (!ctx.get('charge', id)) return chargeMissing(ctx, id);
+  return list(ctx, 'refund', newest(ctx, 'refund').filter((r) => r.charge === id));
+};
+
+const createRefund: Semantics = async (ctx) => {
+  const ch = ctx.get('charge', at(ctx, 'charge'));
+  if (!ch) return chargeMissing(ctx, at(ctx, 'charge'));
+  return refundCharge(ctx, ch, ctx.params);
+};
+
+const chargeRefund = (ctx: SemanticsContext): Row | Response => {
+  if (!ctx.get('charge', at(ctx, 'charge'))) return chargeMissing(ctx, at(ctx, 'charge'));
+  const r = ctx.get('refund', at(ctx, 'refund'));
+  return r && r.charge === at(ctx, 'charge') ? r : fail(ctx, `No such refund: '${at(ctx, 'refund')}'`, 404, 'resource_missing');
+};
+
+const refund: Semantics = async (ctx) => {
+  const r = chargeRefund(ctx);
+  return r instanceof Response ? r : ctx.reply(r);
+};
+
+const updateRefund: Semantics = async (ctx) => {
+  const r = chargeRefund(ctx);
+  return r instanceof Response ? r : ctx.reply(await ctx.write('refund', at(ctx, 'refund'), ctx.params, 'refund.update'));
+};
+
+export const charges: Record<string, Semantics> = {
+  PostCharges: create,
+  PostChargesChargeCapture: capture,
+  GetCharges: listCharges,
+  GetChargesSearch: searchCharges,
+  GetChargesCharge: retrieve,
+  PostChargesCharge: update,
+  GetChargesChargeRefunds: refunds,
+  PostChargesChargeRefunds: createRefund,
+  GetChargesChargeRefundsRefund: refund,
+  PostChargesChargeRefundsRefund: updateRefund,
+};