@volter/twin-stripe 0.1.2 → 2.0.0

package/src/screens/portal.tsx

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

package/src/screens/public-details.tsx

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

package/src/semantics/after-payment.ts

@@ -0,0 +1,113 @@
+// What Stripe does itself once a payment succeeds, which no API call asks for:
+// - a test card that is disputed opens a dispute on its charge (docs.stripe.com/testing#disputes: 4000000000000259
+//   "charge succeeds, then disputed as fraudulent", 4000000000002685 disputed as product not received,
+//   4000000000001976 an inquiry), and Stripe debits the disputed
+//   amount and its dispute fee from the balance (docs.stripe.com/disputes/how-disputes-work);
+// - a test card Radar scores as elevated risk opens a review of its charge (docs.stripe.com/testing#fraud-prevention:
+//   4000000000009235, "elevated risk", which Radar places in review; docs.stripe.com/radar/reviews);
+// - a charge a platform makes with `application_fee_amount` earns the platform an application fee, from the connected
+//   account it pays (a destination charge's `transfer_data.destination`, or the account a direct charge is made on;
+//   docs.stripe.com/connect/destination-charges, docs.stripe.com/connect/direct-charges);
+// - a bank account verified by micro-deposits for a payment or a setup carries a mandate, the customer's acceptance
+//   of debits (docs.stripe.com/payments/ach-direct-debit/accept-a-payment, docs.stripe.com/api/mandates).
+//
+// Where the documentation stops and the twin decides: evidence is due seven days after a dispute opens (Stripe's
+// deadline depends on the card network); the dispute fee is 1500 cents in any currency (Stripe's US fee is $15); an
+// elevated-risk review's risk score is 67 (Radar's elevated band); the application is `ca_twin`.
+import type { SemanticsContext } from '@volter/world-core';
+import { disputeEvidence } from '../stripe-twin.ts';
+import { actingAccount, settleApplicationFee, settleDispute, settleTransfer } from './ledger.ts';
+import { created, type Row } from './shared.ts';
+
+type Outcome = 'dispute' | 'dispute_not_received' | 'inquiry' | 'review';
+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: Record<string, { brand: string; number: string; outcome: Outcome }> = {
+  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: Record<string, Outcome> = 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: SemanticsContext, ref: unknown): Outcome | undefined {
+  if (ref && typeof ref === 'object') return BY_NUMBER[String((ref as Row).number ?? '').replace(/\D/g, '')];
+  if (typeof ref !== 'string' || !ref) return undefined;
+  const stored = ctx.row('payment_method', ref);
+  if (stored) return (stored._afterSuccess as Outcome | undefined) ?? 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: SemanticsContext, chargeId: string, charge: { amount: number; currency: string; payment_intent?: string | undefined; application_fee_amount?: unknown; destination?: unknown }, ref: unknown): Promise<void> {
+  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: SemanticsContext, chargeId: string, pi: { payment_intent: string | null }): Promise<void> {
+  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 as Row | undefined) ?? {};
+  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: SemanticsContext, paymentMethod: unknown, use: 'single_use' | 'multi_use', amount?: number, currency?: string): Promise<string> {
+  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/src/semantics/apps-secrets.ts

@@ -0,0 +1,58 @@
+// Apps secret-store semantics: a secret is named within a scope (the account, or one user); setting
+// the same name in the same scope overwrites it. The scope is kept as a bookkeeping key.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { created, fail, list, newest, type Row, kept } from './shared.ts';
+
+const SECRET = 'apps.secret';
+
+function scopeKeyOf(ctx: SemanticsContext): string {
+  const scope = ctx.params.scope && typeof ctx.params.scope === 'object' ? (ctx.params.scope as Row) : undefined;
+  const scopeType = scope && typeof scope.type === 'string' ? scope.type : 'account';
+  return scopeType === 'user' ? `user:${String(scope!.user)}` : 'account';
+}
+const named = (ctx: SemanticsContext, name: string): Row | undefined => ctx.rows(SECRET).find((s) => s.name === name && kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx));
+
+const set: Semantics = async (ctx) => {
+  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 as Row) : 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: Semantics = async (ctx) => {
+  const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
+  if (!name) return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+  const s = named(ctx, name);
+  return s ? ctx.reply(s) : fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
+};
+
+const remove: Semantics = async (ctx) => {
+  const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
+  if (!name) return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+  const s = named(ctx, name);
+  if (!s) return fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
+  return ctx.reply(await ctx.write(SECRET, String(s.id), { deleted: true }, 'apps_secret.delete'));
+};
+
+const listSecrets: Semantics = async (ctx) => list(ctx, SECRET, newest(ctx, SECRET).filter((s) => kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx)));
+
+export const appsSecrets: Record<string, Semantics> = {
+  PostAppsSecrets: set,
+  GetAppsSecretsFind: find,
+  PostAppsSecretsDelete: remove,
+  GetAppsSecrets: listSecrets,
+};