@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/screens/portal.js

@@ -0,0 +1,214 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// STRIPE'S CUSTOMER PORTAL — a hosted flow (docs/contributing/architecture.md, "Screens"): an application creates
+// a portal session for its customer and sends them to the session's `url` at billing.stripe.com/p/session/{id};
+// there the customer sees their plans, payment method, billing details and invoices, and makes the moves the
+// portal configuration allows, then returns to return_url (docs.stripe.com/customer-management). Canceling is the
+// customer's own move (the subscription machine's external actor): at the period's end by default, or at once
+// when the configuration's subscription_cancel.mode says immediately, and a plan set to cancel can be renewed.
+// Each move goes through the same handler context the API's handlers use, so the application sees it as it
+// would from Stripe: on the subscription, and in its events. Authored from @volter/world-ui's portal piece under
+// Stripe's skin; nothing of Stripe's page is copied.
+//
+// The customer also replaces their card, which becomes the default for their invoices and subscriptions, and pays
+// an open invoice with it, which makes a subscription waiting on it (past_due) active again
+// (docs.stripe.com/customer-management/configure-portal: payment_method_update, invoice_history).
+//
+// Where the documentation stops and the twin decides: a session's configuration that the World never created
+// (the account's default) enables cancellation at period end, updating the payment method and invoice history;
+// changing the plan from the portal is not offered yet. A new card is saved without a charge, so a card that
+// declines only when charged (4000000000000341) is saved and declines when the invoice is paid.
+import { semanticsContext } from '@volter/world-core';
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { payerOf, payOpenInvoice } from "../semantics/renewals.js";
+import { created } from "../semantics/shared.js";
+import { publicBusinessName } from "../stripe-shared.js";
+import { declineFor, paymentMethodSubObject, PLATFORM_ACCOUNT_ID } from "../stripe-twin.js";
+import { cardAnswer, COUNTRIES, money } from "./checkout.js";
+import { formOf } from "./consent-skin.js";
+const SUB = 'subscription';
+const PORTAL_OPERATION = surface.operations.find((o) => o.id === 'PostBillingPortalSessions');
+// Stripe's skin: its type, its purple accent, the merchant's side tinted.
+const SKIN = `
+body { color: #1a1a1a; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; }
+.portal-side { background: #f7f7f9; }
+.portal-back { color: #635bff; }
+.portal-section h2 { color: #6b7280; border-color: #e5e7eb; }
+.portal-item { border-bottom: 1px solid #f0f0f3; }
+.portal-detail, .portal-note { color: #6b7280; }
+.portal-badge { background: #eef0f4; color: #414552; }
+.portal-button { border-color: #d5dbe1; color: #1a1a1a; }
+.portal-primary { background: #635bff; border-color: #635bff; color: #ffffff; }
+.portal-danger { color: #df1b41; border-color: #f4c7d0; }
+.portal-empty { color: #6b7280; }
+`;
+const day = (epoch) => new Date(Number(epoch) * 1000).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric', timeZone: 'UTC' });
+const gone = () => flowPage({ title: 'Billing', status: 404, css: [PORTAL_CSS, SKIN], body: _jsx("main", { className: "portal-main", children: _jsx("h1", { children: "This link has expired." }) }) });
+function featuresOf(ctx, session) {
+    const f = (ctx.get('billing_portal.configuration', String(session.configuration))?.features ?? undefined);
+    const cancel = (f?.subscription_cancel ?? {});
+    const invoices = (f?.invoice_history ?? {});
+    const update = (f?.payment_method_update ?? {});
+    return {
+        cancel: { enabled: f ? cancel.enabled === true : true, mode: cancel.mode === 'immediately' ? 'immediately' : 'at_period_end' },
+        invoices: f ? invoices.enabled !== false : true,
+        paymentMethod: f ? update.enabled === true : true,
+    };
+}
+function planOf(ctx, sub) {
+    const item = ((sub.items?.data) ?? [])[0];
+    const price = (typeof item?.price === 'object' ? item.price : ctx.get('price', String(item?.price ?? '')));
+    const product = typeof price?.product === 'string' ? ctx.get('product', price.product) : price?.product;
+    const recurring = price?.recurring;
+    return {
+        name: String(product?.name ?? price?.nickname ?? 'Plan'),
+        price: price ? `${money(price.unit_amount, price.currency)}${recurring?.interval ? ` per ${String(recurring.interval)}` : ''}` : '',
+    };
+}
+function page(ctx, id, session, problem) {
+    const features = featuresOf(ctx, session);
+    const customer = ctx.get('customer', String(session.customer)) ?? {};
+    const subs = ctx.rows(SUB).filter((s) => s.customer === session.customer && s.status !== 'canceled' && s.status !== 'incomplete_expired');
+    const plans = subs.map((s) => {
+        const plan = planOf(ctx, s);
+        const ending = s.cancel_at_period_end === true;
+        return {
+            title: plan.name,
+            detail: plan.price,
+            badge: s.status === 'trialing' ? 'Trial' : s.status === 'past_due' ? 'Past due' : ending ? 'Cancels' : undefined,
+            note: ending ? `Your plan will be canceled on ${day(s.current_period_end)}.` : s.status === 'trialing' ? `Trial ends ${day(s.trial_end)}.` : `Renews on ${day(s.current_period_end)}.`,
+            actions: ending
+                ? [{ label: 'Renew plan', action: `/p/session/${id}/renew`, fields: { subscription: String(s.id) }, tone: 'primary' }]
+                : features.cancel.enabled ? [{ label: 'Cancel plan', action: `/p/session/${id}/cancel`, fields: { subscription: String(s.id) }, tone: 'danger' }] : [],
+        };
+    });
+    const defaultPm = customer.invoice_settings?.default_payment_method ?? undefined;
+    const pms = ctx.rows('payment_method').filter((p) => p.customer === session.customer);
+    const subDefault = subs.map((sub) => payerOf(ctx, sub)).find((p) => typeof p === 'string');
+    const pm = (defaultPm ? pms.find((p) => p.id === defaultPm) : undefined) ?? (subDefault ? pms.find((p) => p.id === subDefault) : undefined) ?? pms[0];
+    const card = pm?.card;
+    const methods = pm ? [{ title: `${String(card?.brand ?? 'card').replace(/^./, (c) => c.toUpperCase())} •••• ${String(card?.last4 ?? '')}`, detail: card ? `Expires ${String(card.exp_month).padStart(2, '0')}/${String(card.exp_year)}` : undefined, badge: 'Default' }] : [];
+    const address = customer.address;
+    const details = [{ title: String(customer.name ?? customer.email ?? ''), detail: String(customer.email ?? ''), ...(address?.country ? { note: [address.line1, address.city, address.postal_code, address.country].filter(Boolean).join(', ') } : {}) }];
+    const invoices = features.invoices
+        ? ctx.rows('invoice').filter((i) => i.customer === session.customer && i.status !== 'draft').sort((a, b) => Number(b.created) - Number(a.created))
+            .map((i) => ({
+            title: day(i.created), detail: money(i.amount_due ?? i.total, i.currency), badge: String(i.status ?? '').replace(/^./, (c) => c.toUpperCase()),
+            ...(i.status === 'open' && i.collection_method !== 'send_invoice' ? { actions: [{ label: 'Pay', action: `/p/session/${id}/pay`, fields: { invoice: String(i.id) }, tone: 'primary' }] } : {}),
+        }))
+        : [];
+    const back = typeof session.return_url === 'string' ? session.return_url : undefined;
+    // the portal shows the public business name (stripe-shared.ts, publicBusinessName) of the session's on_behalf_of
+    // account ("Use the Accounts API to modify the on_behalf_of account's branding settings, which the portal displays",
+    // docs.stripe.com/api/customer_portal/sessions/object), else of the account it was made on (Stripe-Account), else the
+    // platform's
+    const owner = session.on_behalf_of ?? ctx.row('billing_portal.session', String(session.id))?._brand_account;
+    const merchant = publicBusinessName(ctx.get('account', typeof owner === 'string' ? owner : PLATFORM_ACCOUNT_ID));
+    const v = problem?.values ?? {};
+    const cardFields = [
+        { id: 'cardNumber', label: 'Card number', autoComplete: 'cc-number', placeholder: '1234 1234 1234 1234', value: v.cardNumber ?? '' },
+        { id: 'cardExpiry', label: 'Expiration', autoComplete: 'cc-exp', placeholder: 'MM / YY', value: v.cardExpiry ?? '' },
+        { id: 'cardCvc', label: 'CVC', autoComplete: 'cc-csc', placeholder: 'CVC', value: v.cardCvc ?? '' },
+        { id: 'billingName', label: 'Name on card', autoComplete: 'cc-name', value: v.billingName ?? '' },
+        { id: 'billingCountry', label: 'Country or region', options: COUNTRIES, value: v.billingCountry ?? 'US' },
+        { id: 'billingPostalCode', label: 'ZIP', autoComplete: 'postal-code', value: v.billingPostalCode ?? '' },
+    ];
+    return flowPage({
+        title: 'Billing',
+        css: [PORTAL_CSS, SKIN],
+        ...(problem ? { status: 402 } : {}),
+        body: (_jsx(Portal, { merchant: merchant, ...(problem ? { notice: problem.error } : {}), ...(features.paymentMethod ? { forms: [{ heading: pm ? 'Update payment method' : 'Add payment method', action: `/p/session/${id}/payment_method`, fields: cardFields, submit: { label: pm ? 'Update' : 'Add' } }] } : {}), ...(back ? { back: { href: back, label: `← Return to ${merchant}` } } : {}), sections: [
+                { heading: 'Current plan', items: plans, empty: 'You have no active plans.' },
+                { heading: 'Payment method', items: methods, empty: 'No payment method on file.' },
+                { heading: 'Billing information', items: details },
+                ...(features.invoices ? [{ heading: 'Invoice history', items: invoices, empty: 'No invoices yet.' }] : []),
+            ] })),
+    });
+}
+/** The customer's move on one of their subscriptions, then back to the portal. */
+async function move(ctx, id, session, subscription, kind) {
+    const sub = ctx.get(SUB, subscription);
+    if (!sub || sub.customer !== session.customer || sub.status === 'canceled')
+        return gone();
+    const back = new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
+    if (kind === 'renew') {
+        await ctx.write(SUB, subscription, { cancel_at_period_end: false, cancel_at: null, canceled_at: null, cancellation_details: { comment: null, feedback: null, reason: null } }, 'subscription.update');
+        return back;
+    }
+    const features = featuresOf(ctx, session);
+    if (!features.cancel.enabled)
+        return gone();
+    const now = Number(ctx.now());
+    const details = { comment: null, feedback: null, reason: 'cancellation_requested' };
+    if (features.cancel.mode === 'at_period_end') {
+        await ctx.write(SUB, subscription, { cancel_at_period_end: true, cancel_at: sub.current_period_end ?? null, canceled_at: now, cancellation_details: details }, 'subscription.update');
+        return back;
+    }
+    const refused = ctx.legal(SUB, 'status', PORTAL_OPERATION.id, sub.status, 'canceled', subscription, 'external');
+    if (refused)
+        return gone();
+    await ctx.write(SUB, subscription, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details: details }, 'subscription.cancel');
+    return back;
+}
+/** The customer's new card: saved on them (no charge) as the default their invoices and subscriptions charge. */
+async function updatePaymentMethod(ctx, id, session, v) {
+    if (!featuresOf(ctx, session).paymentMethod)
+        return gone();
+    const refused = cardAnswer(v, Number(ctx.now()), false);
+    if (refused)
+        return page(ctx, id, session, { error: refused, values: v });
+    const customer = String(session.customer);
+    const [month, year] = (v.cardExpiry ?? '').split('/').map((x) => Number(x.trim()));
+    const card = { number: (v.cardNumber ?? '').replace(/\D/g, ''), exp_month: month ?? 12, exp_year: (year ?? 0) < 100 ? 2000 + (year ?? 0) : (year ?? 0) };
+    const pm = await created(ctx, 'payment_method', {}, {
+        type: 'card', customer, livemode: false,
+        billing_details: { address: { country: v.billingCountry || null, postal_code: v.billingPostalCode || null, city: null, line1: null, line2: null, state: null }, email: null, name: v.billingName || null, phone: null },
+        ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null,
+    });
+    const holder = ctx.get('customer', customer) ?? {};
+    await ctx.write('customer', customer, { invoice_settings: { ...(holder.invoice_settings ?? {}), default_payment_method: pm.id } }, 'customer.update');
+    for (const sub of ctx.rows(SUB).filter((s) => s.customer === customer && s.status !== 'canceled' && s.status !== 'incomplete_expired')) {
+        await ctx.write(SUB, String(sub.id), { default_payment_method: pm.id }, 'subscription.update');
+    }
+    return new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
+}
+/** The customer pays one of their open invoices with the card on file. */
+async function payInvoice(ctx, id, session, invoiceId) {
+    const inv = ctx.get('invoice', invoiceId);
+    if (!inv || inv.customer !== session.customer || inv.status !== 'open')
+        return gone();
+    const sub = typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
+    const holder = ctx.get('customer', String(session.customer)) ?? {};
+    const pm = (sub ? payerOf(ctx, sub) : undefined) ?? holder.invoice_settings?.default_payment_method;
+    if (!pm)
+        return page(ctx, id, session, { error: 'Add a payment method to pay this invoice.', values: {} });
+    const declined = await payOpenInvoice(ctx, invoiceId, pm);
+    if (declined)
+        return page(ctx, id, session, { error: declined.message, values: {} });
+    return new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
+}
+/** billing.stripe.com's portal pages, or undefined for any other request. */
+export function stripePortalFlow(scope) {
+    return async (request) => {
+        const m = /^\/p\/session\/(bps_[A-Za-z0-9_]+)(?:\/(cancel|renew|payment_method|pay))?\/?$/.exec(new URL(request.url).pathname);
+        if (!m)
+            return undefined;
+        const [, id, kind] = m;
+        if ((kind && request.method !== 'POST') || (!kind && request.method !== 'GET'))
+            return undefined;
+        // the form is read before the context, which reads the request's body itself
+        const form = kind ? await formOf(request.clone()) : {};
+        const ctx = await semanticsContext(manifest, request, PORTAL_OPERATION, scope);
+        const session = ctx.get('billing_portal.session', id);
+        if (!session)
+            return gone();
+        if (!kind)
+            return page(ctx, id, session);
+        if (kind === 'payment_method')
+            return updatePaymentMethod(ctx, id, session, form);
+        if (kind === 'pay')
+            return payInvoice(ctx, id, session, form.invoice ?? '');
+        return move(ctx, id, session, form.subscription ?? '', kind);
+    };
+}

