@volter/twin-stripe 2.0.38 → 3.0.0

package/src/semantics/checkout.ts

@@ -1,95 +1,12 @@
-// Checkout Session semantics. The machine in ../manifest.ts says an open session expires or
-// completes and nothing else does. Stripe completes a session when the customer pays on its hosted
-// page (src/screens/checkout.tsx, the session's url), which has no API verb; completing links what
-// the payment made: a succeeded PaymentIntent, an active (or
-// trialing) subscription, or a succeeded SetupIntent. List and retrieve are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { addBillingInterval, applyCouponDiscount, buildDiscount, buildSubscriptionItemsList, declineFor, lineItemEntries, mintClientSecret, paginate, paymentMethodSubObject, resolveLineItem, resolveSubscriptionBillingInterval, resolveTrial } from '../stripe-twin.ts';
-import { afterSuccessOf } from './after-payment.ts';
-import { actingAccount } from './ledger.ts';
-import { mintCharge } from './payment-intents.ts';
-import { collectSubscriptionInvoice, draftSubscriptionInvoice } from './renewals.ts';
-import { storeItems } from './subscriptions.ts';
-import { at, created, fail, finder, path, redeemCoupon, type Row } from './shared.ts';
-
-const CS = 'checkout.session';
-const sessionMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such checkout.session: '${id}'`, 404, 'resource_missing');
-
-// Stripe normalizes the create input into the Session: line_items become the list envelope, and
-// subscription_data (create-only) is kept aside for completion to copy onto the subscription
-/** The discount a session is created with (discounts[0][promotion_code] or [coupon]), or Stripe's refusal: an unknown
- *  code or coupon, and one that has expired or been deactivated, are refused at create
- *  (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-discounts, docs.stripe.com/error-codes#coupon-expired).
- *  Where the documentation stops and the twin decides: the refusals' wording. */
-function discountOf(ctx: SemanticsContext, params: Row, now: number): { coupon: Row; promotion?: string } | Response | undefined {
-  const first = Array.isArray(params.discounts) ? (params.discounts[0] as Row | undefined) : undefined;
-  if (!first || typeof first !== 'object') return undefined;
-  const expired = (what: string) => ctx.refuse({ status: 400, code: 'coupon_expired', param: 'discounts', message: `This ${what} has expired.` });
-  let promotion: string | undefined;
-  let couponId = typeof first.coupon === 'string' ? first.coupon : undefined;
-  if (typeof first.promotion_code === 'string') {
-    const pc = ctx.get('promotion_code', first.promotion_code);
-    if (!pc) return ctx.refuse({ status: 400, code: 'resource_missing', param: 'discounts[0][promotion_code]', message: `No such promotion code: '${first.promotion_code}'` });
-    if (typeof pc.expires_at === 'number' && pc.expires_at <= now) return expired('promotion code');
-    if (pc.active === false) return ctx.refuse({ status: 400, param: 'discounts[0][promotion_code]', message: 'This promotion code is inactive.' });
-    promotion = String(pc.id);
-    couponId = typeof pc.coupon === 'string' ? pc.coupon : String((pc.coupon as Row | undefined)?.id ?? '');
-  }
-  const coupon = couponId ? ctx.get('coupon', couponId) : undefined;
-  if (!coupon) return ctx.refuse({ status: 400, code: 'resource_missing', param: 'discounts[0][coupon]', message: `No such coupon: '${couponId ?? ''}'` });
-  if (coupon.valid === false || (typeof coupon.redeem_by === 'number' && coupon.redeem_by <= now)) return expired('coupon');
-  return { coupon, ...(promotion ? { promotion } : {}) };
-}
-
-/** A payment or subscription session with nothing to sell (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-line_items). */
-function noLineItems(ctx: SemanticsContext): Response {
-  return fail(ctx, 'You must provide at least one recurring price in `subscription` mode when not using `line_items[].price_data` or a Price with `recurring`, and at least one `line_items` for `payment` mode.', 400, 'parameter_missing');
-}
-
-/** A destination charge to an account the platform does not have (docs.stripe.com/connect/destination-charges). */
-function noDestination(ctx: SemanticsContext, destination: unknown): Response {
-  return ctx.refuse({ status: 400, code: 'resource_missing', param: 'payment_intent_data[transfer_data][destination]', message: `No such destination: '${String(destination)}'` });
-}
-
-/** A session's trial Stripe refuses: `subscription_data.trial_end` "Has to be at least 48 hours in the future", and
- *  `subscription_data.trial_period_days` "Has to be at least 1" (docs.stripe.com/api/checkout/sessions/create). Where the
- *  documentation stops and the twin decides: the refusals' wording. */
-function sessionTrialRefused(ctx: SemanticsContext, data: unknown, now: number): Response | undefined {
-  if (!data || typeof data !== 'object') return undefined;
-  const { trial_end: end, trial_period_days: days } = data as Row;
-  const endRefused = end !== undefined && !(Number.isInteger(Number(end)) && Number(end) >= now + 48 * 3600);
-  const daysRefused = days !== undefined && !(Number.isInteger(Number(days)) && Number(days) >= 1);
-  return endRefused || daysRefused ? sessionTrialRefusal(ctx, endRefused ? 'trial_end' : 'trial_period_days') : undefined;
-}
-
-function sessionTrialRefusal(ctx: SemanticsContext, param: 'trial_end' | 'trial_period_days'): Response {
-  const message = param === 'trial_end' ? 'The `subscription_data[trial_end]` timestamp has to be at least 48 hours in the future.' : 'The `subscription_data[trial_period_days]` has to be at least 1.';
-  return ctx.refuse({ status: 400, param: `subscription_data[${param}]`, message });
-}
-
-/** The payment method types a session takes: the list a caller pinned to an earlier version gives as
- *  payment_method_types ("A list of the types of payment methods (e.g., `card`) this Checkout Session can accept", the
- *  parameter the served version's allowed_payment_method_types is described against: "Unlike `payment_method_types`,
- *  this acts as a filter on the dynamically computed set of eligible payment methods", docs.stripe.com/api/checkout/
- *  sessions/create), else the allowed_payment_method_types of the served one, else card. Where the documentation stops
- *  and the twin decides: an allowed list is answered whole (the twin does not compute eligibility), and without one the
- *  session takes card (the account's enabled methods are not modelled). */
-function sessionMethodTypes(params: Row): string[] {
-  const given = Array.isArray(params.payment_method_types) ? params.payment_method_types : params.allowed_payment_method_types;
-  return Array.isArray(given) && given.length ? given.map(String) : ['card'];
-}
-
-/** Metadata passed on to what a session makes (payment_intent_data[metadata], subscription_data[metadata]) as a
- *  create's own is kept: "Individual keys can be unset by posting an empty value to them. All keys can be unset by
- *  posting an empty value to `metadata`" (every metadata parameter, docs.stripe.com/api/metadata), so a key posted
- *  empty is not set, and metadata posted empty is {} (stripe-server.ts createMetadata, the top-level case). */
-export function nestedMetadata(given: unknown): Row | undefined {
-  if (given === '') return {};
-  if (!given || typeof given !== 'object' || Array.isArray(given)) return undefined;
-  return Object.fromEntries(Object.entries(given as Row).filter(([, v]) => v !== ''));
-}
-
-const create: Semantics = async (ctx) => {
+// Stripe's checkout 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 { CS, sessionMethodTypes } from '../engine/checkout.ts';
+import type { Row } from '../engine/common.ts';
+import { applyCouponDiscount, lineItemEntries, nowUnix, paginate, resolveLineItem } from '../engine/stripe.ts';
+import { actingAccount, at, checkoutNoDestination, created, discountOf, fail, finder, noLineItems, path, sessionMissing, sessionTrialRefused } from './shared.ts';
+
+export async function PostCheckoutSessions(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
   const mode = typeof params.mode === 'string' ? params.mode : 'payment';
   if (!['payment', 'subscription', 'setup'].includes(mode)) return fail(ctx, 'Invalid mode: must be one of payment, subscription, or setup.', 400, 'parameter_invalid_string_enum');
@@ -102,7 +19,7 @@ const create: Semantics = async (ctx) => {
   const missing = resolved.find((r) => r.priceMissing);
   if (missing) return fail(ctx, `No such price: '${missing.priceMissing}'`, 400, 'resource_missing');
   const items = resolved.map((r) => r.item);
-  const now = Number(ctx.now());
+  const now = Number(nowUnix(ctx.occurredAt));
   const trialRefused = sessionTrialRefused(ctx, params.subscription_data, now);
   if (trialRefused) return trialRefused;
   const discount = discountOf(ctx, params, now);
@@ -144,190 +61,18 @@ const create: Semantics = async (ctx) => {
   const pid = params.payment_intent_data && typeof params.payment_intent_data === 'object' ? (params.payment_intent_data as Row) : undefined;
   if (pid && mode === 'payment') {
     const destination = (pid.transfer_data as Row | undefined)?.destination;
-    if (destination !== undefined && (typeof destination !== 'string' || !ctx.get('account', destination))) return noDestination(ctx, destination);
+    if (destination !== undefined && (typeof destination !== 'string' || !ctx.get('account', destination))) return checkoutNoDestination(ctx, destination);
     fields._payment_intent_data = pid;
   }
   if (discount) fields._discount = { coupon: String(discount.coupon.id), promotion_code: discount.promotion ?? null };
   return ctx.reply(await created(ctx, CS, { id, ...fields }, {}));
-};
-
-// the session's items, a page at a time
-const lineItems: Semantics = async (ctx) => {
-  const s = ctx.get(CS, at(ctx, 'session'));
-  if (!s) return sessionMissing(ctx, at(ctx, 'session'));
-  const li = s.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 expire: Semantics = async (ctx) => {
+export async function PostCheckoutSessionsSessionExpire(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'session');
   const s = ctx.get(CS, id);
   if (!s) return sessionMissing(ctx, id);
   const refused = ctx.legal(CS, 'status', 'PostCheckoutSessionsSessionExpire', s.status, undefined, id);
   if (refused) return ctx.refuse(refused);
   return ctx.reply(await ctx.write(CS, id, { status: 'expired', url: null }, 'checkout.session.expire'));
-};
-
-/** The card the customer entered on the page. */
-export type EnteredCard = { number: string; exp_month: number; exp_year: number };
-
-/** What completing a session makes, by its mode, as the fields that link it: a payment is a PaymentIntent paid with
- *  the entered card, its charge in the ledger as any payment's is. */
-async function complete(ctx: SemanticsContext, id: string, existing: Row, card?: EnteredCard): Promise<Row> {
-  const link: Row = { status: 'complete' };
-  const customer = typeof existing.customer === 'string' ? existing.customer : undefined;
-  const currency = typeof existing.currency === 'string' ? existing.currency : 'usd';
-  // the entered card becomes a PaymentMethod carrying what a later charge to it answers and what Stripe does after it
-  // succeeds (docs.stripe.com/testing#declined-payments, #disputes)
-  const made = card ? await created(ctx, 'payment_method', {}, { type: 'card', customer: null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null, ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}) }) : undefined;
-  // and Checkout attaches it to the customer when it saves it: a subscription's card ("If your Checkout Session uses
-  // subscription mode, Stripe saves the payment method by default", docs.stripe.com/payments/checkout/how-checkout-works),
-  // a setup session's (it exists to save one), and a payment's only under payment_intent_data.setup_future_usage ("to have
-  // Checkout automatically attach the payment method to the Customer you pass in", docs.stripe.com/api/checkout/sessions/
-  // create#create_checkout_session-customer). Attaching is its own write, so payment_method.attached is delivered ("Occurs
-  // whenever a new payment method is attached to a customer", docs.stripe.com/api/events/types) before what the card then
-  // pays for. Where the documentation stops and the twin decides: the order of the events, which Stripe does not
-  // guarantee (docs.stripe.com/webhooks#event-ordering). A gap: the customer's own opt-in to save a payment's card
-  // (saved_payment_method_options.payment_method_save) is not modelled; the page offers no such box.
-  const saves = existing.mode !== 'payment' || !!((ctx.row(CS, id)?._payment_intent_data ?? {}) as Row).setup_future_usage;
-  const pm = made && customer && saves ? await ctx.write('payment_method', String(made.id), { customer }, 'payment_method.attach') : made;
-  if (existing.mode === 'payment') {
-    const amount = Number(existing.amount_total) || 0;
-    const piId = ctx.mint('payment_intent');
-    const pid = (ctx.row(CS, id)?._payment_intent_data ?? {}) as Row;
-    const connect = {
-      ...(pid.application_fee_amount !== undefined ? { application_fee_amount: Math.trunc(Number(pid.application_fee_amount) || 0) } : {}),
-      ...(pid.transfer_data && typeof pid.transfer_data === 'object' ? { transfer_data: { destination: (pid.transfer_data as Row).destination } } : {}),
-      ...(typeof pid.description === 'string' ? { description: pid.description } : {}),
-      // the session's setup_future_usage is its PaymentIntent's (payment_intent_data: "A subset of parameters to be passed to PaymentIntent creation")
-      ...(typeof pid.setup_future_usage === 'string' ? { setup_future_usage: pid.setup_future_usage } : {}),
-      ...(nestedMetadata(pid.metadata) ? { metadata: nestedMetadata(pid.metadata) } : {}),
-    };
-    const fields = { amount, currency, id: piId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}), ...connect };
-    await created(ctx, 'payment_intent', fields, { status: 'succeeded', amount_received: amount, client_secret: mintClientSecret(piId), livemode: false, payment_method_types: Array.isArray(existing.payment_method_types) ? existing.payment_method_types : ['card'] });
-    const charge = await mintCharge(ctx, piId, fields, amount);
-    await ctx.write('payment_intent', piId, { latest_charge: charge }, 'payment_intent.succeeded');
-    link.payment_intent = piId;
-    link.payment_status = 'paid';
-  } else if (existing.mode === 'subscription') {
-    if (customer) {
-      // the subscription bills the session's own (already resolved) line items, and takes the
-      // session's subscription_data: metadata, description, and a trial as its first period
-      const now = Number(ctx.now());
-      // "Line items with one-time Prices will be on the initial invoice only" (docs.stripe.com/api/checkout/sessions/
-      // create#create_checkout_session-line_items): the subscription's items are the recurring ones
-      const inline = (ctx.row(CS, id)?._price_data as Array<Row | null> | undefined) ?? [];
-      const lines = ((existing.line_items as { data?: unknown } | undefined)?.data as Row[] | undefined) ?? [];
-      const allLineItems = inline.some(Boolean) ? await sessionPrices(ctx, lines, inline) : lines;
-      const sessionLineItems = allLineItems.filter((it) => !isOneTime(it));
-      const oneTime = allLineItems.filter((it) => isOneTime(it));
-      const { interval, interval_count } = resolveSubscriptionBillingInterval(sessionLineItems, finder(ctx));
-      const subId = ctx.mint('subscription');
-      // the session's view never carries its create-only subscription_data: read the stored row
-      const raw = ctx.row(CS, id)?._subscription_data;
-      const subData = (raw && typeof raw === 'object' ? raw : {}) as Row;
-      const subMetadata = nestedMetadata(subData.metadata) ?? {};
-      // a trial of `trial_period_days` from now, or to `trial_end` (docs.stripe.com/payments/checkout/free-trials)
-      const trialEnd = resolveTrial(subData, now)?.end ?? null;
-      const sub = await created(ctx, 'subscription', { customer, id: subId }, {
-        status: trialEnd === null ? 'active' : 'trialing', livemode: false, currency, collection_method: 'charge_automatically',
-        // a trial's end is the billing anchor (docs.stripe.com/api/subscriptions/create#create_subscription-trial_end)
-        cancel_at_period_end: false, start_date: now, billing_cycle_anchor: trialEnd ?? now, metadata: subMetadata,
-        description: typeof subData.description === 'string' ? subData.description : null,
-        // the session's discount is the subscription's (docs.stripe.com/payments/checkout/discounts)
-        discounts: sessionDiscount(ctx, id, customer, now), billing_schedules: [],
-        trial_start: trialEnd === null ? null : now, trial_end: trialEnd,
-        current_period_start: now, current_period_end: trialEnd ?? addBillingInterval(now, interval, interval_count),
-        // Checkout saves the card as the subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works)
-        default_payment_method: pm?.id ?? null,
-        items: buildSubscriptionItemsList(sessionLineItems, subId, now, finder(ctx)),
-        automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' },
-        invoice_settings: { issuer: { type: 'self' } },
-      });
-      await storeItems(ctx, subId, ((sub.items as Row | undefined)?.data as Row[] | undefined) ?? []);
-      // its first invoice, paid on the page by the card just entered (nothing is due on a trial's)
-      // (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions)
-      const invoice = await draftSubscriptionInvoice(ctx, sub, { start: now, end: Number(sub.current_period_end), reason: 'subscription_create', trial: trialEnd !== null, once: oneTime });
-      await collectSubscriptionInvoice(ctx, invoice, now, 'external');
-      await ctx.write('subscription', subId, { latest_invoice: invoice }, 'subscription.update');
-      link.subscription = sub.id;
-      link.invoice = invoice;
-    }
-    link.payment_status = 'paid';
-  } else link.setup_intent = await completeSetup(ctx, customer, pm);
-  return link;
-}
-
-/** A line item of a one-time Price: a stored Price, or an inline `price_data`, without `recurring` ("Line items with
- *  one-time Prices will be on the initial invoice only", docs.stripe.com/api/checkout/sessions/create). */
-export function isOneTime(item: Row, priceData?: Row | null): boolean {
-  if (priceData) return !priceData.recurring;
-  return !!item.price && typeof item.price === 'object' && !(item.price as Row).recurring;
-}
-
-/** A subscription session's lines at completion, each inline `price_data` made the Price it generates ("Data used to
- *  generate a new Price object inline", the same page), under the product it names or one made from its product_data,
- *  so the subscription's items bill it. Where the documentation stops and the twin decides: such a Price is archived
- *  (active=false), as a subscription item's price_data makes one (docs.stripe.com/products-prices/manage-prices). */
-async function sessionPrices(ctx: SemanticsContext, lines: Row[], inline: Array<Row | null>): Promise<Row[]> {
-  const out: Row[] = [];
-  for (const [i, line] of lines.entries()) {
-    const d = inline[i];
-    if (!d) { out.push(line); continue; }
-    const pd = d.product_data && typeof d.product_data === 'object' ? (d.product_data as Row) : undefined;
-    const product = typeof d.product === 'string' ? d.product : String((await created(ctx, 'product', { name: pd?.name ?? 'Item' }, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: ctx.now() })).id);
-    const r = d.recurring && typeof d.recurring === 'object' ? (d.recurring as Row) : undefined;
-    const price = await created(ctx, 'price', {
-      product, currency: String(d.currency ?? line.currency ?? 'usd').toLowerCase(),
-      unit_amount: d.unit_amount_decimal !== undefined ? null : Math.trunc(Number(d.unit_amount) || 0),
-      unit_amount_decimal: d.unit_amount_decimal !== undefined ? String(d.unit_amount_decimal) : String(Math.trunc(Number(d.unit_amount) || 0)),
-      ...(r ? { recurring: { interval: r.interval, interval_count: Math.max(1, Math.trunc(Number(r.interval_count ?? 1)) || 1), usage_type: 'licensed', trial_period_days: null, meter: null } } : { recurring: null }),
-    }, { active: false, livemode: false, billing_scheme: 'per_unit', type: r ? 'recurring' : 'one_time', metadata: {}, lookup_key: null, nickname: null, tax_behavior: 'unspecified' });
-    out.push({ ...line, price });
-  }
-  return out;
-}
-
-/** A setup session saves the card through a succeeded SetupIntent (docs.stripe.com/payments/save-and-reuse?platform=checkout). */
-async function completeSetup(ctx: SemanticsContext, customer: string | undefined, pm: Row | undefined): Promise<unknown> {
-  const siId = ctx.mint('setup_intent');
-  const si = await created(ctx, 'setup_intent', { id: siId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}) }, { status: 'succeeded', usage: 'off_session', client_secret: mintClientSecret(siId), payment_method_types: ['card'], livemode: false });
-  return si.id;
-}
-
-/** The discount a completed subscription session gives its subscription. */
-function sessionDiscount(ctx: SemanticsContext, id: string, customer: string, now: number): Row[] {
-  const d = ctx.row(CS, id)?._discount as Row | undefined;
-  const coupon = d && typeof d.coupon === 'string' ? ctx.get('coupon', d.coupon) : undefined;
-  return coupon ? [{ ...buildDiscount(coupon, customer, now), promotion_code: d?.promotion_code ?? null, checkout_session: id }] : [];
 }
-
-/** The customer paying on the hosted page (src/screens/checkout.tsx): the external actor's move on the
- *  session's machine, then what the payment made, linked, and the session stored complete. */
-export async function completeSession(ctx: SemanticsContext, id: string, existing: Row, details: Row = {}, card?: EnteredCard): Promise<Row | Response> {
-  const refused = ctx.legal(CS, 'status', 'PostCheckoutSessionsSession', existing.status, 'complete', id, 'external');
-  if (refused) return ctx.refuse(refused);
-  const link = await complete(ctx, id, existing, card);
-  // the discount the buyer took is redeemed (shared.ts redeemCoupon)
-  const d = ctx.row(CS, id)?._discount as Row | undefined;
-  if (d) await redeemCoupon(ctx, d.coupon, d.promotion_code);
-  // the session's url "is only present when the session is active" (docs.stripe.com/api/checkout/sessions/object)
-  return ctx.write(CS, id, { ...details, ...link, url: null }, 'checkout.session.completed');
-}
-
-const update: Semantics = async (ctx) => {
-  const id = at(ctx, 'session');
-  const existing = ctx.get(CS, id);
-  if (!existing) return sessionMissing(ctx, id);
-  // a session completes only when its customer pays on the hosted page (src/screens/checkout.tsx); the API takes no
-  // status, which the parameter check refuses as Stripe does (../stripe-params.ts)
-  return ctx.reply(await ctx.write(CS, id, ctx.params, 'checkout.session.update'));
-};
-
-export const checkout: Record<string, Semantics> = {
-  PostCheckoutSessions: create,
-  GetCheckoutSessionsSessionLineItems: lineItems,
-  PostCheckoutSessionsSessionExpire: expire,
-  PostCheckoutSessionsSession: update,
-};

package/src/semantics/clock.ts

@@ -0,0 +1,26 @@
+// Stripe's own moves as time passes (docs/contributing/architecture.md, "What an author writes": clock), caught up to
+// the World's clock before anything is answered, so every door (the API, the hosted pages) reads the account as it
+// stands now. Each move is the engine's.
+import type { HandlerContext } from '@volter/world-core';
+import { advanceBilling, advancePayouts, finishClockAdvances, finishReportRuns, lapseCoupons, lapseRealtimeRequests, settleBankDebits, settleHeldRefunds, settleTopups } from './shared.ts';
+
+export async function clock(ctx: HandlerContext): Promise<void> {
+  // a test clock advanced by the last request has reached its time
+  await finishClockAdvances(ctx);
+  // a subscription renews at its period's end, its renewal charged an hour later
+  await advanceBilling(ctx);
+  // a submitted bank debit settles (in test mode at once)
+  await settleBankDebits(ctx);
+  // a coupon past its redeem_by is no longer valid
+  await lapseCoupons(ctx);
+  // a top-up's funds arrive five days after it is made
+  await settleTopups(ctx);
+  // a report run completes
+  await finishReportRuns(ctx);
+  // a real-time authorization request no one answered is decided when its window ends
+  await lapseRealtimeRequests(ctx);
+  // a refund held for want of balance is made when funds cover it, before any payout takes them
+  await settleHeldRefunds(ctx);
+  // each account's automatic payouts
+  await advancePayouts(ctx);
+}

package/src/semantics/coupons.ts

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