@volter/twin-stripe 2.0.38 → 3.0.1

package/src/screens/{onboarding.tsx → connect-onboarding.tsx}

@@ -23,25 +23,23 @@
 // merchant category codes as its list gives them (./industries.ts), and an industry the page does not offer leaves
 // business_profile.mcc due; the states are the fifty and the District of Columbia; a request with no forwarded address
 // records 127.0.0.1. An update link (account_update) shows the same page.
-import { semanticsContext, type SemanticsContext } from '@volter/world-core';
+import type { HandlerContext } from '@volter/world-core';
 import { CONSENT_CSS, 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 { created, syncExternals, type Row } from '../semantics/shared.ts';
-import { formOf, seeOther, STRIPE_CONSENT_SKIN } from './consent-skin.ts';
-import { INDUSTRIES as MCCS } from './industries.ts';
-
+import type { Row } from '../engine/common.ts';
+import { nowUnix } from '../engine/stripe.ts';
+import { formOf, notFound, seeOther, STRIPE_CONSENT_SKIN } from './shared.tsx';
+import { INDUSTRIES as MCCS } from '../engine/industries.ts';
+import { currentlyDue, type Form, type Kind, kindOf, OFFERED } from '../engine/onboarding.ts';
+import { created, syncExternals } from '../semantics/shared.ts';
 const LINK = 'account_link';
-const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'PostAccountsAccount')!;
 
 const gone = (): Response => flowPage({ title: 'Stripe', status: 404, css: [CONSENT_CSS, STRIPE_CONSENT_SKIN], body: <main className="consent"><h1 className="consent-heading">This link is invalid.</h1></main> });
 
 /** A link that can still be used: not used and not past its expiry. */
-const usable = (ctx: SemanticsContext, link: Row): boolean => link.used !== true && Number(link.expires_at) > Number(ctx.now());
+const usable = (ctx: HandlerContext, link: Row): boolean => link.used !== true && Number(link.expires_at) > nowUnix(ctx.occurredAt);
 
 // the field asks, with no industry chosen until the person chooses one (an unanswered field leaves the MCC due)
 const INDUSTRIES = [{ value: '', label: 'Select your industry' }, ...MCCS.map(([value, label]) => ({ value, label }))];