package/dist/src/screens/public-details.d.ts

@@ -0,0 +1,5 @@
+export declare const PUBLIC_DETAILS_PATH = "/settings/public";
+export declare function stripePublicDetailsFlow(scope: {
+    root?: string;
+    clock?: () => string;
+}): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/public-details.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// THE DASHBOARD'S PUBLIC DETAILS — a workspace page (docs/contributing/architecture.md, "Screens") of the Dashboard
+// (manifest screen `dashboard`), at dashboard.stripe.com/settings/public: Settings → Business → Public details, where
+// the operator sets what their customers see ("Public Details → Business Settings",
+// support.stripe.com/questions/update-account-name-shown-in-the-dashboard). Its business name is the account's
+// `business_profile.name`, "The customer-facing business name" (docs.stripe.com/api/accounts/object), and it is the
+// name Checkout shows: "You can change a Checkout page's name by modifying the Business name field"
+// (docs.stripe.com/payments/checkout/customization/appearance). Stripe's API has no call that changes the platform's
+// own account (POST /v1/accounts/{account} updates a connected one), so this page is the only way to the act, and
+// saving it writes the platform account's stored record (semantics/connect.ts `platform`), which GET /v1/account,
+// Checkout and the customer portal then read. The Dashboard's account name (`settings.dashboard.display_name`,
+// Settings → Account) is a separate, internal setting, "for internal use only" (the same support article), and this
+// page does not touch it. Authored from plain markup under Stripe's type; nothing of Stripe's page is copied.
+//
+// Where the documentation stops and the twin decides: the page holds the business name only (the real page's
+// support details, website and statement descriptor are not modelled here); the name is required and at most 5000
+// characters (the spec's bound on business_profile.name), which the browser holds the field to and the page checks
+// again for a client that is not a browser; no sign-in guards the page, as none guards the Dashboard mirror. The page
+// is matched by its path on whatever host reaches the twin (the World routes only dashboard.stripe.com's
+// /settings/public here; the local mirror serves it on its own origin), and the form posts to the page's own address
+// and the save redirects to its own path, so it also works under the hosted mirror's path prefix. Saving is an update of an account that exists (the first save included, though
+// the twin stores the platform's record only then), so every save is sent as account.updated.
+import { semanticsContext } from '@volter/world-core';
+import { flowPage } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { platformAccountDefault } from "../semantics/connect.js";
+import { created } from "../semantics/shared.js";
+import { publicBusinessName } from "../stripe-shared.js";
+import { PLATFORM_ACCOUNT_ID } from "../stripe-twin.js";
+import { formOf } from "./consent-skin.js";
+export const PUBLIC_DETAILS_PATH = '/settings/public';
+const MAX_NAME = 5000;
+const OPERATION = surface.operations.find((o) => o.id === 'PostAccountsAccount');
+const CSS = `
+* { box-sizing: border-box; }
+body { margin: 0; background: #f6f8fa; color: #1a1f36; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; font-size: 14px; }
+.pd { max-width: 640px; margin: 48px auto; padding: 0 16px; }
+.pd h1 { font-size: 28px; margin: 16px 0 4px; }
+.pd-lead { color: #697386; margin: 0 0 24px; }
+.pd-card { background: #ffffff; border: 1px solid #e3e8ee; border-radius: 8px; padding: 24px; }
+.pd-card label { display: block; font-weight: 600; margin-bottom: 6px; }
+.pd-card small { display: block; color: #697386; margin-bottom: 8px; }
+.pd-card input { width: 100%; padding: 8px 10px; border: 1px solid #c1c9d2; border-radius: 6px; font: inherit; }
+.pd-actions { margin-top: 20px; display: flex; justify-content: flex-end; }
+.pd-actions button { background: #635bff; color: #ffffff; border: 0; border-radius: 6px; padding: 8px 16px; font: inherit; font-weight: 600; cursor: pointer; }
+.pd-notice { padding: 10px 12px; border-radius: 6px; margin-bottom: 16px; }
+.pd-error { background: #fff0f3; color: #df1b41; }
+.pd-saved { background: #e7f8ef; color: #0e6245; }
+`;
+function page(account, opts = {}) {
+    const named = account?.business_profile?.name;
+    const value = opts.value ?? (typeof named === 'string' ? named : '');
+    return flowPage({
+        title: 'Public details – Stripe',
+        css: [CSS],
+        ...(opts.error ? { status: 400 } : {}),
+        body: (_jsxs("main", { className: "pd", children: [_jsx("h1", { children: "Public details" }), _jsxs("p", { className: "pd-lead", children: ["What your customers see on Checkout, the customer portal, receipts and invoices. Currently shown: ", _jsx("strong", { "data-testid": "public-business-name", children: publicBusinessName(account) })] }), opts.error ? _jsx("p", { className: "pd-notice pd-error", role: "alert", children: opts.error }) : null, opts.saved ? _jsx("p", { className: "pd-notice pd-saved", role: "status", children: "Your public details were saved." }) : null, _jsxs("form", { className: "pd-card", method: "post", children: [_jsx("label", { htmlFor: "business_name", children: "Business name" }), _jsx("small", { children: "The name customers see when they pay you." }), _jsx("input", { id: "business_name", name: "business_name", autoComplete: "organization", defaultValue: value, required: true, maxLength: MAX_NAME }), _jsx("div", { className: "pd-actions", children: _jsx("button", { type: "submit", children: "Save" }) })] })] })),
+    });
+}
+/** 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, name) {
+    const held = ctx.get('account', PLATFORM_ACCOUNT_ID);
+    const profile = { business_profile: { ...((held ?? platformAccountDefault()).business_profile ?? {}), 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) {
+    return !name ? 'Enter your business name.' : name.length > MAX_NAME ? `Your business name must be at most ${MAX_NAME} characters.` : undefined;
+}
+export function stripePublicDetailsFlow(scope) {
+    return async (request) => {
+        const url = new URL(request.url);
+        if (url.pathname.replace(/\/+$/, '') !== PUBLIC_DETAILS_PATH || (request.method !== 'GET' && request.method !== 'POST'))
+            return undefined;
+        // the form is read before the context, which reads the request's body itself
+        const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+        const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+        if (request.method === 'GET')
+            return page(ctx.get('account', PLATFORM_ACCOUNT_ID), { saved: url.searchParams.has('saved') });
+        const name = (form.business_name ?? '').trim();
+        const refused = nameRefused(name);
+        if (refused)
+            return page(ctx.get('account', PLATFORM_ACCOUNT_ID), { value: form.business_name ?? '', error: refused });
+        await save(ctx, name);
+        // a query-only reference: the page's own path, wherever it is mounted and with or without its trailing slash
+        return new Response(null, { status: 303, headers: { location: '?saved=1' } });
+    };
+}

package/dist/src/semantics/after-payment.d.ts

@@ -0,0 +1,22 @@
+import type { SemanticsContext } from '@volter/world-core';
+type Outcome = 'dispute' | 'dispute_not_received' | 'inquiry' | 'review';
+/** The test cards whose success Stripe follows with its own act, by number and by their documented test names. */
+export declare const AFTER_SUCCESS_CARDS: Record<string, {
+    brand: string;
+    number: string;
+    outcome: Outcome;
+}>;
+/** What Stripe does after a card succeeds: from a raw number, a test name (pm_card_* or tok_*), or a stored
+ *  PaymentMethod that recorded it when it was made. */
+export declare function afterSuccessOf(ctx: SemanticsContext, ref: unknown): Outcome | undefined;
+/** Stripe's acts on a charge that just succeeded: a dispute or a review its card brings, and the platform's fee. */
+export declare function afterCharge(ctx: SemanticsContext, chargeId: string, charge: {
+    amount: number;
+    currency: string;
+    payment_intent?: string | undefined;
+    application_fee_amount?: unknown;
+    destination?: unknown;
+}, ref: unknown): Promise<void>;
+/** The mandate a verified bank account carries for a payment (single use) or a setup (multi use). */
+export declare function mintMandate(ctx: SemanticsContext, paymentMethod: unknown, use: 'single_use' | 'multi_use', amount?: number, currency?: string): Promise<string>;
+export {};

