@volter/twin-stripe 0.1.1 → 2.0.0

package/dist/src/screens/checkout.d.ts

@@ -0,0 +1,31 @@
+import { type SemanticsContext } from '@volter/world-core';
+import { type Row } from '../semantics/shared.js';
+export declare const money: (minor: unknown, currency: unknown) => string;
+export declare const COUNTRIES: {
+    value: string;
+    label: string;
+}[];
+/** 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 declare function parseExpiry(raw: string): {
+    month: number;
+    year: number;
+} | undefined;
+/** The card's answer: undefined when it pays, else what Checkout says under the button. */
+export declare function cardAnswer(v: Record<string, string>, nowSeconds: number, chargesNow: boolean): string | undefined;
+/** checkout.stripe.com's pages, or undefined for any other request. */
+/** The name the page shows: the session's own `branding_settings.display_name` where the create set one, else the
+ *  public business name (stripe-shared.ts, publicBusinessName) of the account whose brand Checkout uses: "Checkout uses
+ *  the brand settings of the connected account for destination charges with on_behalf_of and for platforms performing
+ *  direct charges" (a session made with Stripe-Account), and otherwise the platform's; "If you omit a field in
+ *  branding_settings, Checkout applies the default value from the Dashboard"
+ *  (docs.stripe.com/payments/checkout/customization/appearance). */
+export declare function merchantOf(ctx: SemanticsContext, stored: Row): string;
+export declare function stripeCheckoutFlow(scope: {
+    root?: string;
+    clock?: () => string;
+}): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/checkout.js

