@volter/twin-stripe 0.1.2 → 2.0.1

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,255 @@
+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);
+}
+const EMAIL = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+/** The email of the session's customer when it has a valid one: "If the Customer already has a valid email set, the email
+ *  will be prefilled and not editable in Checkout" (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-customer). */
+function customerEmailOf(session) {
+    const email = session._customer?.email;
+    return typeof email === 'string' && EMAIL.test(email) ? email : undefined;
+}
+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 onFile = customerEmailOf(session);
+    const contact = onFile
+        ? [{ id: 'email', label: 'Email', type: 'email', autoComplete: 'email', value: onFile, readOnly: true }]
+        : 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 onFile = customerEmailOf(session);
+    const email = onFile ?? (typeof session.customer_email === 'string' ? session.customer_email : (v.email ?? '').trim());
+    if (session.mode !== 'setup' || !session.customer) {
+        if (!EMAIL.test(email))
+            return page(session, id, Number(ctx.now()), v, 'Your email address is incomplete.');
+    }
+    // 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 };
+    }
+    // "If the Customer does not have a valid email, Checkout will set the email entered during the session on the Customer" (the same page)
+    if (typeof session.customer === 'string' && !onFile && EMAIL.test(email))
+        await ctx.write('customer', session.customer, { email }, 'customer.update');
+    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, _customer: typeof session.customer === 'string' ? ctx.get('customer', session.customer) : undefined };
+        return request.method === 'GET' ? page(full, id, Number(ctx.now())) : pay(ctx, id, full, values);
+    };
+}

package/dist/src/screens/connect-oauth.d.ts

@@ -0,0 +1,27 @@
+import { type SemanticsContext } from '@volter/world-core';
+/** A code "expires in 5 minutes". */
+export declare const CODE_TTL_SECONDS = 300;
+/** One connection per connected account (the twin's one platform): its scope, tokens, and whether it was revoked. */
+export declare const CONNECTIONS = "_oauth_connection";
+type Scoped = {
+    root?: string;
+    clock?: () => string;
+};
+/** Whether a connected account's OAuth connection to the platform was revoked (deauthorized, or its code reused). */
+export declare function connectionRevoked(ctx: SemanticsContext, account: string): boolean;
+/** The connected account an OAuth key acts as — the connection's current access_token (sk_test_oauth_…) or its
+ *  stripe_publishable_key (pk_test_oauth_…) — with the scope it was issued; undefined for any other key, and null for an
+ *  OAuth-shaped key no live connection holds (revoked, replaced by a refresh, or never issued). */
+export declare function oauthKeyAccount(ctx: SemanticsContext, key: string): {
+    account: string;
+    scope: string;
+} | null | undefined;
+/** The prefill the request carries, invalid values silently dropped (docs.stripe.com/connect/oauth-reference). Only
+ *  what the new account's object shows the platform, or the page shows the person, is read: the person's birth date and
+ *  the business address are the account application's, which the twin does not model (the test-mode skip). */
+export declare function prefill(q: URLSearchParams): Record<string, string>;
+/** A key shown the way Stripe's errors show one: its prefix and its last four. */
+export declare const redactKey: (key: string) => string;
+/** connect.stripe.com's OAuth endpoints, or undefined for any other request. */
+export declare function stripeConnectOAuthFlow(scope: Scoped): (request: Request) => Promise<Response | undefined>;
+export {};