@volter/twin-stripe 2.0.38 → 3.0.1

package/src/screens/{portal.tsx → billing-portal.tsx}

@@ -16,20 +16,15 @@
 // (the account's default) enables cancellation at period end, updating the payment method and invoice history;
 // changing the plan from the portal is not offered yet. A new card is saved without a charge, so a card that
 // declines only when charged (4000000000000341) is saved and declines when the invoice is paid.
-import { semanticsContext, type SemanticsContext } from '@volter/world-core';
-import { flowPage, Portal, PORTAL_CSS, type PaymentField, type PortalItem } from '@volter/world-ui';
-import surface from '../generated/surface.gen.json' with { type: 'json' };
-import { manifest } from '../manifest.ts';
-import { payerOf, payOpenInvoice } from '../semantics/renewals.ts';
-import { afterSuccessOf } from '../semantics/after-payment.ts';
-import { created, type Row } from '../semantics/shared.ts';
-import { publicBusinessName } from '../stripe-shared.ts';
-import { declineFor, paymentMethodSubObject, PLATFORM_ACCOUNT_ID } from '../stripe-twin.ts';
-import { cardAnswer, COUNTRIES, money } from './checkout.tsx';
-import { formOf } from './consent-skin.ts';
-
+import type { HandlerContext } from '@volter/world-core';
+import { flowPage, type PaymentField, Portal, PORTAL_CSS, type PortalItem } from '@volter/world-ui';
+import type { Row } from '../engine/common.ts';
+import { publicBusinessName } from '../engine/display.ts';
+import { declineFor, nowUnix, paymentMethodSubObject, PLATFORM_ACCOUNT_ID } from '../engine/stripe.ts';
+import { cardAnswer, COUNTRIES, formOf, money, notFound } from './shared.tsx';
+import { resourceView, afterSuccessOf, created, payerOf, payOpenInvoice } from '../semantics/shared.ts';
 const SUB = 'subscription';
