@volter/twin-stripe 2.0.38 → 3.0.1

package/src/semantics/charges.ts

@@ -1,220 +1,16 @@
-// 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.
-/** The create's parameters as the charge keeps them: without `card`, the request's card details ("A token, like the ones
- *  returned by Stripe.js", or a hash of the number, expiry and CVC). The Charge object has no `card` property (served
- *  spec, charge); the card it was made with is its payment_method_details. Kept, it answered the card's full number and
- *  CVC back on every read of the charge. */
-function withoutCard(params: Row): Row {
-  const { card: _card, ...rest } = params;
-  return rest;
-}
-
-/** 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', { ...withoutCard(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', { ...withoutCard(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) => {
+// Stripe's charges 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 { at, chargeBody, chargeMissing, expanded, list, newest, where } from './shared.ts';
+export async function GetCharges(ctx: HandlerContext): Promise<Response> {
   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) => {
+export async function GetChargesCharge(ctx: HandlerContext): Promise<Response> {
   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,
-};
+}

package/src/semantics/checkout.ts

@@ -1,108 +1,35 @@
-// 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 !== ''));
+// 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 GetCheckoutSessionsSessionLineItems(ctx: HandlerContext): Promise<Response> {
+  const s = ctx.get(CS, at(ctx, 'session'));
+  if (!s) return sessionMissing(ctx, at(ctx, 'session'));
+  // source: spec:GetCheckoutSessionsSessionLineItems "There is also a URL where you can retrieve the full (paginated) list of line items."
+  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 create: Semantics = async (ctx) => {
+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');
   const entries = lineItemEntries(params);
   if (mode !== 'setup' && entries.length === 0) return noLineItems(ctx);
-  // hosted Checkout (the only ui_mode the twin models) needs success_url
-  if (params.success_url === undefined || params.success_url === '') return fail(ctx, 'Missing required param: success_url.', 400, 'parameter_missing');
+  // source: spec:/paths/~1v1~1checkout~1sessions/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/ui_mode "The UI mode of the Session."
+  const custom = params.ui_mode === 'custom';
+  if (!custom && (params.success_url === undefined || params.success_url === '')) return fail(ctx, 'Missing required param: success_url.', 400, 'parameter_missing');
   const sessionCurrency = typeof params.currency === 'string' ? params.currency : 'usd';
   const resolved = entries.map((e, i) => resolveLineItem(e, i, sessionCurrency, finder(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);
@@ -114,7 +41,10 @@ const create: Semantics = async (ctx) => {
   const fields: Row = {
     mode, status: 'open',
     payment_status: mode === 'setup' ? 'no_payment_required' : 'unpaid',
-    url: `https://checkout.stripe.com/c/pay/${id}`, success_url: params.success_url ?? null, cancel_url: params.cancel_url ?? null,
+    ui_mode: custom ? 'custom' : 'hosted',
+    ...(custom ? { client_secret: `${id}_secret_${await ctx.secret(`checkout-secret:${id}`)}`, return_url: params.return_url ?? null } : {}),
+    allow_promotion_codes: params.allow_promotion_codes === true || params.allow_promotion_codes === 'true',
+    url: custom ? null : `https://checkout.stripe.com/c/pay/${id}`, success_url: params.success_url ?? null, cancel_url: params.cancel_url ?? null,
     customer: params.customer ?? null, client_reference_id: params.client_reference_id ?? null,
     customer_email: params.customer_email ?? null,
     // whether paying makes a customer: in payment mode only when asked (`always`), `if_required` by default
@@ -144,190 +74,9 @@ 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) => {
-  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,19 @@
+// 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, lapseCoupons, lapseRealtimeRequests, settleBankDebits, settleHeldRefunds } from './shared.ts';
+export async function clock(ctx: HandlerContext): Promise<void> {
+  // 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 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);
+}