package/dist/src/semantics/after-payment.js

@@ -0,0 +1,93 @@
+import { disputeEvidence } from "../stripe-twin.js";
+import { actingAccount, settleApplicationFee, settleDispute, settleTransfer } from "./ledger.js";
+import { created } from "./shared.js";
+const DAY = 86_400;
+/** The test cards whose success Stripe follows with its own act, by number and by their documented test names. */
+export const AFTER_SUCCESS_CARDS = {
+    pm_card_createDispute: { brand: 'visa', number: '4000000000000259', outcome: 'dispute' },
+    pm_card_createDisputeProductNotReceived: { brand: 'visa', number: '4000000000002685', outcome: 'dispute_not_received' },
+    pm_card_createDisputeInquiry: { brand: 'visa', number: '4000000000001976', outcome: 'inquiry' },
+    pm_card_riskLevelElevated: { brand: 'visa', number: '4000000000009235', outcome: 'review' },
+};
+const BY_NUMBER = Object.fromEntries(Object.values(AFTER_SUCCESS_CARDS).map((c) => [c.number, c.outcome]));
+/** What Stripe does after a card succeeds: from a raw number, a test name (pm_card_* or tok_*), or a stored
+ *  PaymentMethod that recorded it when it was made. */
+export function afterSuccessOf(ctx, ref) {
+    if (ref && typeof ref === 'object')
+        return BY_NUMBER[String(ref.number ?? '').replace(/\D/g, '')];
+    if (typeof ref !== 'string' || !ref)
+        return undefined;
+    const stored = ctx.row('payment_method', ref);
+    if (stored)
+        return stored._afterSuccess ?? undefined;
+    return AFTER_SUCCESS_CARDS[ref.replace(/^tok_/, 'pm_card_')]?.outcome ?? BY_NUMBER[ref.replace(/\D/g, '')];
+}
+/** Stripe's acts on a charge that just succeeded: a dispute or a review its card brings, and the platform's fee. */
+export async function afterCharge(ctx, chargeId, charge, ref) {
+    const outcome = afterSuccessOf(ctx, ref);
+    const pi = charge.payment_intent ? { payment_intent: charge.payment_intent } : { payment_intent: null };
+    const now = Number(ctx.now());
+    if (outcome === 'dispute' || outcome === 'dispute_not_received' || outcome === 'inquiry') {
+        const dispute = await created(ctx, 'dispute', { charge: chargeId, ...pi, amount: charge.amount, currency: charge.currency }, {
+            reason: outcome === 'dispute_not_received' ? 'product_not_received' : 'fraudulent', status: outcome === 'inquiry' ? 'warning_needs_response' : 'needs_response', is_charge_refundable: false,
+            evidence: disputeEvidence(), evidence_details: { due_by: now + 7 * DAY, has_evidence: false, past_due: false, submission_count: 0, enhanced_eligibility: {} },
+            balance_transactions: [], livemode: false, metadata: {}, enhanced_eligibility_types: [],
+        });
+        // an inquiry moves no money; a dispute takes the amount and its fee until it is decided
+        if (outcome !== 'inquiry') {
+            const bt = await settleDispute(ctx, String(dispute.id), charge.amount, charge.currency);
+            await ctx.write('dispute', String(dispute.id), { balance_transactions: [ctx.get('balance_transaction', bt) ?? bt] }, 'dispute.funds_withdrawn');
+        }
+        await ctx.write('charge', chargeId, { disputed: true }, 'charge.dispute.created');
+    }
+    if (outcome === 'review')
+        await openReview(ctx, chargeId, pi);
+    const feeAmount = Math.trunc(Number(charge.application_fee_amount) || 0);
+    const destination = typeof charge.destination === 'string' && charge.destination ? charge.destination : undefined;
+    const direct = actingAccount(ctx);
+    const account = destination ?? direct;
+    // a destination charge transfers what it collected, less the platform's fee, available when the charge's funds are
+    if (destination) {
+        const amount = charge.amount - feeAmount;
+        const chargeBt = ctx.get('charge', chargeId)?.balance_transaction;
+        const availableOn = Number(ctx.get('balance_transaction', String(chargeBt))?.available_on ?? ctx.now());
+        const tr = await created(ctx, 'transfer', { amount, currency: charge.currency, destination }, {
+            amount_reversed: 0, balance_transaction: null, livemode: false, metadata: {}, reversed: false, source_type: 'card', source_transaction: chargeId,
+            reversals: { object: 'list', data: [], has_more: false, total_count: 0, url: '' },
+        });
+        const bt = await settleTransfer(ctx, String(tr.id), amount, charge.currency, destination, availableOn);
+        await ctx.write('transfer', String(tr.id), { balance_transaction: bt, destination_payment: `py_${String(tr.id).replace(/^tr_/, '')}`, reversals: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/transfers/${String(tr.id)}/reversals` } }, 'transfer.created');
+        await ctx.write('charge', chargeId, { transfer: tr.id }, 'charge.updated');
+    }
+    if (feeAmount > 0 && account) {
+        const fee = await created(ctx, 'application_fee', { account, amount: feeAmount, charge: chargeId, currency: charge.currency }, {
+            amount_refunded: 0, application: 'ca_twin', balance_transaction: null, originating_transaction: null, refunded: false, livemode: false,
+        });
+        // a direct charge's fee moves from the connected account to the platform (a destination charge kept it back)
+        const bt = !destination && direct ? await settleApplicationFee(ctx, String(fee.id), feeAmount, charge.currency, direct) : null;
+        await ctx.write('application_fee', String(fee.id), { balance_transaction: bt, refunds: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/application_fees/${String(fee.id)}/refunds` } }, 'application_fee.created');
+        await ctx.write('charge', chargeId, { application_fee: fee.id, application_fee_amount: feeAmount }, 'charge.updated');
+    }
+}
+/** Radar places an elevated-risk card's charge in review (docs.stripe.com/radar/reviews). */
+async function openReview(ctx, chargeId, pi) {
+    const review = await created(ctx, 'review', { charge: chargeId, ...pi }, {
+        open: true, opened_reason: 'rule', reason: 'rule', closed_reason: null, billing_zip: null, ip_address: null, ip_address_location: null, session: null, livemode: false,
+    });
+    const existing = ctx.get('charge', chargeId)?.outcome ?? {};
+    await ctx.write('charge', chargeId, {
+        review: review.id,
+        outcome: { ...existing, type: 'manual_review', risk_level: 'elevated', risk_score: 67, seller_message: 'Stripe evaluated this payment as having elevated risk, and placed it in review.' },
+    }, 'review.opened');
+}
+/** The mandate a verified bank account carries for a payment (single use) or a setup (multi use). */
+export async function mintMandate(ctx, paymentMethod, use, amount, currency) {
+    const now = Number(ctx.now());
+    const mandate = await created(ctx, 'mandate', { payment_method: typeof paymentMethod === 'string' ? paymentMethod : null }, {
+        status: 'active', type: use, livemode: false,
+        customer_acceptance: { type: 'online', accepted_at: now, online: { ip_address: '127.0.0.1', user_agent: 'twin' } },
+        payment_method_details: { type: 'us_bank_account', us_bank_account: { collection_method: 'paper' } },
+        ...(use === 'single_use' ? { single_use: { amount: amount ?? 0, currency: currency ?? 'usd' } } : { multi_use: {} }),
+    }, { timeField: '_created' });
+    return String(mandate.id);
+}