-const PORTAL_OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'PostBillingPortalSessions')!;
+const PORTAL_OPERATION = { id: 'PostBillingPortalSessions' };
 
 // Stripe's skin: its type, its purple accent, the merchant's side tinted.
 const SKIN = `
@@ -50,7 +45,7 @@ const day = (epoch: unknown): string => new Date(Number(epoch) * 1000).toLocaleD
 const gone = (): Response => flowPage({ title: 'Billing', status: 404, css: [PORTAL_CSS, SKIN], body: <main className="portal-main"><h1>This link has expired.</h1></main> });
 
 type Features = { cancel: { enabled: boolean; mode: 'at_period_end' | 'immediately' }; invoices: boolean; paymentMethod: boolean };
-function featuresOf(ctx: SemanticsContext, session: Row): Features {
+function featuresOf(ctx: HandlerContext, session: Row): Features {
   const f = (ctx.get('billing_portal.configuration', String(session.configuration))?.features ?? undefined) as Row | undefined;
   const cancel = (f?.subscription_cancel ?? {}) as Row;
   const invoices = (f?.invoice_history ?? {}) as Row;
@@ -62,7 +57,7 @@ function featuresOf(ctx: SemanticsContext, session: Row): Features {
   };
 }
 
-function planOf(ctx: SemanticsContext, sub: Row): { name: string; price: string } {
+function planOf(ctx: HandlerContext, sub: Row): { name: string; price: string } {
   const item = (((sub.items as { data?: Row[] } | undefined)?.data) ?? [])[0];
   const price = (typeof item?.price === 'object' ? item.price : ctx.get('price', String(item?.price ?? ''))) as Row | undefined;
   const product = typeof price?.product === 'string' ? ctx.get('product', price.product) : (price?.product as Row | undefined);
@@ -73,10 +68,10 @@ function planOf(ctx: SemanticsContext, sub: Row): { name: string; price: string
   };
 }
 
-function page(ctx: SemanticsContext, id: string, session: Row, problem?: { error: string; values: Record<string, string> }): Response {
+function page(ctx: HandlerContext, id: string, session: Row, problem?: { error: string; values: Record<string, string> }): Response {
   const features = featuresOf(ctx, session);
   const customer = ctx.get('customer', String(session.customer)) ?? {};
-  const subs = ctx.rows(SUB).filter((s) => s.customer === session.customer && s.status !== 'canceled' && s.status !== 'incomplete_expired');
+  const subs = ctx.rows(SUB).map((s) => ctx.expand(SUB, s)).filter((s) => s.customer === session.customer && s.status !== 'canceled' && s.status !== 'incomplete_expired');
   const plans: PortalItem[] = subs.map((s) => {
     const plan = planOf(ctx, s);
     const ending = s.cancel_at_period_end === true;
@@ -106,7 +101,7 @@ function page(ctx: SemanticsContext, id: string, session: Row, problem?: { error
       }))
     : [];
   const back = typeof session.return_url === 'string' ? session.return_url : undefined;
-  // the portal shows the public business name (stripe-shared.ts, publicBusinessName) of the session's on_behalf_of
+  // the portal shows the public business name (../engine/display.ts, publicBusinessName) of the session's on_behalf_of
   // account ("Use the Accounts API to modify the on_behalf_of account's branding settings, which the portal displays",
   // docs.stripe.com/api/customer_portal/sessions/object), else of the account it was made on (Stripe-Account), else the
   // platform's
@@ -143,8 +138,8 @@ function page(ctx: SemanticsContext, id: string, session: Row, problem?: { error
 }
 
 /** The customer's move on one of their subscriptions, then back to the portal. */
-async function move(ctx: SemanticsContext, id: string, session: Row, subscription: string, kind: 'cancel' | 'renew'): Promise<Response> {
-  const sub = ctx.get(SUB, subscription);
+async function move(ctx: HandlerContext, id: string, session: Row, subscription: string, kind: 'cancel' | 'renew'): Promise<Response> {
+  const sub = resourceView(ctx, SUB, subscription);
   if (!sub || sub.customer !== session.customer || sub.status === 'canceled') return gone();
   const back = new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
   if (kind === 'renew') {
@@ -153,7 +148,7 @@ async function move(ctx: SemanticsContext, id: string, session: Row, subscriptio
   }
   const features = featuresOf(ctx, session);
   if (!features.cancel.enabled) return gone();
-  const now = Number(ctx.now());
+  const now = nowUnix(ctx.occurredAt);
   const details = { comment: null, feedback: null, reason: 'cancellation_requested' };
   if (features.cancel.mode === 'at_period_end') {
     await ctx.write(SUB, subscription, { cancel_at_period_end: true, cancel_at: sub.current_period_end ?? null, canceled_at: now, cancellation_details: details }, 'subscription.update');
@@ -166,9 +161,9 @@ async function move(ctx: SemanticsContext, id: string, session: Row, subscriptio
 }
 
 /** The customer's new card: saved on them (no charge) as the default their invoices and subscriptions charge. */
-async function updatePaymentMethod(ctx: SemanticsContext, id: string, session: Row, v: Record<string, string>): Promise<Response> {
+async function updatePaymentMethod(ctx: HandlerContext, id: string, session: Row, v: Record<string, string>): Promise<Response> {
   if (!featuresOf(ctx, session).paymentMethod) return gone();
-  const refused = cardAnswer(v, Number(ctx.now()), false);
+  const refused = cardAnswer(v, nowUnix(ctx.occurredAt), false);
   if (refused) return page(ctx, id, session, { error: refused, values: v });
   const customer = String(session.customer);
   const [month, year] = (v.cardExpiry ?? '').split('/').map((x) => Number(x.trim()));
@@ -181,17 +176,17 @@ async function updatePaymentMethod(ctx: SemanticsContext, id: string, session: R
   });
   const holder = ctx.get('customer', customer) ?? {};
   await ctx.write('customer', customer, { invoice_settings: { ...((holder.invoice_settings as Row | undefined) ?? {}), default_payment_method: pm.id } }, 'customer.update');
-  for (const sub of ctx.rows(SUB).filter((s) => s.customer === customer && s.status !== 'canceled' && s.status !== 'incomplete_expired')) {
+  for (const sub of ctx.rows(SUB).map((s) => ctx.expand(SUB, s)).filter((s) => s.customer === customer && s.status !== 'canceled' && s.status !== 'incomplete_expired')) {
     await ctx.write(SUB, String(sub.id), { default_payment_method: pm.id }, 'subscription.update');
   }
   return new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
 }
 
 /** The customer pays one of their open invoices with the card on file. */
-async function payInvoice(ctx: SemanticsContext, id: string, session: Row, invoiceId: string): Promise<Response> {
+async function payInvoice(ctx: HandlerContext, id: string, session: Row, invoiceId: string): Promise<Response> {
   const inv = ctx.get('invoice', invoiceId);
   if (!inv || inv.customer !== session.customer || inv.status !== 'open') return gone();
-  const sub = typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
+  const sub = typeof inv.subscription === 'string' ? resourceView(ctx, SUB, inv.subscription) : undefined;
   const holder = ctx.get('customer', String(session.customer)) ?? {};
   const pm = (sub ? payerOf(ctx, sub) : undefined) ?? ((holder.invoice_settings as Row | undefined)?.default_payment_method as string | undefined);
   if (!pm) return page(ctx, id, session, { error: 'Add a payment method to pay this invoice.', values: {} });
@@ -201,20 +196,18 @@ async function payInvoice(ctx: SemanticsContext, id: string, session: Row, invoi
 }
 
 /** billing.stripe.com's portal pages, or undefined for any other request. */
-export function stripePortalFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
-  return async (request) => {
-    const m = /^\/p\/session\/(bps_[A-Za-z0-9_]+)(?:\/(cancel|renew|payment_method|pay))?\/?$/.exec(new URL(request.url).pathname);
-    if (!m) return undefined;
-    const [, id, kind] = m as unknown as [string, string, 'cancel' | 'renew' | 'payment_method' | 'pay' | undefined];
-    if ((kind && request.method !== 'POST') || (!kind && request.method !== 'GET')) return undefined;
-    // the form is read before the context, which reads the request's body itself
-    const form = kind ? await formOf(request.clone()) : {};
-    const ctx = await semanticsContext(manifest, request, PORTAL_OPERATION, scope);
-    const session = ctx.get('billing_portal.session', id);
-    if (!session) return gone();
-    if (!kind) return page(ctx, id, session);
-    if (kind === 'payment_method') return updatePaymentMethod(ctx, id, session, form);
-    if (kind === 'pay') return payInvoice(ctx, id, session, form.invoice ?? '');
-    return move(ctx, id, session, form.subscription ?? '', kind);
-  };
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
+  const m = /^\/p\/session\/(bps_[A-Za-z0-9_]+)(?:\/(cancel|renew|payment_method|pay))?\/?$/.exec(new URL(request.url).pathname);
+  if (!m) return notFound();
+  const [, id, kind] = m as unknown as [string, string, 'cancel' | 'renew' | 'payment_method' | 'pay' | undefined];
+  if ((kind && request.method !== 'POST') || (!kind && request.method !== 'GET')) return notFound();
+  // the form is read before the context, which reads the request's body itself
+  const form = kind ? await formOf(request.clone()) : {};
+  const session = ctx.get('billing_portal.session', id);
+  if (!session) return gone();
+  if (!kind) return page(ctx, id, session);
+  if (kind === 'payment_method') return updatePaymentMethod(ctx, id, session, form);
+  if (kind === 'pay') return payInvoice(ctx, id, session, form.invoice ?? '');
+  return move(ctx, id, session, form.subscription ?? '', kind);
 }

package/src/screens/checkout-js.ts

@@ -0,0 +1,80 @@
+import type { HandlerContext } from '@volter/world-core';
+import type { Row } from '../engine/common.ts';
+import { newCustomer } from '../engine/customers.ts';
+import { CS } from '../engine/checkout.ts';
+import { applyCouponDiscount, nowUnix, resolveTrial } from '../engine/stripe.ts';
+import { cardAnswer, parseExpiry } from './shared.tsx';
+import { completeSession, discountOf, created } from '../semantics/shared.ts';
+
+function amount(value: number, currency: string): Row {
+  return { amount: new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(value / 100), minorUnitsAmount: value };
+}
+
+// source: archive:https://registry.npmjs.org/@stripe/stripe-js/-/stripe-js-8.6.0.tgz#sha256=13e61419e9076ab440cc636e34d3ea5df3fc62bbf2d6a80d3fd718e8cd47f0a2!/package/dist/stripe-js/checkout.d.ts "export interface StripeCheckoutSession"
+// The SDK publishes its contract, not its private HTTP wire. This authored payment_pages wire uses the same session store and completion as hosted Checkout.
+function view(ctx: HandlerContext, session: Row): Row {
+  const currency = String(session.currency ?? 'usd');
+  const lines = ((session.line_items as Row)?.data ?? []) as Row[];
+  const stored = ctx.row(CS, String(session.id)) ?? session;
+  const trial = session.mode === 'subscription' ? resolveTrial((stored._subscription_data as Row) ?? {}, nowUnix(ctx.occurredAt)) : undefined;
+  const customer = typeof session.customer === 'string' ? ctx.get('customer', session.customer) : undefined;
+  const discount = stored._discount as Row | undefined;
+  const promotion = typeof discount?.promotion_code === 'string' ? ctx.get('promotion_code', discount.promotion_code) : undefined;
+  const zero = amount(0, currency);
+  return {
+    id: session.id, billingAddress: null, businessName: null, canConfirm: session.status === 'open', currency,
+    currencyOptions: null, discountAmounts: promotion ? [{ ...amount(Number((session.total_details as Row)?.amount_discount ?? 0), currency), promotionCode: promotion.code }] : [],
+    email: customer?.email ?? session.customer_email ?? null, lastPaymentError: null,
+    lineItems: lines.map(line => ({ id: line.id, name: line.description, quantity: line.quantity, unitAmount: amount(Number(line.amount_subtotal) / Number(line.quantity || 1), currency), total: amount(Number(line.amount_total), currency) })),
+    livemode: false, minorUnitsAmountDivisor: 100, phoneNumber: null,
+    recurring: session.mode === 'subscription' ? { trial: trial ? { trialEnd: trial.end, trialPeriodDays: Math.ceil((trial.end - trial.start) / 86400) } : null } : null,
+    savedPaymentMethods: [], shipping: null, shippingAddress: null, shippingOptions: [],
+    status: session.status === 'complete' ? { type: 'complete', paymentStatus: session.payment_status } : { type: session.status },
+    tax: { status: 'ready' }, taxAmounts: [], taxIdInfo: null,
+    total: { appliedBalance: zero, balanceAppliedToNextInvoice: false, discount: amount(Number((session.total_details as Row)?.amount_discount ?? 0), currency), shippingRate: zero, subtotal: amount(Number(session.amount_subtotal ?? 0), currency), taxExclusive: zero, taxInclusive: zero, total: amount(trial ? 0 : Number(session.amount_total ?? 0), currency) },
+  };
+}
+
+const failed = (message: string, code: string | null = null): Response => Response.json({ type: 'error', error: { message, code } });
+
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const path = new URL(ctx.call.request.url).pathname;
+  const id = path.split('/')[3]!;
+  const action = path.split('/')[4];
+  const params = ctx.params;
+  const session = ctx.get(CS, id);
+  // The private client secret is the browser's authority for this session; it never accepts a secret API key.
+  if (!session || session.ui_mode !== 'custom' || params.client_secret !== session.client_secret) return failed('Invalid Checkout Session client secret.');
+  if (action === 'init') return Response.json({ type: 'success', session: view(ctx, session) });
+  if (session.status !== 'open') return failed('This Checkout Session is no longer active.');
+  if (action === 'apply_promotion_code' || action === 'remove_promotion_code') {
+    if (action === 'apply_promotion_code' && session.allow_promotion_codes !== true) return failed('Promotion codes are not enabled for this Checkout Session.');
+    const promotion = action === 'apply_promotion_code' ? ctx.rows('promotion_code').find(p => p.code === params.promotion_code && p.active === true) : undefined;
+    if (action === 'apply_promotion_code' && !promotion) return failed('This promotion code is invalid.', 'invalidPromotionCode');
+    const discount = promotion ? discountOf(ctx, { discounts: [{ promotion_code: promotion.id }] }, nowUnix(ctx.occurredAt)) : undefined;
+    if (discount instanceof Response) return failed('This promotion code is invalid.', 'invalidPromotionCode');
+    const off = discount ? applyCouponDiscount(Number(session.amount_subtotal), discount.coupon) : 0;
+    const fields = { amount_total: Number(session.amount_subtotal) - off, total_details: { ...(session.total_details as Row), amount_discount: off }, discounts: discount ? [{ coupon: discount.coupon.id, promotion_code: promotion!.id }] : [], _discount: discount ? { coupon: discount.coupon.id, promotion_code: promotion!.id } : null };
+    const updated = await ctx.write(CS, id, fields, 'checkout.session.update');
+    return Response.json({ type: 'success', session: view(ctx, updated) });
+  }
+  if (action !== 'confirm') return failed('Unrecognized Checkout action.');
+  const values = (params.payment_details ?? {}) as Record<string, string>;
+  const stored = ctx.row(CS, id) ?? session;
+  const trial = session.mode === 'subscription' ? resolveTrial((stored._subscription_data as Row) ?? {}, nowUnix(ctx.occurredAt)) : undefined;
+  const refusal = cardAnswer(values, nowUnix(ctx.occurredAt), !trial);
+  if (refusal) return failed(refusal, 'paymentFailed');
+  const customer = typeof session.customer === 'string' ? ctx.get('customer', session.customer) : undefined;
+  const email = String(customer?.email ?? params.email ?? session.customer_email ?? '');
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) return failed('Your email address is incomplete.');
+  let existing = session;
+  if (!customer && session.mode === 'subscription') {
+    const cid = ctx.mint('customer');
+    const made = await created(ctx, 'customer', { id: cid, email }, { livemode: false, ...newCustomer(cid) });
+    existing = { ...session, customer: made.id };
+  }
+  const expiry = parseExpiry(values.cardExpiry)!;
+  const completed = await completeSession(ctx, id, existing, { customer: existing.customer, customer_details: { email, name: values.billingName ?? null, address: null, phone: null, tax_exempt: 'none', tax_ids: [] } }, { number: values.cardNumber.replace(/\D/g, ''), exp_month: expiry.month, exp_year: expiry.year });
+  if (completed instanceof Response) return failed('This Checkout Session is no longer active.');
+  return Response.json({ type: 'success', session: view(ctx, completed), return_url: session.return_url });
+}

package/src/screens/checkout.tsx

@@ -15,41 +15,17 @@
 // only sets the card up: setup mode, or a subscription's trial);
 // any other number that passes the Luhn check pays, and a card that asks for authentication pays without
 // the challenge. A subscription session with no customer makes one from the email, as Stripe does.
-import { semanticsContext, type SemanticsContext } from '@volter/world-core';
+import type { HandlerContext } from '@volter/world-core';
 import { flowPage, Payment, PAYMENT_CSS, type PaymentField } from '@volter/world-ui';
-import surface from '../generated/surface.gen.json' with { type: 'json' };
-import { manifest } from '../manifest.ts';
-import { completeSession, isOneTime } from '../semantics/checkout.ts';
-import { newCustomer } from '../semantics/customers.ts';
-import { created, type Row } from '../semantics/shared.ts';
-import { publicBusinessName } from '../stripe-shared.ts';
-import { applyCouponDiscount, PLATFORM_ACCOUNT_ID, resolveTrial } from '../stripe-twin.ts';
-import { formOf } from './consent-skin.ts';
-
+import { isOneTime } from '../engine/checkout.ts';
+import { newCustomer } from '../engine/customers.ts';
+import type { Row } from '../engine/common.ts';
+import { publicBusinessName } from '../engine/display.ts';
+import { applyCouponDiscount, nowUnix, PLATFORM_ACCOUNT_ID, resolveTrial } from '../engine/stripe.ts';
+import { cardAnswer, COUNTRIES, formOf, money, notFound, parseExpiry } from './shared.tsx';
+import { completeSession, created } from '../semantics/shared.ts';
 const CS = 'checkout.session';
-const COMPLETE_OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'PostCheckoutSessionsSession')!;
-
-const DECLINES: Record<string, string> = {
-  '4000000000000002': 'Your card was declined.',
-  '4000000000009995': 'Your card has insufficient funds.',
-  '4000000000000069': 'Your card has expired.',
-  '4000000000000127': "Your card's security code is incorrect.",
-};
-const luhn = (digits: string): boolean => {
-  let sum = 0;
-  for (let i = 0; i < digits.length; i++) {
-    let d = Number(digits[digits.length - 1 - i]);
-    if (i % 2 === 1) { d *= 2; if (d > 9) d -= 9; }
-    sum += d;
-  }
-  return digits.length >= 12 && sum % 10 === 0;
-};
-
-export const money = (minor: unknown, currency: unknown): string => {
-  const c = typeof currency === 'string' ? currency.toUpperCase() : 'USD';
-  const zeroDecimal = ['JPY', 'KRW', 'VND', 'CLP', 'ISK', 'UGX', 'XAF', 'XOF'].includes(c);
-  return new Intl.NumberFormat('en-US', { style: 'currency', currency: c }).format((Number(minor) || 0) / (zeroDecimal ? 1 : 100));
-};
+const COMPLETE_OPERATION = { id: 'PostCheckoutSessionsSession' };
 
 // Stripe's skin: its type, its blue submit, the summary on a tinted half.
 const SKIN = `
