@volter/twin-stripe 2.0.37 → 3.0.0

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

@@ -16,20 +16,16 @@
 // (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 { 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 +46,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 +58,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,7 +69,7 @@ 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');
@@ -106,7 +102,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,7 +139,7 @@ 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> {
+async function move(ctx: HandlerContext, id: string, session: Row, subscription: string, kind: 'cancel' | 'renew'): Promise<Response> {
   const sub = ctx.get(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}` } });
@@ -153,7 +149,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 +162,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()));
@@ -188,7 +184,7 @@ async function updatePaymentMethod(ctx: SemanticsContext, id: string, session: R
 }
 
 /** 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;
@@ -201,20 +197,19 @@ 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.tsx

@@ -15,41 +15,18 @@
 // 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 +38,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 +78,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 +142,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 +173,33 @@ 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);
 }
+