@volter/twin-stripe 0.1.2 → 2.0.1

package/src/screens/onboarding.tsx

@@ -0,0 +1,243 @@
+// STRIPE CONNECT HOSTED ONBOARDING — a hosted flow (docs/contributing/architecture.md, "Screens"): a platform
+// creates an Account Link for a connected account and sends the account's owner to its `url`. The link is a
+// single-use entry point: visiting it takes the owner to their onboarding session, and visiting it again, or after it
+// expires, sends them to refresh_url, where the platform makes a new one (docs.stripe.com/connect/hosted-onboarding).
+// At the session's own address they give Stripe what it requires, and Stripe sends them to return_url. Submitting is
+// the owner's move, not an API call. Authored from @volter/world-ui's payment piece; nothing of Stripe's page is copied.
+//
+// The page asks for exactly what Stripe requires before a US Express account with card_payments and transfers can
+// take card payments (docs.stripe.com/connect/required-verification-information; the set is the one Stripe's
+// requirements endpoint answers, docs.stripe.com/_endpoint/get-requirements-for-setups with apiVersion=v1,
+// platformCountry=US, accountCountry=US, dashboardType=express, tosType=full, capabilities card_payments and transfers):
+// thirty requirements for a company (the business profile, the statement descriptor, the company with its tax id,
+// phone and address, its owners, its representative with their title and address, the agreement and the payout bank
+// account) and eighteen for an individual. A submit that leaves any out is refused with what is missing. The account's
+// requirements.currently_due lists what is still missing, and charges and payouts are enabled, and its requested
+// capabilities become active (Stripe's move on the capability machine), only once none is. The agreement is the
+// page's own checkbox, recorded as tos_acceptance with the request's address and the time.
+//
+// Where the documentation stops and the twin decides: only these two US sets are modelled; an account elsewhere, or
+// of another business type, is told its requirements are not modelled. Test mode verifies at once whatever is
+// submitted (docs.stripe.com/connect/testing lists the values that pass: date of birth 1901-01-01, SSN last four
+// 0000, tax id 000000000, routing 110000000, account 000123456789); the industries offered are Stripe's supported
+// 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 { 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';
+
+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());
+
+// 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 = ([
+  ['AL', 'Alabama'], ['AK', 'Alaska'], ['AZ', 'Arizona'], ['AR', 'Arkansas'], ['CA', 'California'], ['CO', 'Colorado'], ['CT', 'Connecticut'],
+  ['DE', 'Delaware'], ['DC', 'District of Columbia'], ['FL', 'Florida'], ['GA', 'Georgia'], ['HI', 'Hawaii'], ['ID', 'Idaho'], ['IL', 'Illinois'],
+  ['IN', 'Indiana'], ['IA', 'Iowa'], ['KS', 'Kansas'], ['KY', 'Kentucky'], ['LA', 'Louisiana'], ['ME', 'Maine'], ['MD', 'Maryland'],
+  ['MA', 'Massachusetts'], ['MI', 'Michigan'], ['MN', 'Minnesota'], ['MS', 'Mississippi'], ['MO', 'Missouri'], ['MT', 'Montana'], ['NE', 'Nebraska'],
+  ['NV', 'Nevada'], ['NH', 'New Hampshire'], ['NJ', 'New Jersey'], ['NM', 'New Mexico'], ['NY', 'New York'], ['NC', 'North Carolina'],
+  ['ND', 'North Dakota'], ['OH', 'Ohio'], ['OK', 'Oklahoma'], ['OR', 'Oregon'], ['PA', 'Pennsylvania'], ['RI', 'Rhode Island'],
+  ['SC', 'South Carolina'], ['SD', 'South Dakota'], ['TN', 'Tennessee'], ['TX', 'Texas'], ['UT', 'Utah'], ['VT', 'Vermont'], ['VA', 'Virginia'],
+  ['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),
+  field(`${prefix}state`, 'State', v, { options: STATES, value: v[`${prefix}state`] ?? 'OR' }), field(`${prefix}postal_code`, 'ZIP', v, { autoComplete: 'postal-code' }),
+];
+
+/** 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 {
+  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) }),
+    field('url', 'Business website', v, { placeholder: 'https://' }),
+    field('statement_descriptor', 'Statement descriptor (what customers see on their card statements)', v),
+  ];
+  const company: PaymentField[] = [
+    field('company_name', 'Legal business name', v), field('company_tax_id', 'Employer Identification Number (EIN)', v), field('company_phone', 'Business phone', v, { type: 'tel' }),
+    ...addressFields('company_', v),
+  ];
+  const owners: PaymentField[] = [
+    field('owner_first_name', 'Owner first name', v), field('owner_last_name', 'Owner last name', v), field('owner_email', 'Owner email', v, { type: 'email' }),
+    field('owners_provided', 'All owners of 25% or more are listed', v, { type: 'checkbox', value: 'provided' }),
+  ];
+  const person: PaymentField[] = [
+    field('first_name', 'First name', v, { autoComplete: 'given-name' }), field('last_name', 'Last name', v, { autoComplete: 'family-name' }),
+    field('email', 'Email', v, { type: 'email' }), field('phone', 'Phone', v, { type: 'tel' }), field('dob', 'Date of birth', v, { type: 'date' }),
+    ...(kind === 'company' ? [field('title', 'Job title', v)] : []),
+    ...addressFields('', v), field('ssn_last_4', 'Last 4 digits of SSN', v),
+  ];
+  const payout: PaymentField[] = [field('routing_number', 'Routing number', v), field('account_number', 'Account number', v)];
+  const agreement: PaymentField[] = [field('tos', 'I agree to the Stripe Connected Account Agreement', v, { type: 'checkbox', value: 'accepted' })];
+  const sections = kind === 'company'
+    ? [{ heading: 'Business details', fields: business }, { heading: 'Company', fields: company }, { heading: 'Owners', fields: owners }, { heading: 'Representative', fields: person }, { heading: 'Payout account', fields: payout }, { heading: 'Agreement', fields: agreement }]
+    : [{ heading: 'Business details', fields: business }, { heading: 'About you', fields: person }, { heading: 'Payout account', fields: payout }, { heading: 'Agreement', fields: agreement }];
+  return flowPage({
+    title: 'Stripe · Account onboarding',
+    css: [PAYMENT_CSS],
+    ...(error ? { status: 400 } : {}),
+    body: (
+      <Payment
+        merchant={`Verify your ${kind === 'company' ? 'company' : 'business'} with Stripe · ${String(link.account)} · test mode`}
+        lines={[]}
+        action={sessionUrl}
+        sections={sections}
+        submit={{ label: 'Submit' }}
+        back={{ href: String(link.return_url), label: '← Return to platform' }}
+        {...(error ? { error } : {})}
+      />
+    ),
+  });
+}
+
+/** An account whose requirements the twin does not model: outside the US, or of another business type. */
+function unmodelled(account: Row): Response {
+  return flowPage({ title: 'Stripe', status: 501, css: [CONSENT_CSS, STRIPE_CONSENT_SKIN], body: <main className="consent"><h1 className="consent-heading">{`Onboarding requirements for a ${String(account.business_type ?? 'business')} account in ${String(account.country ?? 'this country')} are not modelled by this twin.`}</h1></main> });
+}
+
+/** 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 {
+  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> {
+  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';
+  }
+  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 };
+  const addressOf = (p: string): Row => ({ line1: v[`${p}line1`], line2: null, city: v[`${p}city`], state: v[`${p}state`], postal_code: v[`${p}postal_code`], country: 'US' });
+  const [year, month, day] = (v.dob ?? '').split('-').map(Number);
+  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) ?? {};
+  await ctx.write('account', id, {
+    details_submitted: true, charges_enabled: due.length === 0, payouts_enabled: due.length === 0, capabilities: caps, requirements,
+    business_type: kind,
+    business_profile: { ...((account.business_profile as Row | undefined) ?? {}), name: company ? v.company_name : `${String(v.first_name)} ${String(v.last_name)}`, mcc: (v.mcc ?? '').trim(), url: v.url },
+    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 },
+  }, '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: {} });
+    await created(ctx, 'person', { account: id }, { first_name: v.owner_first_name, last_name: v.owner_last_name, email: v.owner_email, relationship: { owner: true, representative: false, executive: false, director: false, percent_ownership: null, title: null }, metadata: {} });
+  }
+  const digits = (v.account_number ?? '').replace(/\D/g, '');
+  await created(ctx, 'external_account', { account: id }, {
+    object: 'bank_account', account_holder_name: company ? v.company_name : `${String(v.first_name)} ${String(v.last_name)}`, account_holder_type: company ? 'company' : 'individual', bank_name: 'STRIPE TEST BANK', country: 'US', currency: 'usd',
+    default_for_currency: true, fingerprint: `twin_ext_${digits.slice(-4)}`, last4: digits.slice(-4), routing_number: v.routing_number, status: 'new', metadata: {},
+  });
+  await syncExternals(ctx, id);
+}
+
+/** Where an onboarding session lives, on connect.stripe.com. */
+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> {
+  const link = ctx.get(LINK, id);
+  if (!link) return gone();
+  if (!usable(ctx, link)) return seeOther(String(link.refresh_url));
+  const session = `onbs_${id.replace(/^acctlink_/, '')}`;
+  await ctx.write(LINK, id, { used: true, _session: session }, 'account_link.used');
+  return seeOther(`${SESSIONS}${session}`);
+}
+
+/** 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));
+  };
+}

package/src/screens/portal.tsx

@@ -0,0 +1,220 @@
+// STRIPE'S CUSTOMER PORTAL — a hosted flow (docs/contributing/architecture.md, "Screens"): an application creates
+// a portal session for its customer and sends them to the session's `url` at billing.stripe.com/p/session/{id};
+// there the customer sees their plans, payment method, billing details and invoices, and makes the moves the
+// portal configuration allows, then returns to return_url (docs.stripe.com/customer-management). Canceling is the
+// customer's own move (the subscription machine's external actor): at the period's end by default, or at once
+// when the configuration's subscription_cancel.mode says immediately, and a plan set to cancel can be renewed.
+// Each move goes through the same handler context the API's handlers use, so the application sees it as it
+// would from Stripe: on the subscription, and in its events. Authored from @volter/world-ui's portal piece under
+// Stripe's skin; nothing of Stripe's page is copied.
+//
+// The customer also replaces their card, which becomes the default for their invoices and subscriptions, and pays
+// an open invoice with it, which makes a subscription waiting on it (past_due) active again
+// (docs.stripe.com/customer-management/configure-portal: payment_method_update, invoice_history).
+//
+// Where the documentation stops and the twin decides: a session's configuration that the World never created
+// (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';
+
+const SUB = 'subscription';
+const PORTAL_OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'PostBillingPortalSessions')!;
+
+// Stripe's skin: its type, its purple accent, the merchant's side tinted.
+const SKIN = `
+body { color: #1a1a1a; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; }
+.portal-side { background: #f7f7f9; }
+.portal-back { color: #635bff; }
+.portal-section h2 { color: #6b7280; border-color: #e5e7eb; }
+.portal-item { border-bottom: 1px solid #f0f0f3; }
+.portal-detail, .portal-note { color: #6b7280; }
+.portal-badge { background: #eef0f4; color: #414552; }
+.portal-button { border-color: #d5dbe1; color: #1a1a1a; }
+.portal-primary { background: #635bff; border-color: #635bff; color: #ffffff; }
+.portal-danger { color: #df1b41; border-color: #f4c7d0; }
+.portal-empty { color: #6b7280; }
+`;
+
+const day = (epoch: unknown): string => new Date(Number(epoch) * 1000).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric', timeZone: 'UTC' });
+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 {
+  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;
+  const update = (f?.payment_method_update ?? {}) as Row;
+  return {
+    cancel: { enabled: f ? cancel.enabled === true : true, mode: cancel.mode === 'immediately' ? 'immediately' : 'at_period_end' },
+    invoices: f ? invoices.enabled !== false : true,
+    paymentMethod: f ? update.enabled === true : true,
+  };
+}
+
+function planOf(ctx: SemanticsContext, 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);
+  const recurring = price?.recurring as Row | undefined;
+  return {
+    name: String(product?.name ?? price?.nickname ?? 'Plan'),
+    price: price ? `${money(price.unit_amount, price.currency)}${recurring?.interval ? ` per ${String(recurring.interval)}` : ''}` : '',
+  };
+}
+
+function page(ctx: SemanticsContext, 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 plans: PortalItem[] = subs.map((s) => {
+    const plan = planOf(ctx, s);
+    const ending = s.cancel_at_period_end === true;
+    return {
+      title: plan.name,
+      detail: plan.price,
+      badge: s.status === 'trialing' ? 'Trial' : s.status === 'past_due' ? 'Past due' : ending ? 'Cancels' : undefined,
+      note: ending ? `Your plan will be canceled on ${day(s.current_period_end)}.` : s.status === 'trialing' ? `Trial ends ${day(s.trial_end)}.` : `Renews on ${day(s.current_period_end)}.`,
+      actions: ending
+        ? [{ label: 'Renew plan', action: `/p/session/${id}/renew`, fields: { subscription: String(s.id) }, tone: 'primary' as const }]
+        : features.cancel.enabled ? [{ label: 'Cancel plan', action: `/p/session/${id}/cancel`, fields: { subscription: String(s.id) }, tone: 'danger' as const }] : [],
+    };
+  });
+  const defaultPm = ((customer.invoice_settings as Row | undefined)?.default_payment_method as string | undefined) ?? undefined;
+  const pms = ctx.rows('payment_method').filter((p) => p.customer === session.customer);
+  const subDefault = subs.map((sub) => payerOf(ctx, sub)).find((p) => typeof p === 'string');
+  const pm = (defaultPm ? pms.find((p) => p.id === defaultPm) : undefined) ?? (subDefault ? pms.find((p) => p.id === subDefault) : undefined) ?? pms[0];
+  const card = pm?.card as Row | undefined;
+  const methods: PortalItem[] = pm ? [{ title: `${String(card?.brand ?? 'card').replace(/^./, (c) => c.toUpperCase())} •••• ${String(card?.last4 ?? '')}`, detail: card ? `Expires ${String(card.exp_month).padStart(2, '0')}/${String(card.exp_year)}` : undefined, badge: 'Default' }] : [];
+  const address = customer.address as Row | undefined;
+  const details: PortalItem[] = [{ title: String(customer.name ?? customer.email ?? ''), detail: String(customer.email ?? ''), ...(address?.country ? { note: [address.line1, address.city, address.postal_code, address.country].filter(Boolean).join(', ') } : {}) }];
+  const invoices: PortalItem[] = features.invoices
+    ? ctx.rows('invoice').filter((i) => i.customer === session.customer && i.status !== 'draft').sort((a, b) => Number(b.created) - Number(a.created))
+      .map((i) => ({
+        title: day(i.created), detail: money(i.amount_due ?? i.total, i.currency), badge: String(i.status ?? '').replace(/^./, (c) => c.toUpperCase()),
+        ...(i.status === 'open' && i.collection_method !== 'send_invoice' ? { actions: [{ label: 'Pay', action: `/p/session/${id}/pay`, fields: { invoice: String(i.id) }, tone: 'primary' as const }] } : {}),
+      }))
+    : [];
+  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
+  // 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
+  const owner = session.on_behalf_of ?? ctx.row('billing_portal.session', String(session.id))?._brand_account;
+  const merchant = publicBusinessName(ctx.get('account', typeof owner === 'string' ? owner : PLATFORM_ACCOUNT_ID));
+  const v = problem?.values ?? {};
+  const cardFields: PaymentField[] = [
+    { id: 'cardNumber', label: 'Card number', autoComplete: 'cc-number', placeholder: '1234 1234 1234 1234', value: v.cardNumber ?? '' },
+    { id: 'cardExpiry', label: 'Expiration', autoComplete: 'cc-exp', placeholder: 'MM / YY', value: v.cardExpiry ?? '' },
+    { id: 'cardCvc', label: 'CVC', autoComplete: 'cc-csc', placeholder: 'CVC', value: v.cardCvc ?? '' },
+    { id: 'billingName', label: 'Name on card', autoComplete: 'cc-name', value: v.billingName ?? '' },
+    { id: 'billingCountry', label: 'Country or region', options: COUNTRIES, value: v.billingCountry ?? 'US' },
+    { id: 'billingPostalCode', label: 'ZIP', autoComplete: 'postal-code', value: v.billingPostalCode ?? '' },
+  ];
+  return flowPage({
+    title: 'Billing',
+    css: [PORTAL_CSS, SKIN],
+    ...(problem ? { status: 402 } : {}),
+    body: (
+      <Portal
+        merchant={merchant}
+        {...(problem ? { notice: problem.error } : {})}
+        {...(features.paymentMethod ? { forms: [{ heading: pm ? 'Update payment method' : 'Add payment method', action: `/p/session/${id}/payment_method`, fields: cardFields, submit: { label: pm ? 'Update' : 'Add' } }] } : {})}
+        {...(back ? { back: { href: back, label: `← Return to ${merchant}` } } : {})}
+        sections={[
+          { heading: 'Current plan', items: plans, empty: 'You have no active plans.' },
+          { heading: 'Payment method', items: methods, empty: 'No payment method on file.' },
+          { heading: 'Billing information', items: details },
+          ...(features.invoices ? [{ heading: 'Invoice history', items: invoices, empty: 'No invoices yet.' }] : []),
+        ]}
+      />
+    ),
+  });
+}
+
+/** 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);
+  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') {
+    await ctx.write(SUB, subscription, { cancel_at_period_end: false, cancel_at: null, canceled_at: null, cancellation_details: { comment: null, feedback: null, reason: null } }, 'subscription.update');
+    return back;
+  }
+  const features = featuresOf(ctx, session);
+  if (!features.cancel.enabled) return gone();
+  const now = Number(ctx.now());
+  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');
+    return back;
+  }
+  const refused = ctx.legal(SUB, 'status', PORTAL_OPERATION.id, sub.status, 'canceled', subscription, 'external');
+  if (refused) return gone();
+  await ctx.write(SUB, subscription, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details: details }, 'subscription.cancel');
+  return back;
+}
+
+/** 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> {
+  if (!featuresOf(ctx, session).paymentMethod) return gone();
+  const refused = cardAnswer(v, Number(ctx.now()), 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()));
+  const card = { number: (v.cardNumber ?? '').replace(/\D/g, ''), exp_month: month ?? 12, exp_year: (year ?? 0) < 100 ? 2000 + (year ?? 0) : (year ?? 0) };
+  const pm = await created(ctx, 'payment_method', {}, {
+    type: 'card', customer, livemode: false,
+    billing_details: { address: { country: v.billingCountry || null, postal_code: v.billingPostalCode || null, city: null, line1: null, line2: null, state: null }, email: null, name: v.billingName || null, phone: null },
+    ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null,
+    ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}),
+  });
+  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')) {
+    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> {
+  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 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: {} });
+  const declined = await payOpenInvoice(ctx, invoiceId, pm);
+  if (declined) return page(ctx, id, session, { error: declined.message, values: {} });
+  return new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
+}
+
+/** 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);
+  };
+}

package/src/screens/public-details.tsx

@@ -0,0 +1,105 @@
+// 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 (semantics/connect.ts `platform`), 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, as none guards the Dashboard mirror. The page
+// is matched by its path on whatever host reaches the twin (the World routes only dashboard.stripe.com's
+// /settings/public here; the local mirror serves it on its own origin), and the form posts to the page's own address
+// and the save redirects to its own path, so it also works under the hosted mirror's path prefix. 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.
+import { semanticsContext, type SemanticsContext } from '@volter/world-core';
+import { flowPage } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from '../manifest.ts';
+import { platformAccountDefault } from '../semantics/connect.ts';
+import { created, type Row } from '../semantics/shared.ts';
+import { publicBusinessName } from '../stripe-shared.ts';
+import { PLATFORM_ACCOUNT_ID } from '../stripe-twin.ts';
+import { formOf } from './consent-skin.ts';
+
+export const PUBLIC_DETAILS_PATH = '/settings/public';
+const MAX_NAME = 5000;
+const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'PostAccountsAccount')!;
+
+const 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 page(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: [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: SemanticsContext, 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;
+}
+
+export function stripePublicDetailsFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
+  return async (request) => {
+    const url = new URL(request.url);
+    if (url.pathname.replace(/\/+$/, '') !== PUBLIC_DETAILS_PATH || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
+    // the form is read before the context, which reads the request's body itself
+    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+    if (request.method === 'GET') return page(ctx.get('account', PLATFORM_ACCOUNT_ID), { saved: url.searchParams.has('saved') });
+    const name = (form.business_name ?? '').trim();
+    const refused = nameRefused(name);
+    if (refused) return page(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' } });
+  };
+}