@@ -0,0 +1,241 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// STRIPE CHECKOUT — a hosted flow (docs/contributing/architecture.md, "Screens"): an application creates a
+// Checkout Session and sends its customer to the session's `url` at checkout.stripe.com/c/pay/{id}; the
+// customer pays there, the session completes (what the payment made is linked on it and
+// checkout.session.completed is delivered), and Checkout redirects to success_url with
+// {CHECKOUT_SESSION_ID} filled in, or the customer goes back to cancel_url
+// (docs.stripe.com/payments/checkout/how-checkout-works). Paying is a move no API call makes: the external
+// actor's move on the session's machine, taken here through the same handler context the API's handlers use.
+// The page is authored from @volter/world-ui's payment piece under Stripe's skin, nothing of Stripe's page
+// copied; its fields carry the ids tests of Checkout fill (email, cardNumber, cardExpiry, cardCvc,
+// billingName, billingCountry, billingPostalCode) and its button the test id Stripe gives it.
+//
+// Where the documentation stops and the twin decides: test cards answer as docs.stripe.com/testing lists
+// (4242… pays; 4000000000000002 declines; …9995 insufficient funds; …0069 expired; …0127 incorrect CVC;
+// …0341 is saved but declines when charged, so it declines on a page that charges now and is saved on one that
+// only sets the card up: setup mode, or a subscription's trial);
+// any other number that passes the Luhn check pays, and a card that asks for authentication pays without
+// the challenge. A subscription session with no customer makes one from the email, as Stripe does.
+import { semanticsContext } from '@volter/world-core';
+import { flowPage, Payment, PAYMENT_CSS } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { completeSession, isOneTime } from "../semantics/checkout.js";
+import { newCustomer } from "../semantics/customers.js";
+import { created } from "../semantics/shared.js";
+import { publicBusinessName } from "../stripe-shared.js";
+import { applyCouponDiscount, PLATFORM_ACCOUNT_ID, resolveTrial } from "../stripe-twin.js";
+import { formOf } from "./consent-skin.js";
+const CS = 'checkout.session';
+const COMPLETE_OPERATION = surface.operations.find((o) => o.id === 'PostCheckoutSessionsSession');
+const DECLINES = {
+    '4000000000000002': 'Your card was declined.',
+    '4000000000009995': 'Your card has insufficient funds.',
+    '4000000000000069': 'Your card has expired.',
+    '4000000000000127': "Your card's security code is incorrect.",
+};
+const luhn = (digits) => {
+    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, currency) => {
+    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));
+};
+// Stripe's skin: its type, its blue submit, the summary on a tinted half.
+const SKIN = `
+body { color: #1a1a1a; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; }
+.pay-summary { background: #f7f7f9; }
+.pay-back, .pay-line small, .pay-total-lead span { color: #6b7280; }
+.pay-field input, .pay-field select { border-color: #e0e0e0; background: #ffffff; }
+.pay-error { color: #df1b41; }
+.pay-submit { background: #0074d4; color: #ffffff; }
+`;
+export const COUNTRIES = [['US', 'United States'], ['GB', 'United Kingdom'], ['CA', 'Canada'], ['DE', 'Germany'], ['FR', 'France'], ['AU', 'Australia'], ['JP', 'Japan']].map(([value, label]) => ({ value: value, label: label }));
+/** A subscription session's trial, when its subscription_data gives one: `trial_period_days`, or `trial_end`
+ *  (docs.stripe.com/payments/checkout/free-trials), as resolveTrial makes the subscription's at completion. */
+function trialOf(session, now) {
+    const data = session._subscription_data;
+    return session.mode === 'subscription' && data && typeof data === 'object' ? resolveTrial(data, now) : undefined;
+}
+/** A session line's inline price_data, when it was given one (semantics/checkout.ts keeps them). */
+const inlineOf = (session, i) => session._price_data?.[i];
+const recurringOf = (item) => (item.price && typeof item.price === 'object' ? item.price.recurring ?? undefined : undefined);
+/** How often a price bills, as Checkout says it after the amount: "per month". Where the documentation stops and the twin
+ *  decides: a price billing every several intervals reads "every 3 months". */
+function cadenceOf(session) {
+    const lines = (session.line_items?.data) ?? [];
+    const recurring = lines.map((it, i) => recurringOf(it) ?? inlineOf(session, i)?.recurring).find(Boolean);
+    const interval = typeof recurring?.interval === 'string' ? recurring.interval : 'month';
+    const count = Math.max(1, Math.trunc(Number(recurring?.interval_count ?? 1)) || 1);
+    return count === 1 ? `per ${interval}` : `every ${count} ${interval}s`;
+}
+/** What a trial's Checkout says, as checkout.stripe.com shows it for a 14-day trial of a $12.99 monthly price: the lead
+ *  "14 days free" over "Then $12.99 per month", the button "Start trial", and under it "After your trial ends, you will
+ *  be charged $12.99 per month starting July 7, 2025. You can always cancel before then." (a live Checkout page's
+ *  screenshot, github.com/stripe/stripe-react-native/issues/1975; Stripe's docs describe no wording). Where that stops
+ *  and the twin decides: a one-day trial reads "1 day free", a trial set by `trial_end` counts its days rounded up, and
+ *  the amount is the session's total, what the first invoice after the trial charges. */
+function trialSummary(session, trial) {
+    const days = Math.ceil((trial.end - trial.start) / 86400);
+    const then = `${money(afterTrial(session), session.currency)} ${cadenceOf(session)}`;
+    const date = new Date(trial.end * 1000).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric', timeZone: 'UTC' });
+    return {
+        lead: { label: '', amount: `${days} ${days === 1 ? 'day' : 'days'} free`, detail: `Then ${then}` },
+        note: `After your trial ends, you will be charged ${then} starting ${date}. You can always cancel before then.`,
+    };
+}
+/** What each period after the trial charges, as the subscription's invoices will: its recurring line items (a one-time
+ *  item is on the first invoice only, semantics/checkout.ts isOneTime), under the session's coupon unless the coupon is `once`, which the trial's own $0
+ *  invoice takes (semantics/renewals.ts draftSubscriptionInvoice). */
+function afterTrial(session) {
+    const items = ((session.line_items?.data) ?? []).filter((it, i) => !isOneTime(it, inlineOf(session, i)));
+    const subtotal = items.reduce((sum, it) => sum + (Number(it.amount_subtotal) || 0), 0);
+    const coupon = session._coupon;
+    return subtotal - (coupon && coupon.duration !== 'once' ? applyCouponDiscount(subtotal, coupon) : 0);
+}
+function page(session, id, now, values = {}, error) {
+    const lines = ((session.line_items?.data) ?? []).map((item) => ({
+        name: String(item.description ?? 'Item'),
+        amount: money(item.amount_total, item.currency ?? session.currency),
+        ...(Number(item.quantity) > 1 ? { detail: `Qty ${String(item.quantity)}` } : {}),
+    }));
+    const mode = String(session.mode);
+    const merchant = String(session._merchant);
+    const trial = trialOf(session, now);
+    const submit = mode === 'setup' ? 'Save card' : mode === 'subscription' ? (trial ? 'Start trial' : 'Subscribe') : 'Pay';
+    const trialText = trial ? trialSummary(session, trial) : undefined;
+    const contact = typeof session.customer_email === 'string'
+        ? [{ id: 'email', label: 'Email', type: 'email', autoComplete: 'email', value: session.customer_email }]
+        : [{ id: 'email', label: 'Email', type: 'email', autoComplete: 'email', placeholder: 'email@example.com', value: values.email ?? '' }];
+    const card = [
+        { id: 'cardNumber', label: 'Card number', autoComplete: 'cc-number', placeholder: '1234 1234 1234 1234', value: values.cardNumber ?? '' },
+        { id: 'cardExpiry', label: 'Expiration', autoComplete: 'cc-exp', placeholder: 'MM / YY', value: values.cardExpiry ?? '', format: 'card-expiry' },
+        { id: 'cardCvc', label: 'CVC', autoComplete: 'cc-csc', placeholder: 'CVC', value: values.cardCvc ?? '' },
+        { id: 'billingName', label: 'Cardholder name', autoComplete: 'cc-name', placeholder: 'Full name on card', value: values.billingName ?? '' },
+        { id: 'billingCountry', label: 'Country or region', options: COUNTRIES, value: values.billingCountry ?? 'US' },
+        { id: 'billingPostalCode', label: 'ZIP', autoComplete: 'postal-code', placeholder: 'ZIP', value: values.billingPostalCode ?? '' },
+    ];
+    return flowPage({
+        title: 'Checkout',
+        css: [PAYMENT_CSS, SKIN],
+        status: error ? 402 : 200,
+        body: (_jsx(Payment, { merchant: merchant, lines: lines, ...(trialText ? { total: trialText.lead, note: trialText.note } : session.amount_total !== null && session.amount_total !== undefined ? { total: { label: mode === 'subscription' ? 'Subscribe' : `Pay ${merchant}`, amount: money(session.amount_total, session.currency) } } : {}), action: `/c/pay/${id}`, sections: [{ heading: 'Contact information', fields: contact }, { heading: 'Payment method', fields: card }], submit: { label: submit, testId: 'hosted-payment-submit-button' }, ...(typeof session.cancel_url === 'string' ? { back: { href: session.cancel_url, label: '← Back' } } : {}), ...(error ? { error } : {}) })),
+    });
+}
+const gone = () => flowPage({ title: 'Checkout', status: 404, css: [PAYMENT_CSS, SKIN], body: _jsx("main", { className: "pay-form", children: _jsx("h1", { children: "This Checkout Session is no longer active." }) }) });
+/** Cards that are saved but decline when charged. */
+const DECLINES_WHEN_CHARGED = { '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) {
+    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, nowSeconds, chargesNow) {
+    const digits = (v.cardNumber ?? '').replace(/\D/g, '');
+    if (!digits)
+        return 'Your card number is incomplete.';
+    if (DECLINES[digits])
+        return DECLINES[digits];
+    if (chargesNow && DECLINES_WHEN_CHARGED[digits])
+        return DECLINES_WHEN_CHARGED[digits];
+    if (!luhn(digits))
+        return 'Your card number is invalid.';
+    const exp = parseExpiry(v.cardExpiry ?? '');
+    if (!exp)
+        return "Your card's expiration date is incomplete.";
+    const { month, year } = exp;
+    if (month < 1 || month > 12)
+        return "Your card's expiration date is invalid.";
+    const now = new Date(nowSeconds * 1000);
+    if (year < now.getUTCFullYear() || (year === now.getUTCFullYear() && month < now.getUTCMonth() + 1))
+        return "Your card's expiration year is in the past.";
+    if (!/^\d{3,4}$/.test(v.cardCvc ?? ''))
+        return "Your card's security code is incomplete.";
+    return undefined;
+}
+async function pay(ctx, id, session, v) {
+    const email = typeof session.customer_email === 'string' ? session.customer_email : (v.email ?? '').trim();
+    if (session.mode !== 'setup' || !session.customer) {
+        if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email))
+            return page(session, id, Number(ctx.now()), v, 'Your email address is incomplete.');
+    }
+    // a trial charges nothing now unless a one-time price is on the first invoice
+    const oneTimeDue = ((session.line_items?.data) ?? []).some((it, i) => isOneTime(it, inlineOf(session, i)));
+    const chargesNow = session.mode === 'payment' || (session.mode === 'subscription' && (!trialOf(session, Number(ctx.now())) || oneTimeDue));
+    const refused = cardAnswer(v, Number(ctx.now()), chargesNow);
+    if (refused)
+        return page(session, id, Number(ctx.now()), v, refused);
+    let existing = session;
+    // Checkout always makes a customer for a subscription; a payment makes one only when the session asks
+    if (!session.customer && (session.mode === 'subscription' || session.customer_creation === 'always')) {
+        const cid = ctx.mint('customer');
+        const customer = await created(ctx, 'customer', { id: cid, email, ...(v.billingName ? { name: v.billingName } : {}) }, { livemode: false, ...newCustomer(cid) });
+        existing = { ...session, customer: customer.id };
+    }
+    const details = {
+        customer_details: { email, name: v.billingName || null, address: { country: v.billingCountry || null, postal_code: v.billingPostalCode || null, city: null, line1: null, line2: null, state: null }, phone: null, tax_exempt: 'none', tax_ids: [] },
+        ...(existing.customer !== session.customer ? { customer: existing.customer } : {}),
+    };
+    const exp = parseExpiry(v.cardExpiry ?? '');
+    const done = await completeSession(ctx, id, existing, details, { number: (v.cardNumber ?? '').replace(/\D/g, ''), exp_month: exp.month, exp_year: exp.year });
+    if (done instanceof Response)
+        return gone();
+    const to = String(session.success_url).replaceAll('{CHECKOUT_SESSION_ID}', id);
+    return new Response(null, { status: 303, headers: { location: to } });
+}
+/** checkout.stripe.com's pages, or undefined for any other request. */
+/** The name the page shows: the session's own `branding_settings.display_name` where the create set one, else the
+ *  public business name (stripe-shared.ts, publicBusinessName) of the account whose brand Checkout uses: "Checkout uses
+ *  the brand settings of the connected account for destination charges with on_behalf_of and for platforms performing
+ *  direct charges" (a session made with Stripe-Account), and otherwise the platform's; "If you omit a field in
+ *  branding_settings, Checkout applies the default value from the Dashboard"
+ *  (docs.stripe.com/payments/checkout/customization/appearance). */
+export function merchantOf(ctx, stored) {
+    const brand = stored._branding_settings?.display_name;
+    const behalf = stored._payment_intent_data?.on_behalf_of ?? stored._subscription_data?.on_behalf_of;
+    const account = typeof behalf === 'string' ? behalf : typeof stored._brand_account === 'string' ? stored._brand_account : PLATFORM_ACCOUNT_ID;
+    return typeof brand === 'string' && brand.trim() ? brand : publicBusinessName(ctx.get('account', account));
+}
+export function stripeCheckoutFlow(scope) {
+    return async (request) => {
+        const m = /^\/c\/pay\/(cs_[A-Za-z0-9_]+)\/?$/.exec(new URL(request.url).pathname);
+        if (!m || (request.method !== 'GET' && request.method !== 'POST'))
+            return undefined;
+        const id = m[1];
+        // the form is read before the context, which reads the request's body itself
+        const values = request.method === 'POST' ? await formOf(request.clone()) : {};
+        const ctx = await semanticsContext(manifest, request, COMPLETE_OPERATION, scope);
+        const session = ctx.get(CS, id);
+        if (!session)
+            return gone();
+        // an ended session's page is gone; paying on one is the customer's move the machine refuses
+        if (session.status !== 'open' && (request.method === 'GET' || ctx.legal(CS, 'status', COMPLETE_OPERATION.id, String(session.status), 'complete', id, 'external')))
+            return gone();
+        const stored = ctx.row(CS, id) ?? {};
+        const coupon = stored._discount?.coupon;
+        const full = { ...session, _subscription_data: stored._subscription_data, _price_data: stored._price_data, _merchant: merchantOf(ctx, stored), _coupon: typeof coupon === 'string' ? ctx.get('coupon', coupon) : undefined };
+        return request.method === 'GET' ? page(full, id, Number(ctx.now())) : pay(ctx, id, full, values);
+    };
+}

