@volter/twin-stripe 2.0.38 → 3.0.0

package/src/screens/dashboard.tsx

@@ -0,0 +1,198 @@
+// 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). Stripe's other Dashboard pages answer Stripe's 404 here.
+//
+// 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 type { Row } from '../engine/common.ts';
+import { platformAccountDefault } from '../engine/connect.ts';
+import { CONNECT_SETTINGS_PATH, type ConnectOAuthSettings, PLATFORM_CLIENT_ID, redirectUris, SETTINGS } from '../engine/connect-settings.ts';
+import { publicBusinessName } from '../engine/display.ts';
+import { PLATFORM_ACCOUNT_ID } from '../engine/stripe.ts';
+import { formOf, notFound } from './shared.tsx';
+import { connectOAuthSettings, created } from '../semantics/shared.ts';
+
+const PUBLIC_DETAILS_PATH = '/settings/public';
+const MAX_NAME = 5000;
+
+const SETTINGS_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; }
+.co { max-width: 680px; margin: 48px auto; padding: 0 16px; }
+.co h1 { font-size: 28px; margin: 16px 0 4px; }
+.co-lead { color: #697386; margin: 0 0 24px; }
+.co-card { background: #ffffff; border: 1px solid #e3e8ee; border-radius: 8px; padding: 24px; margin-bottom: 16px; }
+.co-card h2 { font-size: 16px; margin: 0 0 12px; }
+.co-card label { display: block; font-weight: 600; margin-bottom: 6px; }
+.co-card small { display: block; color: #697386; margin-bottom: 8px; }
+.co-card textarea { width: 100%; min-height: 96px; padding: 8px 10px; border: 1px solid #c1c9d2; border-radius: 6px; font: 13px ui-monospace, Menlo, monospace; }
+.co-id { font: 14px ui-monospace, Menlo, monospace; background: #f6f8fa; border: 1px solid #e3e8ee; border-radius: 6px; padding: 6px 10px; display: inline-block; }
+.co-toggle { display: flex; gap: 8px; align-items: center; font-weight: 600; }
+.co-actions { display: flex; justify-content: flex-end; }
+.co-actions button { background: #635bff; color: #ffffff; border: 0; border-radius: 6px; padding: 8px 16px; font: inherit; font-weight: 600; cursor: pointer; }
+.co-notice { padding: 10px 12px; border-radius: 6px; margin-bottom: 16px; }
+.co-error { background: #fff0f3; color: #df1b41; }
+.co-saved { background: #e7f8ef; color: #0e6245; }
+.co-uris { margin: 0; padding-left: 18px; }
+`;
+
+function settingsPage(s: ConnectOAuthSettings, opts: { value?: string; enabled?: boolean; error?: string; saved?: boolean } = {}): Response {
+  const enabled = opts.enabled ?? s.oauth_enabled;
+  return flowPage({
+    title: 'OAuth – Connect settings – Stripe',
+    css: [SETTINGS_CSS],
+    ...(opts.error ? { status: 400 } : {}),
+    body: (
+      <main className="co">
+        <h1>OAuth</h1>
+        <p className="co-lead">Onboard Standard accounts by sending them to Stripe's OAuth flow. Test mode.</p>
+        {opts.error ? <p className="co-notice co-error" role="alert">{opts.error}</p> : null}
+        {opts.saved ? <p className="co-notice co-saved" role="status">Your OAuth settings were saved.</p> : null}
+        <section className="co-card">
+          <h2>Test mode client ID</h2>
+          <small>The client_id your platform sends to connect.stripe.com/oauth/authorize.</small>
+          <code className="co-id" data-testid="connect-client-id">{PLATFORM_CLIENT_ID}</code>
+          <p data-testid="connect-oauth-status">{s.oauth_enabled ? 'OAuth is enabled.' : 'OAuth is disabled.'}</p>
+          {s.redirect_uris.length ? <ul className="co-uris">{s.redirect_uris.map((u) => <li key={u} data-testid="connect-redirect-uri">{u}</li>)}</ul> : <p>No redirect URIs.</p>}
+        </section>
+        <form className="co-card" method="post">
+          <label className="co-toggle" htmlFor="oauth_enabled"><input type="checkbox" id="oauth_enabled" name="oauth_enabled" value="on" defaultChecked={enabled} /> Enable OAuth for Standard accounts</label>
+          <label htmlFor="redirect_uris">Redirect URIs</label>
+          <small>One per line. The first is used when a request names none. http and localhost are allowed in test mode.</small>
+          <textarea id="redirect_uris" name="redirect_uris" defaultValue={opts.value ?? s.redirect_uris.join('\n')} />
+          <div className="co-actions"><button type="submit">Save</button></div>
+        </form>
+      </main>
+    ),
+  });
+}
+
+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 settings(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()) : {};
+  const held = connectOAuthSettings(ctx);
+  if (request.method === 'GET') return settingsPage(held, { saved: url.searchParams.has('saved') });
+  const enabled = form.oauth_enabled === 'on' || form.oauth_enabled === 'true';
+  const parsed = redirectUris(form.redirect_uris ?? '');
+  if ('refused' in parsed) return settingsPage(held, { value: form.redirect_uris ?? '', enabled, error: parsed.refused });
+  await ctx.record(SETTINGS, { oauth_enabled: enabled, redirect_uris: parsed.uris }, PLATFORM_CLIENT_ID);
+  return new Response(null, { status: 303, headers: { location: '?saved=1' } });
+}
+
+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.stripe.com's pages: Public details and the Connect OAuth settings; Stripe's 404 for any other. */
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const path = new URL(ctx.call.request.url).pathname.replace(/\/+$/, '');
+  if (path === PUBLIC_DETAILS_PATH) return publicDetails(ctx);
+  if (CONNECT_SETTINGS_PATH.test(path)) return settings(ctx);
+  return 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,170 @@
+// STRIPE.JS — the client library an application's page loads from js.stripe.com, served as a content screen
+// (docs/contributing/architecture.md, "Screens": a widget the vendor ships into the application's own page "is not a screen: it is a client library,
+// twinned from its published types as an SDK surface is"). Written from @stripe/stripe-js's published loader and types
+// (7.x: dist/index.mjs, dist/stripe-js/stripe.d.ts, dist/stripe-js/hosted-checkout.d.ts), nothing of Stripe's script
+// copied:
+//   - the loader injects https://js.stripe.com/<release train>/stripe.js (or /v3/), and accepts a script already on the
+//     page whose src matches `/^https:\/\/js\.stripe\.com\/(v3|[a-z]+)\/stripe\.js(\?.*)?$/` (so /v3/stripe.js too);
+//     it resolves `window.Stripe`, reads `Stripe.version` (3 is the v3 URL, otherwise the train's name) and calls the
+//     instance's `_registerWrapper` when it has one;
+//   - `stripe.redirectToCheckout({ sessionId })` sends the customer to that Checkout Session's page (hosted-checkout.d.ts,
+//     RedirectToCheckoutServerOptions), which this twin serves at checkout.stripe.com/c/pay/{id} (screens/checkout.tsx),
+//     and its promise settles only on failure (`Promise<never | {error}>`);
+//   - `stripe.collectFinancialConnectionsAccounts({ clientSecret })` loads the Financial Connections authentication
+//     flow for the session whose client_secret it is (stripe.d.ts; docs.stripe.com/js/financial_connections/
+//     collect_financial_connections_accounts: "it will load the Authentication Flow, an on-page modal UI"). Where the
+//     twin decides: it navigates to the flow's page, js.stripe.com/v3/financial-connections/{client_secret}
+//     (screens/financial-connections.tsx), instead of a modal, so its promise does not settle; the flow returns the
+//     holder to the session's return_url, where the application reads the session's accounts.
+//   - `stripe.elements({ clientSecret?, ... })` groups elements; `elements.create('payment' | 'card')` makes one, which
+//     `mount`s into the page and emits `ready` and `change` ({ complete, empty }); `elements.submit()` checks the fields
+//     (stripe.d.ts: StripeElements, StripePaymentElement). Where the twin decides: an element is the page's own card
+//     fields (number, expiry, CVC), not Stripe's iframe;
+//   - `stripe.confirmPayment({ elements, clientSecret?, confirmParams: { return_url }, redirect? })` and
+//     `stripe.confirmSetup(...)` confirm the intent whose client secret it is with the card the element holds
+//     (`POST /v1/payment_intents/{id}/confirm`, `/v1/setup_intents/{id}/confirm`, with the publishable key), then send
+//     the customer to `return_url` with `payment_intent` (or `setup_intent`), its client secret and `redirect_status`,
+//     or, with `redirect: 'if_required'`, resolve `{ paymentIntent }` (`{ setupIntent }`); a refusal resolves
+//     `{ error }` (docs.stripe.com/js/payment_intents/confirm_payment).
+// Demand: Dub's upgrade button (apps/web/ui/workspaces/upgrade-plan-button.tsx) and cal.com's sign-up call
+// redirectToCheckout; cal.com's booking payment form (packages/platform/atoms/event-types/payments/StripePaymentForm.tsx)
+// and Twenty's billing forms (AddPaymentMethodForm.tsx, useSubmitSubscriptionPayment.ts) confirm intents through
+// Elements. Every other member of the library throws, naming itself, when called: an application reaching one finds the
+// gap instead of a silent no-op.
+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 {
+  if (/^\/v3(\/|\/stripe\.js)?$/.test(pathname)) return 3;
+  return /^\/([a-z]+)\/stripe\.js$/.exec(pathname)?.[1];
+}
+
+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 Stripe(publishableKey) {
+    if (typeof publishableKey !== "string" || !publishableKey) throw new Error("Stripe.js (Volter twin): Stripe() needs a publishable key");
+    var api = "https://api.stripe.com/v1";
+    // the card fields every mounted element holds, the last mounted first
+    var mounted = [];
+    function cardOf(elements) {
+      var el = (elements && elements._mounted && elements._mounted[elements._mounted.length - 1]) || mounted[mounted.length - 1];
+      if (!el) return null;
+      var exp = String(el.expiry.value || "").split("/");
+      return { number: String(el.number.value || "").replace(/\s+/g, ""), exp_month: exp[0] ? String(Number(exp[0])) : "", exp_year: exp[1] ? String(2000 + Number(exp[1]) % 100) : "", cvc: String(el.cvc.value || "") };
+    }
+    function form(fields) {
+      return Object.keys(fields).filter(function (k) { return fields[k] !== undefined && fields[k] !== ""; }).map(function (k) { return encodeURIComponent(k) + "=" + encodeURIComponent(fields[k]); }).join("&");
+    }
+    function confirm(kind, options) {
+      options = options || {};
+      var elements = options.elements;
+      var secret = options.clientSecret || (elements && elements._options && elements._options.clientSecret);
+      if (typeof secret !== "string" || secret.indexOf("_secret_") < 0) return Promise.resolve({ error: { type: "invalid_request_error", message: "A clientSecret is required." } });
+      var id = secret.split("_secret_")[0];
+      var card = cardOf(elements);
+      var params = options.confirmParams || {};
+      var fields = { client_secret: secret };
+      if (card) { fields["payment_method_data[type]"] = "card"; fields["payment_method_data[card][number]"] = card.number; fields["payment_method_data[card][exp_month]"] = card.exp_month; fields["payment_method_data[card][exp_year]"] = card.exp_year; fields["payment_method_data[card][cvc]"] = card.cvc; }
+      if (params.return_url) fields.return_url = params.return_url;
+      var path = kind === "payment" ? "/payment_intents/" : "/setup_intents/";
+      return fetch(api + path + encodeURIComponent(id) + "/confirm", { method: "POST", headers: { authorization: "Bearer " + publishableKey, "content-type": "application/x-www-form-urlencoded" }, body: form(fields) })
+        .then(function (res) { return res.json().then(function (body) { return { ok: res.ok, body: body }; }); })
+        .then(function (r) {
+          if (!r.ok) return { error: r.body.error || { type: "api_error", message: "The confirmation failed." } };
+          var key = kind === "payment" ? "paymentIntent" : "setupIntent";
+          var out = {}; out[key] = r.body;
+          if (options.redirect === "if_required" || !params.return_url) return out;
+          var q = kind === "payment" ? "payment_intent" : "setup_intent";
+          var target = new URL(params.return_url);
+          target.searchParams.set(q, r.body.id);
+          target.searchParams.set(q + "_client_secret", secret);
+          target.searchParams.set("redirect_status", r.body.status === "succeeded" ? "succeeded" : r.body.status === "processing" ? "processing" : "failed");
+          window.location.assign(target.toString());
+          return new Promise(function () {});
+        });
+    }
+    function element(type, group) {
+      var handlers = {};
+      function emit(name, event) { (handlers[name] || []).forEach(function (h) { h(event); }); }
+      var el = {
+        _type: type,
+        mount: function (target) {
+          var node = typeof target === "string" ? document.querySelector(target) : target;
+          if (!node) throw new Error("Stripe.js (Volter twin): mount() found no element " + String(target));
+          node.innerHTML = "";
+          var wrap = document.createElement("div");
+          wrap.setAttribute("data-volter-twin-element", type);
+          function input(name, placeholder) { var i = document.createElement("input"); i.name = name; i.placeholder = placeholder; i.autocomplete = "off"; i.addEventListener("input", change); wrap.appendChild(i); return i; }
+          el.number = input("cardnumber", "Card number");
+          el.expiry = input("exp-date", "MM / YY");
+          el.cvc = input("cvc", "CVC");
+          node.appendChild(wrap);
+          mounted.push(el); group._mounted.push(el);
+          setTimeout(function () { emit("ready", { elementType: type }); }, 0);
+        },
+        on: function (name, handler) { (handlers[name] = handlers[name] || []).push(handler); return el; },
+        off: function (name, handler) { handlers[name] = (handlers[name] || []).filter(function (h) { return h !== handler; }); return el; },
+        update: function () {}, focus: function () { if (el.number) el.number.focus(); }, blur: function () {},
+        clear: function () { [el.number, el.expiry, el.cvc].forEach(function (i) { if (i) i.value = ""; }); change(); },
+        unmount: function () {}, destroy: function () { mounted = mounted.filter(function (m) { return m !== el; }); }
+      };
+      function change() {
+        var c = { number: el.number && el.number.value, expiry: el.expiry && el.expiry.value, cvc: el.cvc && el.cvc.value };
+        emit("change", { elementType: type, empty: !c.number && !c.expiry && !c.cvc, complete: !!(c.number && c.expiry && c.cvc), value: { type: "card" } });
+      }
+      return el;
+    }
+    var known = {
+      _registerWrapper: function () {},
+      elements: function (options) {
+        var group = { _options: options || {}, _mounted: [], _created: {} };
+        group.create = function (type) { var e = element(type, group); group._created[type] = e; return e; };
+        group.getElement = function (type) { return group._created[typeof type === "string" ? type : "card"] || null; };
+        group.update = function (next) { group._options = Object.assign({}, group._options, next || {}); };
+        group.fetchUpdates = function () { return Promise.resolve({}); };
+        group.submit = function () {
+          var card = cardOf(group);
+          if (!card || !card.number || !card.exp_month || !card.cvc) return Promise.resolve({ error: { type: "validation_error", message: "Your card details are incomplete." } });
+          return Promise.resolve({});
+        };
+        return group;
+      },
+      confirmPayment: function (options) { return confirm("payment", options); },
+      confirmSetup: function (options) { return confirm("setup", options); },
+      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 () {});
+      },
+      collectFinancialConnectionsAccounts: function (options) {
+        if (!options || typeof options.clientSecret !== "string" || !options.clientSecret) return gap("collectFinancialConnectionsAccounts without a clientSecret")();
+        window.location.assign("https://js.stripe.com/v3/financial-connections/" + encodeURIComponent(options.clientSecret));
+        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_links.ts

@@ -0,0 +1,21 @@
+// 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);
+}

package/src/semantics/accounts.ts

@@ -0,0 +1,43 @@
+// Stripe's accounts 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 { externalList, type Row } from '../engine/common.ts';
+import { capabilityBody, controllerOf, expressRequirements, keptKyc, keptPerson, RELATIONSHIP } from '../engine/connect.ts';
+import { OAUTH_CONNECTIONS } from '../engine/display.ts';
+import { ACCOUNT_TYPES, accountCapabilities, accountRequirements, accountSettings, asBool, nowUnix, PLATFORM_ACCOUNT_ID } from '../engine/stripe.ts';
+import { accountExternal, accountMissing, accountPerson, accountRow, at, connectReview, created, externalMissing, fail, list, newest, path, personMissing, refuseExternalWrite, syncExternals } from './shared.ts';
+
+export async function GetAccountsAccountExternalAccounts(ctx: HandlerContext): Promise<Response> {
+  const account = at(ctx, 'account');
+  if (!accountRow(ctx, account)) return accountMissing(ctx, account);
+  return list(ctx, 'external_account', newest(ctx, 'external_account').filter((e) => e.account === account));
+}
+
+// the requested capabilities become Stripe's status map, and settings its canonical shape
+export async function PostAccounts(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  const type = typeof params.type === 'string' ? params.type : 'standard';
+  if (!ACCOUNT_TYPES.has(type)) return fail(ctx, 'Invalid account type: must be one of express, standard, or custom.', 400, 'parameter_invalid_string_enum');
+  const { capabilities: _caps, settings: _settings, ...accountParams } = keptKyc(params);
+  const id = ctx.mint('account');
+  const made = await created(ctx, 'account', { ...accountParams, id, type }, {
+    business_type: null, charges_enabled: false, payouts_enabled: false, details_submitted: false,
+    capabilities: accountCapabilities(params), requirements: type === 'express' ? expressRequirements(params) : accountRequirements(),
+    country: typeof params.country === 'string' ? params.country : 'US',
+    default_currency: 'usd', email: params.email ?? null, metadata: {}, livemode: false,
+    settings: accountSettings(params.settings), business_profile: {},
+    controller: controllerOf(type), external_accounts: externalList(id, []),
+    future_requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+    tos_acceptance: { date: null, ip: null, user_agent: null },
+  });
+  await connectReview(ctx, String(made.id));
+  return ctx.reply(ctx.get('account', String(made.id))!);
+}
+
+// a single-use Express dashboard link, not stored
+export async function PostAccountsAccountLoginLinks(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'account');
+  if (!ctx.get('account', id)) return accountMissing(ctx, id);
+  return ctx.reply({ object: 'login_link', created: nowUnix(ctx.occurredAt), url: `https://connect.twin.local/express/${id}` });
+}
+

package/src/semantics/{apps-secrets.ts → apps.ts}

@@ -1,18 +1,19 @@
-// Apps secret-store semantics: a secret is named within a scope (the account, or one user); setting
-// the same name in the same scope overwrites it. The scope is kept as a bookkeeping key.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { created, fail, list, newest, type Row, kept } from './shared.ts';
+// Stripe's apps 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 { SECRET } from '../engine/apps-secrets.ts';
+import type { Row } from '../engine/common.ts';
+import { nowUnix } from '../engine/stripe.ts';
+import { created, fail, kept, list, named, newest, scopeKeyOf } from './shared.ts';
 
-const SECRET = 'apps.secret';
-
-function scopeKeyOf(ctx: SemanticsContext): string {
-  const scope = ctx.params.scope && typeof ctx.params.scope === 'object' ? (ctx.params.scope as Row) : undefined;
-  const scopeType = scope && typeof scope.type === 'string' ? scope.type : 'account';
-  return scopeType === 'user' ? `user:${String(scope!.user)}` : 'account';
+export async function GetAppsSecretsFind(ctx: HandlerContext): Promise<Response> {
+  const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
+  if (!name) return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+  const s = named(ctx, name);
+  return s ? ctx.reply(s) : fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
 }
-const named = (ctx: SemanticsContext, name: string): Row | undefined => ctx.rows(SECRET).find((s) => s.name === name && kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx));
 
-const set: Semantics = async (ctx) => {
+export async function PostAppsSecrets(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
   const name = typeof params.name === 'string' ? params.name : '';
   if (!name) return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
@@ -23,7 +24,7 @@ const set: Semantics = async (ctx) => {
   if (params.payload === undefined) return fail(ctx, 'Missing required param: payload.', 400, 'parameter_missing');
   const expiresAt = params.expires_at !== undefined ? Math.trunc(Number(params.expires_at)) : null;
   const existing = named(ctx, name);
-  if (existing) return ctx.reply(await ctx.write(SECRET, String(existing.id), { payload: params.payload, expires_at: expiresAt, _updated: ctx.now() }, 'apps_secret.update'));
+  if (existing) return ctx.reply(await ctx.write(SECRET, String(existing.id), { payload: params.payload, expires_at: expiresAt, _updated: nowUnix(ctx.occurredAt) }, 'apps_secret.update'));
   return ctx.reply(
     await created(ctx, SECRET, { name }, {
       livemode: false, deleted: false, expires_at: expiresAt, payload: params.payload,
@@ -31,28 +32,12 @@ const set: Semantics = async (ctx) => {
       _scope_key: scopeKeyOf(ctx),
     }),
   );
-};
-
-const find: Semantics = async (ctx) => {
-  const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
-  if (!name) return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
-  const s = named(ctx, name);
-  return s ? ctx.reply(s) : fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
-};
+}
 
-const remove: Semantics = async (ctx) => {
+export async function PostAppsSecretsDelete(ctx: HandlerContext): Promise<Response> {
   const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
   if (!name) return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
   const s = named(ctx, name);
   if (!s) return fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
   return ctx.reply(await ctx.write(SECRET, String(s.id), { deleted: true }, 'apps_secret.delete'));
-};
-
-const listSecrets: Semantics = async (ctx) => list(ctx, SECRET, newest(ctx, SECRET).filter((s) => kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx)));
-
-export const appsSecrets: Record<string, Semantics> = {
-  PostAppsSecrets: set,
-  GetAppsSecretsFind: find,
-  PostAppsSecretsDelete: remove,
-  GetAppsSecrets: listSecrets,
-};
+}

package/src/semantics/around.ts

@@ -0,0 +1,20 @@
+// What Stripe does around every API request (docs/contributing/architecture.md, "What an author writes": around): a
+// request's key is one Stripe issued (the platform's, or a connected account's OAuth key); an OAuth key acts as its
+// connected account; a publishable key is held to the client-side calls, a revoked account is
+// refused and the parameters are checked against the operation's; a metadata hash merges; and every answer is rendered
+// in the caller's API version (../engine/front.ts).
+import type { HandlerContext } from '@volter/world-core';
+import { actingAsOAuthKey, platformKeyRefused, publishableKeyRefused, refuseParameters, rendered, revokedAccountRefused, withMetadata } from './shared.ts';
+
+export async function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response> {
+  const arrived = ctx.call.request;
+  const unkeyed = platformKeyRefused(ctx, arrived);
+  if (unkeyed) return unkeyed;
+  const acting = await actingAsOAuthKey(ctx, arrived.clone());
+  if (acting instanceof Response) return acting;
+  if (ctx.call.operation.id !== 'unmatched') {
+    const refused = publishableKeyRefused(ctx) ?? revokedAccountRefused(ctx) ?? refuseParameters(ctx);
+    if (refused) return refused;
+  }
+  return rendered(arrived, await next(withMetadata(ctx, acting)));
+}