package/dist/src/semantics/apps-secrets.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const appsSecrets: Record<string, Semantics>;

package/dist/src/semantics/apps-secrets.js

@@ -0,0 +1,54 @@
+import { created, fail, list, newest, kept } from "./shared.js";
+const SECRET = 'apps.secret';
+function scopeKeyOf(ctx) {
+    const scope = ctx.params.scope && typeof ctx.params.scope === 'object' ? ctx.params.scope : undefined;
+    const scopeType = scope && typeof scope.type === 'string' ? scope.type : 'account';
+    return scopeType === 'user' ? `user:${String(scope.user)}` : 'account';
+}
+const named = (ctx, name) => ctx.rows(SECRET).find((s) => s.name === name && kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx));
+const set = async (ctx) => {
+    const params = ctx.params;
+    const name = typeof params.name === 'string' ? params.name : '';
+    if (!name)
+        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+    const scope = params.scope && typeof params.scope === 'object' ? params.scope : undefined;
+    const scopeType = scope && typeof scope.type === 'string' ? scope.type : '';
+    if (scopeType !== 'account' && scopeType !== 'user')
+        return fail(ctx, 'Invalid scope[type]: must be account or user.', 400, 'parameter_invalid_string_enum');
+    if (scopeType === 'user' && typeof scope.user !== 'string')
+        return fail(ctx, 'Missing required param: scope[user].', 400, 'parameter_missing');
+    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'));
+    return ctx.reply(await created(ctx, SECRET, { name }, {
+        livemode: false, deleted: false, expires_at: expiresAt, payload: params.payload,
+        scope: scopeType === 'user' ? { type: 'user', user: scope.user } : { type: 'account' },
+        _scope_key: scopeKeyOf(ctx),
+    }));
+};
+const find = 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 = 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);
+    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 = async (ctx) => list(ctx, SECRET, newest(ctx, SECRET).filter((s) => kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx)));
+export const appsSecrets = {
+    PostAppsSecrets: set,
+    GetAppsSecretsFind: find,
+    PostAppsSecretsDelete: remove,
+    GetAppsSecrets: listSecrets,
+};

package/dist/src/semantics/balance.d.ts

@@ -0,0 +1,11 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** The acting account's Balance object (docs.stripe.com/api/balance/balance_object). */
+export declare function balanceBody(ctx: SemanticsContext): Row;
+/** Time's arrivals, written: each of the acting account's payouts whose arrival date has come moves pending → paid
+ *  (the clock's move, as asOf reads it), written as `payout.paid`, the event Stripe sends for it. Answers their ids. */
+export declare function payDuePayouts(ctx: SemanticsContext): Promise<string[]>;
+/** Time's payouts, caught up to the World's clock: each account on an automatic schedule is paid out, on each of its
+ *  scheduled days that has come, what became available by then. */
+export declare function advancePayouts(ctx: SemanticsContext): Promise<void>;
+export declare const balances: Record<string, Semantics>;