-const OFFERED = new Set(MCCS.map(([mcc]) => mcc));
 // the fifty states and the District of Columbia, by their USPS codes (the address's `state`, ISO 3166-2 without its
 // country, docs.stripe.com/api/accounts/object)
 const STATES = ([
@@ -55,49 +53,6 @@ const STATES = ([
   ['WA', 'Washington'], ['WV', 'West Virginia'], ['WI', 'Wisconsin'], ['WY', 'Wyoming'],
 ] as const).map(([value, label]) => ({ value, label }));
 
-type Form = Record<string, string>;
-type Kind = 'company' | 'individual';
-const has = (v: Form, k: string): boolean => (v[k] ?? '').trim() !== '';
-const dobPart = (v: Form, i: number): boolean => /^\d{4}-\d{2}-\d{2}$/.test(v.dob ?? '') && Number((v.dob ?? '').split('-')[i]) > 0;
-
-/** Each requirement Stripe names, the form's answer that meets it, and which of the two sets it belongs to. */
-const REQUIREMENTS: Array<[string, (v: Form) => boolean, Kind[]]> = [
-  ['business_profile.mcc', (v) => OFFERED.has((v.mcc ?? '').trim()), ['company', 'individual']],
-  ['business_profile.url', (v) => has(v, 'url'), ['company', 'individual']],
-  ['settings.payments.statement_descriptor', (v) => has(v, 'statement_descriptor'), ['company', 'individual']],
-  ['company.name', (v) => has(v, 'company_name'), ['company']],
-  ['company.tax_id', (v) => has(v, 'company_tax_id'), ['company']],
-  ['company.phone', (v) => has(v, 'company_phone'), ['company']],
-  ['company.address.line1', (v) => has(v, 'company_line1'), ['company']],
-  ['company.address.city', (v) => has(v, 'company_city'), ['company']],
-  ['company.address.state', (v) => has(v, 'company_state'), ['company']],
-  ['company.address.postal_code', (v) => has(v, 'company_postal_code'), ['company']],
-  ['company.owners_provided', (v) => v.owners_provided === 'provided', ['company']],
-  ['owners.first_name', (v) => has(v, 'owner_first_name'), ['company']],
-  ['owners.last_name', (v) => has(v, 'owner_last_name'), ['company']],
-  ['owners.email', (v) => has(v, 'owner_email'), ['company']],
-  ...(['first_name', 'last_name', 'email', 'phone'] as const).flatMap((f): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.${f}`, (v) => has(v, f), ['company']], [`individual.${f}`, (v) => has(v, f), ['individual']]]),
-  ...(['day', 'month', 'year'] as const).flatMap((f, i): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.dob.${f}`, (v) => dobPart(v, 2 - i), ['company']], [`individual.dob.${f}`, (v) => dobPart(v, 2 - i), ['individual']]]),
-  ...(['line1', 'city', 'state', 'postal_code'] as const).flatMap((f): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.address.${f}`, (v) => has(v, f), ['company']], [`individual.address.${f}`, (v) => has(v, f), ['individual']]]),
-  ['representative.relationship.title', (v) => has(v, 'title'), ['company']],
-  ['representative.ssn_last_4', (v) => /^\d{4}$/.test(v.ssn_last_4 ?? ''), ['company']],
-  ['individual.ssn_last_4', (v) => /^\d{4}$/.test(v.ssn_last_4 ?? ''), ['individual']],
-  ['tos_acceptance.date', (v) => v.tos === 'accepted', ['company', 'individual']],
-  ['tos_acceptance.ip', (v) => v.tos === 'accepted', ['company', 'individual']],
-  ['external_account', (v) => has(v, 'routing_number') && has(v, 'account_number'), ['company', 'individual']],
-];
-
-/** The set an account onboards against: the two US sets the twin models, or none. */
-export function kindOf(account: Row): Kind | undefined {
-  const type = account.business_type ?? 'individual';
-  return (account.country ?? 'US') === 'US' && (type === 'company' || type === 'individual') ? type : undefined;
-}
-
-/** What an account of this kind still owes, given the form's answers (none: all of it). */
-export function currentlyDue(kind: Kind, v: Form = {}): string[] {
-  return REQUIREMENTS.filter(([, met, kinds]) => kinds.includes(kind) && !met(v)).map(([req]) => req);
-}
-
 const field = (id: string, label: string, v: Form, extra: Partial<PaymentField> = {}): PaymentField => ({ id, label, value: v[id] ?? '', ...extra });
 const addressFields = (prefix: string, v: Form): PaymentField[] => [
   field(`${prefix}line1`, 'Address', v, { autoComplete: 'address-line1' }), field(`${prefix}city`, 'City', v),
@@ -107,7 +62,7 @@ const addressFields = (prefix: string, v: Form): PaymentField[] => [
 /** The industry the field shows: what the form sent, else what the account already holds, when the page offers it. */
 const industryOf = (mcc: unknown): string => (typeof mcc === 'string' && OFFERED.has(mcc.trim()) ? mcc.trim() : '');
 
-function page(ctx: SemanticsContext, sessionUrl: string, link: Row, kind: Kind, values: Form = {}, error?: string): Response {
+function page(ctx: HandlerContext, sessionUrl: string, link: Row, kind: Kind, values: Form = {}, error?: string): Response {
   const v = values;
   const business: PaymentField[] = [
     field('mcc', 'Industry', v, { options: INDUSTRIES, value: industryOf(v.mcc ?? (ctx.get('account', String(link.account))?.business_profile as Row | undefined)?.mcc) }),
@@ -157,19 +112,19 @@ function unmodelled(account: Row): Response {
 }
 
 /** A submit that leaves something out is refused on the page with what is missing, the owner's answers kept. */
-function incomplete(ctx: SemanticsContext, sessionUrl: string, link: Row, kind: Kind, v: Form, missing: string[]): Response {
+function incomplete(ctx: HandlerContext, sessionUrl: string, link: Row, kind: Kind, v: Form, missing: string[]): Response {
   return page(ctx, sessionUrl, link, kind, v, `Still required: ${missing.join(', ')}.`);
 }
 
 /** The owner submits everything: it is stored on the account, nothing is due, and charges, payouts and the requested
  *  capabilities are enabled. */
-async function submit(ctx: SemanticsContext, link: Row, kind: Kind, v: Form, ip: string): Promise<void> {
+async function submit(ctx: HandlerContext, link: Row, kind: Kind, v: Form, ip: string): Promise<void> {
   const id = String(link.account);
   const account = ctx.get('account', id);
   if (!account) return;
   const caps: Row = { ...((account.capabilities as Row | undefined) ?? {}) };
   for (const [cap, status] of Object.entries(caps)) {
-    if (status !== 'active' && !ctx.legal('capability', 'status', OPERATION.id, String(status), 'active', cap, 'vendor')) caps[cap] = 'active';
+    if (status !== 'active') caps[cap] = 'active';
   }
   const due = currentlyDue(kind, v);
   const requirements = { ...((account.requirements as Row | undefined) ?? {}), currently_due: due, eventually_due: due, past_due: [], disabled_reason: null, current_deadline: null };
@@ -178,6 +133,7 @@ async function submit(ctx: SemanticsContext, link: Row, kind: Kind, v: Form, ip:
   const person = { first_name: v.first_name, last_name: v.last_name, email: v.email, phone: v.phone, dob: { day, month, year }, address: addressOf(''), ssn_last_4_provided: true, id_number_provided: false };
   const company = kind === 'company';
   const settings = (account.settings as Row | undefined) ?? {};
+  const individual = company ? null : await created(ctx, 'person', { ...person, account: id }, { relationship: { representative: true }, metadata: {} });
   await ctx.write('account', id, {
     details_submitted: true, charges_enabled: due.length === 0, payouts_enabled: due.length === 0, capabilities: caps, requirements,
     business_type: kind,
@@ -185,8 +141,8 @@ async function submit(ctx: SemanticsContext, link: Row, kind: Kind, v: Form, ip:
     settings: { ...settings, payments: { ...((settings.payments as Row | undefined) ?? {}), statement_descriptor: v.statement_descriptor } },
     ...(company
       ? { company: { name: v.company_name, phone: v.company_phone, address: addressOf('company_'), tax_id_provided: true, owners_provided: true, directors_provided: false, executives_provided: false } }
-      : { individual: { ...person, id: `person_${id}` } }),
-    tos_acceptance: { date: Number(ctx.now()), ip, user_agent: null },
+      : { individual: individual!.id }),
+    tos_acceptance: { date: nowUnix(ctx.occurredAt), ip, user_agent: null },
   }, 'account.updated');
   if (company) {
     await created(ctx, 'person', { account: id }, { ...person, relationship: { representative: true, executive: true, director: false, owner: false, percent_ownership: null, title: v.title }, metadata: {} });
@@ -205,7 +161,7 @@ const SESSIONS = 'https://connect.stripe.com/setup/s/';
 
 /** Visiting an Account Link consumes it and sends the owner to their onboarding session; a used or expired one sends
  *  them to refresh_url for a fresh link. */
-async function visit(ctx: SemanticsContext, id: string): Promise<Response> {
+async function visit(ctx: HandlerContext, id: string): Promise<Response> {
   const link = ctx.get(LINK, id);
   if (!link) return gone();
   if (!usable(ctx, link)) return seeOther(String(link.refresh_url));
@@ -215,29 +171,27 @@ async function visit(ctx: SemanticsContext, id: string): Promise<Response> {
 }
 
 /** connect.stripe.com's onboarding pages, or undefined for any other request. */
-export function stripeOnboardingFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
-  return async (request) => {
-    const path = new URL(request.url).pathname;
-    const entry = /^\/setup\/(acctlink_[A-Za-z0-9_]+)\/?$/.exec(path);
-    const at = /^\/setup\/s\/(onbs_[A-Za-z0-9_]+)\/?$/.exec(path);
-    if (entry && request.method === 'GET') return visit(await semanticsContext(manifest, request, OPERATION, scope), entry[1]!);
-    if (!at || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
-    const sid = at[1]!;
-    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
-    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
-    // the session the visited link opened, until it is submitted
-    const stored = ctx.rowsRaw(LINK).find((l) => l._session === sid && l._submitted !== true);
-    const link = stored ? ctx.get(LINK, String(stored.id)) : undefined;
-    if (!stored || !link) return gone();
-    const sessionUrl = `${SESSIONS}${sid}`;
-    const account = ctx.get('account', String(link.account)) ?? {};
-    const kind = kindOf(account);
-    if (!kind) return unmodelled(account);
-    if (request.method === 'GET') return page(ctx, sessionUrl, link, kind);
-    const missing = currentlyDue(kind, form);
-    if (missing.length) return incomplete(ctx, sessionUrl, link, kind, form, missing);
-    await ctx.write(LINK, String(stored.id), { _submitted: true }, 'account_link.submitted');
-    await submit(ctx, link, kind, form, request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || '127.0.0.1');
-    return seeOther(String(link.return_url));
-  };
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
+  const path = new URL(request.url).pathname;
+  const entry = /^\/setup\/(acctlink_[A-Za-z0-9_]+)\/?$/.exec(path);
+  const at = /^\/setup\/s\/(onbs_[A-Za-z0-9_]+)\/?$/.exec(path);
+  if (entry && request.method === 'GET') return visit(ctx, entry[1]!);
+  if (!at || (request.method !== 'GET' && request.method !== 'POST')) return notFound();
+  const sid = at[1]!;
+  const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+  // the session the visited link opened, until it is submitted
+  const stored = ctx.rowsRaw(LINK).find((l) => l._session === sid && l._submitted !== true);
+  const link = stored ? ctx.get(LINK, String(stored.id)) : undefined;
+  if (!stored || !link) return gone();
+  const sessionUrl = `${SESSIONS}${sid}`;
+  const account = ctx.get('account', String(link.account)) ?? {};
+  const kind = kindOf(account);
+  if (!kind) return unmodelled(account);
+  if (request.method === 'GET') return page(ctx, sessionUrl, link, kind);
+  const missing = currentlyDue(kind, form);
+  if (missing.length) return incomplete(ctx, sessionUrl, link, kind, form, missing);
+  await ctx.write(LINK, String(stored.id), { _submitted: true }, 'account_link.submitted');
+  await submit(ctx, link, kind, form, request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || '127.0.0.1');
+  return seeOther(String(link.return_url));
 }

package/src/screens/dashboard.tsx

@@ -0,0 +1,178 @@
+// THE DASHBOARD — dashboard.stripe.com's pages an operator sets what Stripe's API cannot (docs/contributing/architecture.md,
+// "Screens": a workspace): Public details (/settings/public) and the Connect OAuth settings
+// (/settings/connect/onboarding-options/oauth), Radar lists and test Issuing funding.
+// The operator controls prepare the cited real application calls; other Dashboard pages answer Stripe's 404.
+//
+// THE DASHBOARD'S PUBLIC DETAILS — a workspace page (docs/contributing/architecture.md, "Screens") of the Dashboard
+// (manifest screen `dashboard`), at dashboard.stripe.com/settings/public: Settings → Business → Public details, where
+// the operator sets what their customers see ("Public Details → Business Settings",
+// support.stripe.com/questions/update-account-name-shown-in-the-dashboard). Its business name is the account's
+// `business_profile.name`, "The customer-facing business name" (docs.stripe.com/api/accounts/object), and it is the
+// name Checkout shows: "You can change a Checkout page's name by modifying the Business name field"
+// (docs.stripe.com/payments/checkout/customization/appearance). Stripe's API has no call that changes the platform's
+// own account (POST /v1/accounts/{account} updates a connected one), so this page is the only way to the act, and
+// saving it writes the platform account's stored record (../engine/connect.ts), which GET /v1/account,
+// Checkout and the customer portal then read. The Dashboard's account name (`settings.dashboard.display_name`,
+// Settings → Account) is a separate, internal setting, "for internal use only" (the same support article), and this
+// page does not touch it. Authored from plain markup under Stripe's type; nothing of Stripe's page is copied.
+//
+// Where the documentation stops and the twin decides: the page holds the business name only (the real page's
+// support details, website and statement descriptor are not modelled here); the name is required and at most 5000
+// characters (the spec's bound on business_profile.name), which the browser holds the field to and the page checks
+// again for a client that is not a browser; no sign-in guards the page. The form posts to the page's own address
+// and the save redirects to its own path. Saving is an update of an account that exists (the first save included, though
+// the twin stores the platform's record only then), so every save is sent as account.updated.
+//
+// THE DASHBOARD'S CONNECT OAUTH SETTINGS — a workspace page (docs/contributing/architecture.md, "Screens") of the
+// Dashboard (manifest screen `dashboard`), at dashboard.stripe.com/settings/connect/onboarding-options/oauth, where a
+// platform starts an OAuth integration: "Enable onboarding accounts with OAuth", "Copy your client_id, a unique
+// identifier for your platform that's generated by Stripe", and "Set your redirect_uri ... You must specify all redirect
+// URLs in your platform settings. If you don't include the redirect_uri parameter in your request, Stripe defaults to
+// using the first address you've configured" (docs.stripe.com/connect/oauth-standard-accounts). The test client_id
+// "allows you to: Set your redirect_uri to a non-HTTPS URL; Set your redirect_uri to localhost"
+// (docs.stripe.com/connect/testing#using-oauth). Stripe's API has no call that reads or changes these settings (GET
+// /v1/account does not carry the client_id), so this page is the only way to them, and connect.stripe.com/oauth/authorize
+// (./connect-oauth.tsx) reads what it saves. Authored from plain markup under Stripe's type; nothing of Stripe's page is
+// copied.
+//
+// Where the documentation stops and the twin decides: the World has one platform, and its test client_id is
+// `ca_twin_self` (PLATFORM_CLIENT_ID; the platform account is acct_twin_self), the same in every World, shown on the
+// page in an element a runner reads (data-testid="connect-client-id"). OAuth starts disabled. The page is served at
+// the docs' address, at /test/… (the docs' test-mode link) and at /settings/connect (the address Cal.com's setup
+// guide gives). The redirect URIs are one form field, one per line (or comma-separated, as the reference describes
+// them), saved whole: each an absolute http or https URL without a fragment; http and localhost are allowed, as the
+// test client_id allows them. No sign-in guards the page. The form posts to the
+// page's own address and the save redirects to it.
+import type { HandlerContext } from '@volter/world-core';
+import { flowPage } from '@volter/world-ui';
+import { VL } from '../engine/radar.ts';
+import { nowUnix } from '../engine/stripe.ts';
+import type { Row } from '../engine/common.ts';
+import { platformAccountDefault } from '../engine/connect.ts';
+import { publicBusinessName } from '../engine/display.ts';
+import { PLATFORM_ACCOUNT_ID } from '../engine/stripe.ts';
+import { formOf, notFound } from './shared.tsx';
+import { created } from '../semantics/shared.ts';
+const redirect = (path: string): Response => new Response(null, { status: 303, headers: { location: path } });
+const invalid = (message: string): Response => flowPage({ css: [], title: 'Stripe', status: 400, body: <main><p role="alert">{message}</p></main> });
+
+const PUBLIC_DETAILS_PATH = '/settings/public';
+const MAX_NAME = 5000;
+
+const DETAILS_CSS = `
+* { box-sizing: border-box; }
+body { margin: 0; background: #f6f8fa; color: #1a1f36; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; font-size: 14px; }
+.pd { max-width: 640px; margin: 48px auto; padding: 0 16px; }
+.pd h1 { font-size: 28px; margin: 16px 0 4px; }
+.pd-lead { color: #697386; margin: 0 0 24px; }
+.pd-card { background: #ffffff; border: 1px solid #e3e8ee; border-radius: 8px; padding: 24px; }
+.pd-card label { display: block; font-weight: 600; margin-bottom: 6px; }
+.pd-card small { display: block; color: #697386; margin-bottom: 8px; }
+.pd-card input { width: 100%; padding: 8px 10px; border: 1px solid #c1c9d2; border-radius: 6px; font: inherit; }
+.pd-actions { margin-top: 20px; display: flex; justify-content: flex-end; }
+.pd-actions button { background: #635bff; color: #ffffff; border: 0; border-radius: 6px; padding: 8px 16px; font: inherit; font-weight: 600; cursor: pointer; }
+.pd-notice { padding: 10px 12px; border-radius: 6px; margin-bottom: 16px; }
+.pd-error { background: #fff0f3; color: #df1b41; }
+.pd-saved { background: #e7f8ef; color: #0e6245; }
+`;
+
+function detailsPage(account: Row | undefined, opts: { value?: string; error?: string; saved?: boolean } = {}): Response {
+  const named = (account?.business_profile as Row | undefined)?.name;
+  const value = opts.value ?? (typeof named === 'string' ? named : '');
+  return flowPage({
+    title: 'Public details – Stripe',
+    css: [DETAILS_CSS],
+    ...(opts.error ? { status: 400 } : {}),
+    body: (
+      <main className="pd">
+        <h1>Public details</h1>
+        <p className="pd-lead">What your customers see on Checkout, the customer portal, receipts and invoices. Currently shown: <strong data-testid="public-business-name">{publicBusinessName(account)}</strong></p>
+        {opts.error ? <p className="pd-notice pd-error" role="alert">{opts.error}</p> : null}
+        {opts.saved ? <p className="pd-notice pd-saved" role="status">Your public details were saved.</p> : null}
+        <form className="pd-card" method="post">
+          <label htmlFor="business_name">Business name</label>
+          <small>The name customers see when they pay you.</small>
+          <input id="business_name" name="business_name" autoComplete="organization" defaultValue={value} required maxLength={MAX_NAME} />
+          <div className="pd-actions"><button type="submit">Save</button></div>
+        </form>
+      </main>
+    ),
+  });
+}
+
+/** Save the business name on the platform's own account: the stored record, made from Stripe's default the first
+ *  time anything is saved, and otherwise changed in place (its other public details kept). */
+async function save(ctx: HandlerContext, name: string): Promise<void> {
+  const held = ctx.get('account', PLATFORM_ACCOUNT_ID);
+  const profile = { business_profile: { ...(((held ?? platformAccountDefault()).business_profile as Row | undefined) ?? {}), name } };
+  await (held ? ctx.write('account', PLATFORM_ACCOUNT_ID, profile, 'account.update') : created(ctx, 'account', { ...platformAccountDefault(), ...profile }, {}, { operation: 'account.update' }));
+}
+
+/** What the page says of a name no browser sends (the field is required and bounded), for a client that sends it. */
+function nameRefused(name: string): string | undefined {
+  return !name ? 'Enter your business name.' : name.length > MAX_NAME ? `Your business name must be at most ${MAX_NAME} characters.` : undefined;
+}
+
+async function publicDetails(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
+  const url = new URL(request.url);
+  if (request.method !== 'GET' && request.method !== 'POST') return notFound();
+  const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+  if (request.method === 'GET') return detailsPage(ctx.get('account', PLATFORM_ACCOUNT_ID), { saved: url.searchParams.has('saved') });
+  const name = (form.business_name ?? '').trim();
+  const refused = nameRefused(name);
+  if (refused) return detailsPage(ctx.get('account', PLATFORM_ACCOUNT_ID), { value: form.business_name ?? '', error: refused });
+  await save(ctx, name);
+  // a query-only reference: the page's own path, wherever it is mounted and with or without its trailing slash
+  return new Response(null, { status: 303, headers: { location: '?saved=1' } });
+}
+
+/** Dashboard settings, Radar list creation and test Issuing funding; other pages answer Stripe's 404. */
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const path = new URL(ctx.call.request.url).pathname.replace(/\/+$/, '');
+  // source: https://docs.stripe.com/radar/lists "Use the Dashboard or the API to create lists."
+  // source: https://docs.stripe.com/radar/lists "Enter a name for the list"
+  // source: https://docs.stripe.com/radar/lists "Select the type of list to create."
+  // source: https://docs.stripe.com/radar/lists "Click Add to save your new list."
+  // Where the documentation stops: it names Dashboard controls, not their browser request routes or form wire.
+  // This authored page uses /radar/lists for GET and POST, /radar/lists/{id} for its redirect/detail address,
+  // and a 303 redirect after saving. The HTML field names name, alias and item_type are the twin's choices;
+  // item_type values are the pinned API's enums, not published Dashboard form values. The alias fallback's
+  // lowercase/underscore algorithm is also authored; Stripe says it generates an alias but gives no algorithm.
+  if (/^\/radar\/lists(?:\/[^/]+)?$/.test(path)) {
+    if (ctx.call.request.method === 'POST') {
+      const form = await formOf(ctx.call.request);
+      const types = ['string', 'case_sensitive_string', 'card_fingerprint', 'card_bin', 'customer_id', 'email', 'ip_address', 'country', 'sepa_debit_fingerprint', 'us_bank_account_fingerprint'];
+      if (!form.name?.trim() || !types.includes(form.item_type ?? '')) return invalid('Enter a name and select a list type.');
+      const alias = form.alias?.trim() || form.name.toLowerCase().replace(/[^a-z0-9]+/g, '_');
+      // Where the page stops: an operator has no login identity in the World; created_by is its synthetic operator.
+      const list = await created(ctx, VL, { name: form.name.trim(), alias, item_type: form.item_type }, {
+        created_by: 'twin', livemode: false, metadata: {},
+        list_items: { object: 'list', data: [], has_more: false, url: '/v1/radar/value_list_items' },
+      });
+      await ctx.write(VL, String(list.id), { list_items: { object: 'list', data: [], has_more: false, url: `/v1/radar/value_list_items?value_list=${list.id}` } }, 'radar.value_list.updated');
+      return redirect(`/radar/lists/${list.id}`);
+    }
+    return flowPage({ css: [], title: 'Lists – Radar – Stripe', body: <main><h1>Radar Lists</h1><form method="post" action="/radar/lists"><h2>New list</h2><label>Name<input name="name" required /></label><label>Alias<input name="alias" /></label><label>List type<select name="item_type"><option value="customer_id">Customer ID</option><option value="email">Email</option><option value="card_fingerprint">Card fingerprint</option><option value="ip_address">IP address</option><option value="string">String</option></select></label><button>Add</button></form><ul>{ctx.rows(VL).map(row => <li key={String(row.id)}>{String(row.name)} ({String(row.alias)})</li>)}</ul></main> });
+  }
+  // source: https://docs.stripe.com/issuing/testing "Before you create test transactions, you must add test funds to the Issuing balance on your account."
+  // source: https://docs.stripe.com/issuing/testing "You can create test top-ups in the Dashboard, or with the Top-ups API"
+  // Where the documentation stops: it states the Dashboard funding act, not a browser request path or form wire.
+  // The authored GET/POST address and 303 redirect are /test/issuing/balance. The form name amount, its positive
+  // integer validation and its units (USD cents for this US sandbox) are the twin's choices, not published form
+  // fields. Its POST records the balance change in the vendor ledger, with source=null (permitted by the pinned
+  // schema) and immediate availability for this sandbox control; the page states neither that source nor timing.
+  // No private Topup object is seeded or answered, and the uncalled Top-ups API remains the gap.
+  if (path === '/test/issuing/balance') {
+    if (ctx.call.request.method === 'POST') {
+      const form = await formOf(ctx.call.request);
+      const amount = Number(form.amount);
+      if (!Number.isInteger(amount) || amount <= 0) return invalid('Enter a positive amount in cents.');
+      await created(ctx, 'balance_transaction', {}, { amount, currency: 'usd', fee: 0, net: amount, type: 'topup', reporting_category: 'topup', source: null, status: 'available', balance_type: 'issuing', available_on: Number(nowUnix(ctx.occurredAt)), fee_details: [] });
+      return redirect('/test/issuing/balance');
+    }
+    return flowPage({ css: [], title: 'Test Issuing balance – Stripe', body: <main><h1>Test Issuing balance</h1><form method="post"><label>Amount<input name="amount" type="number" min="1" required /></label><button>Add test funds</button></form></main> });
+  }
+  return path === PUBLIC_DETAILS_PATH ? publicDetails(ctx) : notFound();
+}
+

package/src/screens/shared.tsx

@@ -0,0 +1,84 @@
+// What Stripe's screens share (docs/contributing/architecture.md, "Pack layout": screens/shared.tsx): the skin over
+// @volter/world-ui's consent piece for the flows where a person agrees to something (connected-account onboarding,
+// identity verification, linking a bank), a page's form, and the card a customer types on Checkout and the portal.
+export const STRIPE_CONSENT_SKIN = `
+body { background: #f6f9fc; color: #1a1f36; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; }
+.consent-badge { background: #ffffff; border: 1px solid #e3e8ee; color: #1a1f36; }
+.consent-vendor { background: #635bff; border-color: #635bff; }
+.consent-link { border-color: #c1c9d2; }
+.consent-box { background: #ffffff; border-color: #e3e8ee; }
+.consent-who small, .consent-permission summary small, .consent-note { color: #697386; }
+.consent-actions { border-color: #e3e8ee; }
+.consent-deny { background: #ffffff; border-color: #c1c9d2; color: #1a1f36; }
+.consent-allow { background: #635bff; border-color: #635bff; color: #ffffff; }
+`;
+
+/** The form fields a page's POST carries, as a browser posts them. */
+export async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+export const seeOther = (location: string): Response => new Response(null, { status: 302, headers: { location } });
+
+export 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.",
+};
+
+export 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));
+};
+
+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! }));
+
+/** Cards that are saved but decline when charged. */
+export 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;
+}
+
+/** Stripe's answer for a page of one of its hosts the twin does not serve. */
+export const notFound = (): Response => new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain; charset=utf-8' } });

package/src/screens/stripe-js.ts

@@ -0,0 +1,102 @@
+// Stripe.js 7.3.1 is Dub’s pinned browser SDK (apps/web/package.json:49 and pnpm-lock.yaml).
+// Its loader requests a release-train script, reads window.Stripe and registers its wrapper.
+// The shipped upgrade button calls redirectToCheckout({ sessionId }); hosted-checkout.d.ts declares that
+// navigation and its promise that settles only on failure. Other SDK flows have no demanded caller.
+import type { HandlerContext } from '@volter/world-core';
+import { notFound } from './shared.tsx';
+
+/** The release train a script path names: `/v3`, `/v3/` or `/v3/stripe.js` → 3, `/<train>/stripe.js` → the train. */
+function stripeJsTrain(pathname: string): 3 | string | undefined {
+  return /^\/v3(\/|\/stripe\.js)?$/.test(pathname) ? 3 : /^\/([a-z]+)\/stripe\.js$/.exec(pathname)?.[1];
+}
+
+// source: archive:https://registry.npmjs.org/@stripe/stripe-js/-/stripe-js-8.6.0.tgz#sha256=13e61419e9076ab440cc636e34d3ea5df3fc62bbf2d6a80d3fd718e8cd47f0a2!/package/dist/stripe-js/checkout.d.ts "loadActions: () => Promise<StripeCheckoutLoadActionsResult>"
+function script(version: 3 | string): string {
+  return `(function () {
+  var version = ${JSON.stringify(version)};
+  function gap(name) {
+    return function () { throw new Error("Stripe.js (Volter twin): stripe." + name + " is not modelled by this twin yet"); };
+  }
+  function initCheckout(options) {
+    var session, root, fields = {}, listeners = {};
+    function emit(name, value) { (listeners[name] || []).forEach(function (fn) { fn(value); }); }
+    function call(action, values) {
+      var secret = options.clientSecret;
+      var id = secret.split("_secret_")[0];
+      return fetch("https://api.stripe.com/v1/payment_pages/" + encodeURIComponent(id) + "/" + action, {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify(Object.assign({ client_secret: secret }, values || {}))
+      }).then(function (r) { return r.json(); }).then(function (result) {
+        if (result.type === "success") { session = result.session; emit("change", session); }
+        return result;
+      });
+    }
+    var actions = {
+      getSession: function () { return session; },
+      applyPromotionCode: function (code) { return call("apply_promotion_code", { promotion_code: code }); },
+      removePromotionCode: function () { return call("remove_promotion_code"); },
+      confirm: function (params) {
+        return call("confirm", Object.assign({}, params || {}, { payment_details: fields })).then(function (result) {
+          if (result.type === "success" && (!params || params.redirect !== "if_required") && result.return_url) window.location.assign((params && params.returnUrl) || result.return_url);
+          return result;
+        });
+      }
+    };
+    var elementListeners = {};
+    function elementEmit(name, value) { (elementListeners[name] || []).forEach(function (fn) { fn(value); }); }
+    var element = {
+      on: function (name, fn) { (elementListeners[name] || (elementListeners[name] = [])).push(fn); return element; },
+      off: function (name, fn) { elementListeners[name] = (elementListeners[name] || []).filter(function (f) { return f !== fn; }); return element; },
+      mount: function (target) {
+        root = typeof target === "string" ? document.querySelector(target) : target;
+        [["cardNumber", "Card number", "cc-number"], ["cardExpiry", "Expiration", "cc-exp"], ["cardCvc", "CVC", "cc-csc"], ["billingName", "Cardholder name", "cc-name"]].forEach(function (field) {
+          var label = document.createElement("label"), input = document.createElement("input");
+          label.textContent = field[1]; input.name = field[0]; input.autocomplete = field[2];
+          input.addEventListener("input", function () { fields[field[0]] = input.value; elementEmit("change", { empty: !fields.cardNumber, complete: !!(fields.cardNumber && fields.cardExpiry && fields.cardCvc), value: { type: "card" } }); });
+          label.appendChild(input); root.appendChild(label);
+        });
+        Promise.resolve().then(function () { elementEmit("ready", element); });
+      },
+      unmount: function () { if (root) root.replaceChildren(); root = null; },
+      destroy: function () { element.unmount(); elementListeners = {}; },
+      update: function () {}
+    };
+    return {
+      on: function (name, fn) { (listeners[name] || (listeners[name] = [])).push(fn); },
+      loadActions: function () { return call("init").then(function (r) { return r.type === "success" ? { type: "success", actions: actions } : r; }); },
+      createPaymentElement: function () { return element; }, getPaymentElement: function () { return element; },
+      changeAppearance: function () {}, loadFonts: function () {}
+    };
+  }
+  function Stripe(publishableKey) {
+    if (typeof publishableKey !== "string" || !publishableKey) throw new Error("Stripe.js (Volter twin): Stripe() needs a publishable key");
+    var known = {
+      initCheckout: initCheckout,
+      _registerWrapper: function () {},
+      redirectToCheckout: function (options) {
+        if (!options || typeof options.sessionId !== "string" || !options.sessionId) return gap("redirectToCheckout without a sessionId")();
+        window.location.assign("https://checkout.stripe.com/c/pay/" + encodeURIComponent(options.sessionId));
+        return new Promise(function () {});
+      }
+    };
+    return new Proxy(known, {
+      get: function (target, name) {
+        if (name in target) return target[name];
+        if (typeof name === "symbol" || name === "then") return undefined;
+        return gap(String(name));
+      }
+    });
+  }
+  Stripe.version = version;
+  window.Stripe = Stripe;
+})();
+`;
+}
+
+/** js.stripe.com's script for a GET of its path; Stripe's 404 for anything else there. */
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
+  const train = request.method === 'GET' || request.method === 'HEAD' ? stripeJsTrain(new URL(request.url).pathname) : undefined;
+  if (train === undefined) return notFound();
+  return new Response(script(train), { headers: { 'content-type': 'application/javascript; charset=utf-8', 'access-control-allow-origin': '*' } });
+}

package/src/semantics/account.ts

@@ -0,0 +1,10 @@
+import type { HandlerContext } from '@volter/world-core';
+import { PLATFORM_ACCOUNT_ID } from '../engine/stripe.ts';
+import { actingAccount, accountMissing } from './shared.ts';
+
+// source: spec:GetAccount "Retrieves the details of an account."
+export async function GetAccount(ctx: HandlerContext): Promise<Response> {
+  const id = actingAccount(ctx) ?? PLATFORM_ACCOUNT_ID;
+  const account = ctx.get('account', id);
+  return account ? ctx.reply(ctx.expand('account', account)) : accountMissing(ctx, id);
+}

package/src/semantics/account_links.ts

@@ -0,0 +1,20 @@
+// Stripe's account_links 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 { nowUnix } from '../engine/stripe.ts';
+import { accountMissing, fail } from './shared.ts';
+// ── hosted onboarding links and embedded-component sessions ──
+export async function PostAccountLinks(ctx: HandlerContext): Promise<Response> {
+  const account = typeof ctx.params.account === 'string' ? ctx.params.account : '';
+  if (!account) return fail(ctx, 'Missing required param: account.', 400, 'parameter_missing');
+  if (!ctx.get('account', account)) return accountMissing(ctx, account, 400);
+  const linkType = typeof ctx.params.type === 'string' ? ctx.params.type : '';
+  if (linkType !== 'account_onboarding' && linkType !== 'account_update') return fail(ctx, 'Invalid account link type: must be account_onboarding or account_update.', 400, 'parameter_invalid_string_enum');
+  // the owner is sent back to return_url when done, and to refresh_url for a new link once this one is used or expired
+  for (const k of ['refresh_url', 'return_url']) if (typeof ctx.params[k] !== 'string' || !ctx.params[k]) return fail(ctx, `Missing required param: ${k}.`, 400, 'parameter_missing');
+  const now = Number(nowUnix(ctx.occurredAt));
+  const id = ctx.mint('account_link');
+  const link = { object: 'account_link', created: now, expires_at: now + 300, url: `https://connect.stripe.com/setup/${id}` };
+  await ctx.write('account_link', id, { ...link, account, type: linkType, refresh_url: ctx.params.refresh_url, return_url: ctx.params.return_url, used: false }, 'account_link.create');
+  return ctx.reply(link);
+}