@@ -61,8 +37,6 @@ body { color: #1a1a1a; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI
 .pay-submit { background: #0074d4; color: #ffffff; }
 `;
 
-export const COUNTRIES = [['US', 'United States'], ['GB', 'United Kingdom'], ['CA', 'Canada'], ['DE', 'Germany'], ['FR', 'France'], ['AU', 'Australia'], ['JP', 'Japan']].map(([value, label]) => ({ value: value!, label: label! }));
-
 /** A subscription session's trial, when its subscription_data gives one: `trial_period_days`, or `trial_end`
  *  (docs.stripe.com/payments/checkout/free-trials), as resolveTrial makes the subscription's at completion. */
 function trialOf(session: Row, now: number): { start: number; end: number } | undefined {
@@ -103,7 +77,7 @@ function trialSummary(session: Row, trial: { start: number; end: number }): { le
 
 /** What each period after the trial charges, as the subscription's invoices will: its recurring line items (a one-time
  *  item is on the first invoice only, semantics/checkout.ts isOneTime), under the session's coupon unless the coupon is `once`, which the trial's own $0
- *  invoice takes (semantics/renewals.ts draftSubscriptionInvoice). */
+ *  invoice takes (../engine/renewals.ts draftSubscriptionInvoice). */
 function afterTrial(session: Row): number {
   const items = (((session.line_items as { data?: Row[] } | undefined)?.data) ?? []).filter((it, i) => !isOneTime(it, inlineOf(session, i)));
   const subtotal = items.reduce((sum, it) => sum + (Number(it.amount_subtotal) || 0), 0);
@@ -167,52 +141,17 @@ function page(session: Row, id: string, now: number, values: Record<string, stri
 const gone = (): Response =>
   flowPage({ title: 'Checkout', status: 404, css: [PAYMENT_CSS, SKIN], body: <main className="pay-form"><h1>This Checkout Session is no longer active.</h1></main> });
 
-/** Cards that are saved but decline when charged. */
-const DECLINES_WHEN_CHARGED: Record<string, string> = { '4000000000000341': 'Your card was declined.' };
-
-/** The expiry as the customer typed it. Stripe's field formats itself as it is typed: the digits `1230` read `12 / 30`,
- *  and a first digit above 1 is a month on its own (`5` reads `05 / `), so a person types the digits straight through
- *  (Checkout's own field, seen on checkout.stripe.com; docs.stripe.com/payments/checkout names no format to type). The
- *  page's script (@volter/world-ui Payment, `format: 'card-expiry'`) shows it formatted; this reads what is posted either
- *  way: `MM / YY`, `MM/YYYY`, or the bare digits `MMYY`, `MYY` (`530`) and `MMYYYY`; a month past 12 is read, and refused
- *  as invalid by cardAnswer. */
-export function parseExpiry(raw: string): { month: number; year: number } | undefined {
-  const split = /^\s*(\d{1,2})\s*\/\s*(\d{2}|\d{4})\s*$/.exec(raw);
-  const digits = raw.replace(/\s/g, '');
-  const bare = split ? undefined : /^(\d{2})(\d{2}|\d{4})$/.exec(digits) ?? /^([2-9])(\d{2})$/.exec(digits);
-  const m = split ?? bare;
-  if (!m) return undefined;
-  return { month: Number(m[1]), year: m[2]!.length === 2 ? 2000 + Number(m[2]) : Number(m[2]) };
-}
-
-/** The card's answer: undefined when it pays, else what Checkout says under the button. */
-export function cardAnswer(v: Record<string, string>, nowSeconds: number, chargesNow: boolean): string | undefined {
-  const digits = (v.cardNumber ?? '').replace(/\D/g, '');
-  if (!digits) return 'Your card number is incomplete.';
-  if (DECLINES[digits]) return DECLINES[digits];
-  if (chargesNow && DECLINES_WHEN_CHARGED[digits]) return DECLINES_WHEN_CHARGED[digits];
-  if (!luhn(digits)) return 'Your card number is invalid.';
-  const exp = parseExpiry(v.cardExpiry ?? '');
-  if (!exp) return "Your card's expiration date is incomplete.";
-  const { month, year } = exp;
-  if (month < 1 || month > 12) return "Your card's expiration date is invalid.";
-  const now = new Date(nowSeconds * 1000);
-  if (year < now.getUTCFullYear() || (year === now.getUTCFullYear() && month < now.getUTCMonth() + 1)) return "Your card's expiration year is in the past.";
-  if (!/^\d{3,4}$/.test(v.cardCvc ?? '')) return "Your card's security code is incomplete.";
-  return undefined;
-}
-
-async function pay(ctx: SemanticsContext, id: string, session: Row, v: Record<string, string>): Promise<Response> {
+async function pay(ctx: HandlerContext, id: string, session: Row, v: Record<string, string>): Promise<Response> {
   const onFile = customerEmailOf(session);
   const email = onFile ?? (typeof session.customer_email === 'string' ? session.customer_email : (v.email ?? '').trim());
   if (session.mode !== 'setup' || !session.customer) {
-    if (!EMAIL.test(email)) return page(session, id, Number(ctx.now()), v, 'Your email address is incomplete.');
+    if (!EMAIL.test(email)) return page(session, id, nowUnix(ctx.occurredAt), v, 'Your email address is incomplete.');
   }
   // a trial charges nothing now unless a one-time price is on the first invoice
   const oneTimeDue = (((session.line_items as { data?: Row[] } | undefined)?.data) ?? []).some((it, i) => isOneTime(it, inlineOf(session, i)));
-  const chargesNow = session.mode === 'payment' || (session.mode === 'subscription' && (!trialOf(session, Number(ctx.now())) || oneTimeDue));
-  const refused = cardAnswer(v, Number(ctx.now()), chargesNow);
-  if (refused) return page(session, id, Number(ctx.now()), v, refused);
+  const chargesNow = session.mode === 'payment' || (session.mode === 'subscription' && (!trialOf(session, nowUnix(ctx.occurredAt)) || oneTimeDue));
+  const refused = cardAnswer(v, nowUnix(ctx.occurredAt), chargesNow);
+  if (refused) return page(session, id, nowUnix(ctx.occurredAt), v, refused);
   let existing = session;
   // Checkout always makes a customer for a subscription; a payment makes one only when the session asks
   if (!session.customer && (session.mode === 'subscription' || session.customer_creation === 'always')) {
@@ -233,35 +172,32 @@ async function pay(ctx: SemanticsContext, id: string, session: Row, v: Record<st
   return new Response(null, { status: 303, headers: { location: to } });
 }
 
-/** checkout.stripe.com's pages, or undefined for any other request. */
 /** The name the page shows: the session's own `branding_settings.display_name` where the create set one, else the
- *  public business name (stripe-shared.ts, publicBusinessName) of the account whose brand Checkout uses: "Checkout uses
+ *  public business name (../engine/display.ts, publicBusinessName) of the account whose brand Checkout uses: "Checkout uses
  *  the brand settings of the connected account for destination charges with on_behalf_of and for platforms performing
  *  direct charges" (a session made with Stripe-Account), and otherwise the platform's; "If you omit a field in
  *  branding_settings, Checkout applies the default value from the Dashboard"
  *  (docs.stripe.com/payments/checkout/customization/appearance). */
-export function merchantOf(ctx: SemanticsContext, stored: Row): string {
+function merchantOf(ctx: HandlerContext, stored: Row): string {
   const brand = (stored._branding_settings as Row | undefined)?.display_name;
   const behalf = (stored._payment_intent_data as Row | undefined)?.on_behalf_of ?? (stored._subscription_data as Row | undefined)?.on_behalf_of;
   const account = typeof behalf === 'string' ? behalf : typeof stored._brand_account === 'string' ? stored._brand_account : PLATFORM_ACCOUNT_ID;
   return typeof brand === 'string' && brand.trim() ? brand : publicBusinessName(ctx.get('account', account));
 }
 
-export function stripeCheckoutFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
-  return async (request) => {
-    const m = /^\/c\/pay\/(cs_[A-Za-z0-9_]+)\/?$/.exec(new URL(request.url).pathname);
-    if (!m || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
-    const id = m[1]!;
-    // the form is read before the context, which reads the request's body itself
-    const values = request.method === 'POST' ? await formOf(request.clone()) : {};
-    const ctx = await semanticsContext(manifest, request, COMPLETE_OPERATION, scope);
-    const session = ctx.get(CS, id);
-    if (!session) return gone();
-    // an ended session's page is gone; paying on one is the customer's move the machine refuses
-    if (session.status !== 'open' && (request.method === 'GET' || ctx.legal(CS, 'status', COMPLETE_OPERATION.id, String(session.status), 'complete', id, 'external'))) return gone();
-    const stored = ctx.row(CS, id) ?? {};
-    const coupon = (stored._discount as Row | undefined)?.coupon;
-    const full = { ...session, _subscription_data: stored._subscription_data, _price_data: stored._price_data, _merchant: merchantOf(ctx, stored), _coupon: typeof coupon === 'string' ? ctx.get('coupon', coupon) : undefined, _customer: typeof session.customer === 'string' ? ctx.get('customer', session.customer) : undefined };
-    return request.method === 'GET' ? page(full, id, Number(ctx.now())) : pay(ctx, id, full, values);
-  };
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
+  const m = /^\/c\/pay\/(cs_[A-Za-z0-9_]+)\/?$/.exec(new URL(request.url).pathname);
+  if (!m || (request.method !== 'GET' && request.method !== 'POST')) return notFound();
+  const id = m[1]!;
+  // the form is read before the context, which reads the request's body itself
+  const values = request.method === 'POST' ? await formOf(request.clone()) : {};
+  const session = ctx.get(CS, id);
+  if (!session) return gone();
+  // an ended session's page is gone; paying on one is the customer's move the machine refuses
+  if (session.status !== 'open' && (request.method === 'GET' || ctx.legal(CS, 'status', COMPLETE_OPERATION.id, String(session.status), 'complete', id, 'external'))) return gone();
+  const stored = ctx.row(CS, id) ?? {};
+  const coupon = (stored._discount as Row | undefined)?.coupon;
+  const full = { ...session, _subscription_data: stored._subscription_data, _price_data: stored._price_data, _merchant: merchantOf(ctx, stored), _coupon: typeof coupon === 'string' ? ctx.get('coupon', coupon) : undefined, _customer: typeof session.customer === 'string' ? ctx.get('customer', session.customer) : undefined };
+  return request.method === 'GET' ? page(full, id, nowUnix(ctx.occurredAt)) : pay(ctx, id, full, values);
 }