package/dist/src/screens/consent-skin.d.ts

@@ -0,0 +1,4 @@
+export declare const STRIPE_CONSENT_SKIN = "\nbody { background: #f6f9fc; color: #1a1f36; font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Ubuntu, sans-serif; }\n.consent-badge { background: #ffffff; border: 1px solid #e3e8ee; color: #1a1f36; }\n.consent-vendor { background: #635bff; border-color: #635bff; }\n.consent-link { border-color: #c1c9d2; }\n.consent-box { background: #ffffff; border-color: #e3e8ee; }\n.consent-who small, .consent-permission summary small, .consent-note { color: #697386; }\n.consent-actions { border-color: #e3e8ee; }\n.consent-deny { background: #ffffff; border-color: #c1c9d2; color: #1a1f36; }\n.consent-allow { background: #635bff; border-color: #635bff; color: #ffffff; }\n";
+/** The form fields a page's POST carries, as a browser posts them. */
+export declare function formOf(request: Request): Promise<Record<string, string>>;
+export declare const seeOther: (location: string) => Response;

package/dist/src/screens/consent-skin.js

@@ -0,0 +1,18 @@
+// Stripe's skin over @volter/world-ui's consent piece, for the hosted flows where a person agrees to something
+// (connected-account onboarding, identity verification, linking a bank): Stripe's type and its purple action.
+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) {
+    return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+export const seeOther = (location) => new Response(null, { status: 302, headers: { location } });

package/dist/src/screens/financial-connections.d.ts

@@ -0,0 +1,5 @@
+/** The authentication flow Stripe.js opens, or undefined for any other request. */
+export declare function stripeFinancialConnectionsFlow(scope: {
+    root?: string;
+    clock?: () => string;
+}): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/financial-connections.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// STRIPE FINANCIAL CONNECTIONS — a hosted flow (docs/contributing/architecture.md, "Screens"): an application
+// creates a Financial Connections Session for an account holder and the permissions it wants, and hands its
+// client_secret to Stripe.js, whose authentication flow lets the holder pick their bank and the accounts to share;
+// the linked accounts are then on the session and readable through the Accounts API, with balances and
+// transactions when the permissions asked for them (docs.stripe.com/financial-connections/fundamentals,
+// docs.stripe.com/financial-connections/other-data-powered-products). In test mode the bank is Stripe's test
+// institution (docs.stripe.com/financial-connections/testing). Linking is the holder's move, not an API call.
+// Authored from @volter/world-ui's consent piece under Stripe's skin; nothing of Stripe's page is copied.
+//
+// The flow is opened with the session's client_secret, never its id: the session's own documentation says "The
+// session's client_secret can be used to launch the flow using Stripe.js", and stripe.collectFinancialConnectionsAccounts
+// takes `clientSecret`, "The client_secret of the Financial Connections Session"
+// (docs.stripe.com/js/financial_connections/collect_financial_connections_accounts).
+// Where the documentation stops and the twin decides: the page is served at
+// js.stripe.com/v3/financial-connections/{client_secret}, the twin's address for the "on-page modal UI" Stripe.js
+// loads (the twin's stripe.js navigates there, ../stripe-js.ts); an id or an unknown secret finds no flow;
+// the test institution holds a checking account (•••• 6789) and a savings account (•••• 4321); a linked account's
+// balance and its three transactions are the twin's test data.
+import { semanticsContext } from '@volter/world-core';
+import { Consent, CONSENT_CSS, flowPage } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { created } from "../semantics/shared.js";
+import { formOf, seeOther, STRIPE_CONSENT_SKIN } from "./consent-skin.js";
+const FCS = 'financial_connections.session';
+const FCA = 'financial_connections.account';
+const FCT = 'financial_connections.transaction';
+const OPERATION = surface.operations.find((o) => o.id === 'GetFinancialConnectionsSessionsSession');
+const css = [CONSENT_CSS, STRIPE_CONSENT_SKIN];
+const TEST_ACCOUNTS = [
+    { last4: '6789', subcategory: 'checking', display_name: 'Checking', balance: 125_000 },
+    { last4: '4321', subcategory: 'savings', display_name: 'Savings', balance: 980_000 },
+];
+const message = (status, text) => flowPage({ title: 'Link your account', status, css, body: _jsx("main", { className: "consent", children: _jsx("h1", { className: "consent-heading", children: text }) }) });
+const permissionsOf = (session) => (Array.isArray(session.permissions) ? session.permissions.map(String) : []);
+function page(secret, session) {
+    const says = { balances: 'Account balances', ownership: 'Account ownership details', payment_method: 'Account and routing numbers', transactions: 'Transactions' };
+    return flowPage({
+        title: 'Link your account',
+        css,
+        body: (_jsx(Consent, { heading: "Link your account", app: { name: 'Test Institution' }, request: `Test mode · ${TEST_ACCOUNTS.map((a) => `${a.display_name} •••• ${a.last4}`).join(', ')}`, permissions: permissionsOf(session).map((p) => ({ title: says[p] ?? p, detail: 'Shared with the business through Stripe' })), action: `/v3/financial-connections/${secret}`, fields: {}, deny: { name: 'answer', value: 'cancel', label: 'Cancel' }, allow: { name: 'answer', value: 'link', label: 'Link accounts' }, note: "Stripe will share the data above with the business." })),
+    });
+}
+/** The holder links the test institution's accounts to the session. */
+async function link(ctx, id, session) {
+    const permissions = permissionsOf(session);
+    const now = Number(ctx.now());
+    for (const a of TEST_ACCOUNTS) {
+        const account = await created(ctx, FCA, { session: id }, {
+            livemode: false, status: 'active', account_holder: session.account_holder ?? null, institution_name: 'StripeBank', display_name: a.display_name,
+            last4: a.last4, category: 'cash', subcategory: a.subcategory, supported_payment_method_types: ['us_bank_account', 'link'], permissions,
+            balance: permissions.includes('balances') ? { as_of: now, type: 'cash', cash: { available: { usd: a.balance } }, current: { usd: a.balance } } : null,
+            balance_refresh: permissions.includes('balances') ? { status: 'succeeded', last_attempted_at: now, next_refresh_available_at: null } : null,
+            transaction_refresh: permissions.includes('transactions') ? { id: `fctxnref_${a.last4}`, status: 'succeeded', last_attempted_at: now, next_refresh_available_at: null } : null,
+            ownership: null, ownership_refresh: null, subscriptions: [],
+        });
+        if (!permissions.includes('transactions'))
+            continue;
+        for (const [i, t] of [{ amount: -4_250, description: 'COFFEE ROASTERS' }, { amount: -12_000, description: 'CITY UTILITIES' }, { amount: 250_000, description: 'PAYROLL DEPOSIT' }].entries()) {
+            await created(ctx, FCT, { account: account.id }, {
+                livemode: false, amount: t.amount, currency: 'usd', description: t.description, status: 'posted',
+                status_transitions: { posted_at: now - (3 - i) * 86_400, void_at: null }, transacted_at: now - (3 - i) * 86_400, transaction_refresh: `fctxnref_${a.last4}`, updated: now,
+            });
+        }
+    }
+}
+/** The authentication flow Stripe.js opens, or undefined for any other request. */
+export function stripeFinancialConnectionsFlow(scope) {
+    return async (request) => {
+        const m = /^\/v3\/financial-connections\/([A-Za-z0-9_]+)\/?$/.exec(new URL(request.url).pathname);
+        if (!m || (request.method !== 'GET' && request.method !== 'POST'))
+            return undefined;
+        const secret = m[1];
+        const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+        const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+        const session = ctx.rows(FCS).find((s) => s.client_secret === secret);
+        if (!session)
+            return message(404, 'This link has expired.');
+        const id = String(session.id);
+        if (ctx.rows(FCA).some((a) => a.session === id))
+            return message(200, 'Your accounts are linked.');
+        if (request.method === 'GET')
+            return page(secret, session);
+        if (form.answer === 'link')
+            await link(ctx, id, session);
+        const back = typeof session.return_url === 'string' && session.return_url ? session.return_url : undefined;
+        return back ? seeOther(back) : message(200, form.answer === 'link' ? 'Your accounts are linked.' : 'No accounts were linked.');
+    };
+}

package/dist/src/screens/identity.d.ts

@@ -0,0 +1,5 @@
+/** verify.stripe.com's pages, or undefined for any other request. */
+export declare function stripeIdentityFlow(scope: {
+    root?: string;
+    clock?: () => string;
+}): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/identity.js

@@ -0,0 +1,86 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// STRIPE IDENTITY — a hosted flow (docs/contributing/architecture.md, "Screens"): an application creates a
+// VerificationSession and sends the person to its `url` at verify.stripe.com/start/{session}; they submit their
+// ID there, the session is processing and then verified, with a VerificationReport of what was checked, or it
+// asks for input again with the reason in last_error; the person returns to return_url
+// (docs.stripe.com/identity/how-sessions-work, docs.stripe.com/identity/verification-sessions). In test mode the
+// page offers the outcome instead of a camera (the twin's decision: docs.stripe.com/identity/testing, once cited
+// for it, no longer answers). Submitting is the person's move
+// (the session machine's external actor) and the check Stripe's (its vendor moves). Authored from
+// @volter/world-ui's consent piece under Stripe's skin; nothing of Stripe's page is copied.
+//
+// Where the documentation stops and the twin decides: test mode's person is Jenny Rosen with a driving licence,
+// the name Stripe's test reports carry; a failed check is document_unverified_other.
+import { semanticsContext } from '@volter/world-core';
+import { Consent, CONSENT_CSS, flowPage } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { created } from "../semantics/shared.js";
+import { formOf, seeOther, STRIPE_CONSENT_SKIN } from "./consent-skin.js";
+const VS = 'identity.verification_session';
+const OPERATION = surface.operations.find((o) => o.id === 'GetIdentityVerificationSessionsSession');
+const css = [CONSENT_CSS, STRIPE_CONSENT_SKIN];
+const message = (status, text) => flowPage({ title: 'Stripe Identity', status, css, body: _jsx("main", { className: "consent", children: _jsx("h1", { className: "consent-heading", children: text }) }) });
+function page(id, session) {
+    const kind = session.type === 'id_number' ? 'ID number' : 'Government-issued photo ID';
+    return flowPage({
+        title: 'Verify your identity',
+        css,
+        body: (_jsx(Consent, { heading: "Verify your identity", app: { name: 'Stripe Identity' }, request: "Test mode: choose how the verification ends", permissions: [
+                { title: kind, detail: 'Test data: Jenny Rosen, driving licence' },
+                ...(session.options?.document?.require_matching_selfie === true ? [{ title: 'Selfie', detail: 'Matched to the ID photo' }] : []),
+            ], action: `/start/${id}`, fields: {}, deny: { name: 'outcome', value: 'unverified', label: 'Fail verification' }, allow: { name: 'outcome', value: 'verified', label: 'Verify' }, note: "Stripe uses this data only to verify your identity." })),
+    });
+}
+/** The person submits; Stripe checks and writes the report, and the session is verified or asks again. */
+async function submit(ctx, id, session, verified) {
+    if (ctx.legal(VS, 'status', OPERATION.id, String(session.status), 'processing', id, 'external'))
+        return;
+    // Stripe's check decides the processing session at once: the second move of the one write below
+    ctx.legal(VS, 'status', OPERATION.id, 'processing', verified ? 'verified' : 'requires_input', id, 'vendor');
+    const type = session.type === 'id_number' ? 'id_number' : 'document';
+    const error = verified ? null : { code: 'document_unverified_other', reason: 'The document could not be verified.' };
+    // a document check holds its images: files "Array of File ids containing images for this document" (the served
+    // spec's document report). Where the documentation stops and the twin decides: the licence's front and back, two
+    // identity_document files, as the published report's two
+    const images = [];
+    if (type === 'document')
+        for (const side of ['front', 'back']) {
+            const f = await created(ctx, 'file', { purpose: 'identity_document' }, { filename: `driving_license_${side}.jpg`, size: 0, type: 'jpg', title: null, expires_at: null, url: null, links: { object: 'list', data: [], has_more: false, url: '' } });
+            images.push(String(f.id));
+        }
+    // the report records the options the session was checked with (the session's own, as its object answers them)
+    const sessionOptions = session.options ?? {};
+    const report = await created(ctx, 'identity.verification_report', { verification_session: id, type }, {
+        livemode: false, client_reference_id: session.client_reference_id ?? null,
+        document: type === 'document' ? { status: verified ? 'verified' : 'unverified', type: 'driving_license', first_name: 'Jenny', last_name: 'Rosen', address: null, dob: null, error, files: images } : null,
+        id_number: type === 'id_number' ? { status: verified ? 'verified' : 'unverified', id_number_type: 'us_ssn', first_name: 'Jenny', last_name: 'Rosen', dob: null, error } : null,
+        selfie: null, email: null, phone: null,
+        options: type === 'document' ? { document: sessionOptions.document ?? {} } : { id_number: sessionOptions.id_number ?? {} },
+    });
+    // the url "can only be used once" (the served spec): spent by the submission, as the verification sessions page's
+    // examples answer a verified and a requires_input session with url null
+    await ctx.write(VS, id, verified
+        ? { status: 'verified', last_verification_report: report.id, last_error: null, url: null, client_secret: null, verified_outputs: { first_name: 'Jenny', last_name: 'Rosen' } }
+        : { status: 'requires_input', last_verification_report: report.id, last_error: error, url: null }, verified ? 'verification_session.verified' : 'verification_session.requires_input');
+}
+/** verify.stripe.com's pages, or undefined for any other request. */
+export function stripeIdentityFlow(scope) {
+    return async (request) => {
+        const m = /^\/start\/(vs_[A-Za-z0-9_]+)\/?$/.exec(new URL(request.url).pathname);
+        if (!m || (request.method !== 'GET' && request.method !== 'POST'))
+            return undefined;
+        const id = m[1];
+        const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+        const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+        const session = ctx.get(VS, id);
+        if (!session)
+            return message(404, 'This verification link is invalid.');
+        if (session.status !== 'requires_input')
+            return message(200, session.status === 'verified' ? 'You are verified.' : 'This verification has ended.');
+        if (request.method === 'GET')
+            return page(id, session);
+        await submit(ctx, id, session, form.outcome === 'verified');
+        return typeof session.return_url === 'string' && session.return_url ? seeOther(session.return_url) : message(200, form.outcome === 'verified' ? 'You are verified.' : 'We could not verify your identity.');
+    };
+}

package/dist/src/screens/industries.d.ts

@@ -0,0 +1 @@
+export declare const INDUSTRIES: ReadonlyArray<readonly [mcc: string, name: string]>;