@volter/twin-stripe 2.0.0 → 2.0.2

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

@@ -0,0 +1,22 @@
+import { type SemanticsContext } from '@volter/world-core';
+/** The platform's test client_id: the World's one platform (acct_twin_self) is the application it names. */
+export declare const PLATFORM_CLIENT_ID = "ca_twin_self";
+export declare const SETTINGS_URL = "https://dashboard.stripe.com/settings/connect/onboarding-options/oauth";
+/** The page's addresses: the docs' own, its test-mode link, and Connect's settings root. */
+export declare const CONNECT_SETTINGS_PATH: RegExp;
+export type ConnectOAuthSettings = {
+    oauth_enabled: boolean;
+    redirect_uris: string[];
+};
+/** What the platform saved, or the settings a new platform starts with (OAuth off, no redirect URI). */
+export declare function connectOAuthSettings(ctx: SemanticsContext): ConnectOAuthSettings;
+/** The redirect URIs a form's field names, or the first one refused and why. */
+export declare function redirectUris(field: string): {
+    uris: string[];
+} | {
+    refused: string;
+};
+export declare function stripeConnectSettingsFlow(scope: {
+    root?: string;
+    clock?: () => string;
+}): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/connect-settings.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// THE DASHBOARD'S CONNECT OAUTH SETTINGS — a workspace page (docs/contributing/architecture.md, "Screens") of the
+// Dashboard (manifest screen `dashboard`), at dashboard.stripe.com/settings/connect/onboarding-options/oauth, where a
+// platform starts an OAuth integration: "Enable onboarding accounts with OAuth", "Copy your client_id, a unique
+// identifier for your platform that's generated by Stripe", and "Set your redirect_uri ... You must specify all redirect
+// URLs in your platform settings. If you don't include the redirect_uri parameter in your request, Stripe defaults to
+// using the first address you've configured" (docs.stripe.com/connect/oauth-standard-accounts). The test client_id
+// "allows you to: Set your redirect_uri to a non-HTTPS URL; Set your redirect_uri to localhost"
+// (docs.stripe.com/connect/testing#using-oauth). Stripe's API has no call that reads or changes these settings (GET
+// /v1/account does not carry the client_id), so this page is the only way to them, and connect.stripe.com/oauth/authorize
+// (./connect-oauth.tsx) reads what it saves. Authored from plain markup under Stripe's type; nothing of Stripe's page is
+// copied.
+//
+// Where the documentation stops and the twin decides: the World has one platform, and its test client_id is
+// `ca_twin_self` (PLATFORM_CLIENT_ID; the platform account is acct_twin_self), the same in every World, shown on the
+// page in an element a runner reads (data-testid="connect-client-id"). OAuth starts disabled. The page is served at
+// the docs' address, at /test/… (the docs' test-mode link) and at /settings/connect (the address Cal.com's setup
+// guide gives). The redirect URIs are one form field, one per line (or comma-separated, as the reference describes
+// them), saved whole: each an absolute http or https URL without a fragment; http and localhost are allowed, as the
+// test client_id allows them. No sign-in guards the page, as none guards the Dashboard mirror. The form posts to the
+// page's own address and the save redirects to it.
+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 { formOf } from "./consent-skin.js";
+/** The platform's test client_id: the World's one platform (acct_twin_self) is the application it names. */
+export const PLATFORM_CLIENT_ID = 'ca_twin_self';
+export const SETTINGS_URL = 'https://dashboard.stripe.com/settings/connect/onboarding-options/oauth';
+/** The page's addresses: the docs' own, its test-mode link, and Connect's settings root. */
+export const CONNECT_SETTINGS_PATH = /^\/(test\/)?settings\/connect(\/onboarding-options\/oauth)?\/?$/;
+const SETTINGS = '_connect_oauth_settings';
+const OPERATION = surface.operations.find((o) => o.id === 'PostAccountsAccount');
+/** What the platform saved, or the settings a new platform starts with (OAuth off, no redirect URI). */
+export function connectOAuthSettings(ctx) {
+    const row = ctx.rowsRaw(SETTINGS).find((r) => r.id === PLATFORM_CLIENT_ID);
+    return { oauth_enabled: row?.oauth_enabled === true, redirect_uris: Array.isArray(row?.redirect_uris) ? row.redirect_uris : [] };
+}
+/** The redirect URIs a form's field names, or the first one refused and why. */
+export function redirectUris(field) {
+    const uris = [...new Set(field.split(/[\n,]/).map((s) => s.trim()).filter(Boolean))];
+    for (const uri of uris) {
+        let url;
+        try {
+            url = new URL(uri);
+        }
+        catch {
+            return { refused: `${uri} is not a valid URL.` };
+        }
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return { refused: `${uri} must use http or https.` };
+        if (uri.includes('#'))
+            return { refused: `${uri} must not contain a fragment.` };
+    }
+    return { uris };
+}
+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; }
+.co { max-width: 680px; margin: 48px auto; padding: 0 16px; }
+.co h1 { font-size: 28px; margin: 16px 0 4px; }
+.co-lead { color: #697386; margin: 0 0 24px; }
+.co-card { background: #ffffff; border: 1px solid #e3e8ee; border-radius: 8px; padding: 24px; margin-bottom: 16px; }
+.co-card h2 { font-size: 16px; margin: 0 0 12px; }
+.co-card label { display: block; font-weight: 600; margin-bottom: 6px; }
+.co-card small { display: block; color: #697386; margin-bottom: 8px; }
+.co-card textarea { width: 100%; min-height: 96px; padding: 8px 10px; border: 1px solid #c1c9d2; border-radius: 6px; font: 13px ui-monospace, Menlo, monospace; }
+.co-id { font: 14px ui-monospace, Menlo, monospace; background: #f6f8fa; border: 1px solid #e3e8ee; border-radius: 6px; padding: 6px 10px; display: inline-block; }
+.co-toggle { display: flex; gap: 8px; align-items: center; font-weight: 600; }
+.co-actions { display: flex; justify-content: flex-end; }
+.co-actions button { background: #635bff; color: #ffffff; border: 0; border-radius: 6px; padding: 8px 16px; font: inherit; font-weight: 600; cursor: pointer; }
+.co-notice { padding: 10px 12px; border-radius: 6px; margin-bottom: 16px; }
+.co-error { background: #fff0f3; color: #df1b41; }
+.co-saved { background: #e7f8ef; color: #0e6245; }
+.co-uris { margin: 0; padding-left: 18px; }
+`;
+function page(s, opts = {}) {
+    const enabled = opts.enabled ?? s.oauth_enabled;
+    return flowPage({
+        title: 'OAuth – Connect settings – Stripe',
+        css: [CSS],
+        ...(opts.error ? { status: 400 } : {}),
+        body: (_jsxs("main", { className: "co", children: [_jsx("h1", { children: "OAuth" }), _jsx("p", { className: "co-lead", children: "Onboard Standard accounts by sending them to Stripe's OAuth flow. Test mode." }), opts.error ? _jsx("p", { className: "co-notice co-error", role: "alert", children: opts.error }) : null, opts.saved ? _jsx("p", { className: "co-notice co-saved", role: "status", children: "Your OAuth settings were saved." }) : null, _jsxs("section", { className: "co-card", children: [_jsx("h2", { children: "Test mode client ID" }), _jsx("small", { children: "The client_id your platform sends to connect.stripe.com/oauth/authorize." }), _jsx("code", { className: "co-id", "data-testid": "connect-client-id", children: PLATFORM_CLIENT_ID }), _jsx("p", { "data-testid": "connect-oauth-status", children: s.oauth_enabled ? 'OAuth is enabled.' : 'OAuth is disabled.' }), s.redirect_uris.length ? _jsx("ul", { className: "co-uris", children: s.redirect_uris.map((u) => _jsx("li", { "data-testid": "connect-redirect-uri", children: u }, u)) }) : _jsx("p", { children: "No redirect URIs." })] }), _jsxs("form", { className: "co-card", method: "post", children: [_jsxs("label", { className: "co-toggle", htmlFor: "oauth_enabled", children: [_jsx("input", { type: "checkbox", id: "oauth_enabled", name: "oauth_enabled", value: "on", defaultChecked: enabled }), " Enable OAuth for Standard accounts"] }), _jsx("label", { htmlFor: "redirect_uris", children: "Redirect URIs" }), _jsx("small", { children: "One per line. The first is used when a request names none. http and localhost are allowed in test mode." }), _jsx("textarea", { id: "redirect_uris", name: "redirect_uris", defaultValue: opts.value ?? s.redirect_uris.join('\n') }), _jsx("div", { className: "co-actions", children: _jsx("button", { type: "submit", children: "Save" }) })] })] })),
+    });
+}
+export function stripeConnectSettingsFlow(scope) {
+    return async (request) => {
+        const url = new URL(request.url);
+        if (!CONNECT_SETTINGS_PATH.test(url.pathname) || (request.method !== 'GET' && request.method !== 'POST'))
+            return undefined;
+        const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+        const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+        const held = connectOAuthSettings(ctx);
+        if (request.method === 'GET')
+            return page(held, { saved: url.searchParams.has('saved') });
+        const enabled = form.oauth_enabled === 'on' || form.oauth_enabled === 'true';
+        const parsed = redirectUris(form.redirect_uris ?? '');
+        if ('refused' in parsed)
+            return page(held, { value: form.redirect_uris ?? '', enabled, error: parsed.refused });
+        await ctx.record(SETTINGS, { oauth_enabled: enabled, redirect_uris: parsed.uris }, PLATFORM_CLIENT_ID);
+        return new Response(null, { status: 303, headers: { location: '?saved=1' } });
+    };
+}

package/dist/src/screens/portal.js

@@ -22,6 +22,7 @@ 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 { afterSuccessOf } from "../semantics/after-payment.js";
 import { created } from "../semantics/shared.js";
 import { publicBusinessName } from "../stripe-shared.js";
 import { declineFor, paymentMethodSubObject, PLATFORM_ACCOUNT_ID } from "../stripe-twin.js";
@@ -165,6 +166,7 @@ async function updatePaymentMethod(ctx, id, session, v) {
         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,
+        ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}),
     });
     const holder = ctx.get('customer', customer) ?? {};
     await ctx.write('customer', customer, { invoice_settings: { ...(holder.invoice_settings ?? {}), default_payment_method: pm.id } }, 'customer.update');

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

@@ -1,5 +1,5 @@
 import type { SemanticsContext } from '@volter/world-core';
-type Outcome = 'dispute' | 'dispute_not_received' | 'inquiry' | 'review';
+type Outcome = 'dispute' | 'dispute_not_received' | 'inquiry' | 'review' | 'available';
 /** 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;

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

@@ -1,5 +1,6 @@
 import { disputeEvidence } from "../stripe-twin.js";
 import { actingAccount, settleApplicationFee, settleDispute, settleTransfer } from "./ledger.js";
+import { BYPASS_PENDING_CARDS } from "./test-cards.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. */
@@ -8,11 +9,16 @@ export const AFTER_SUCCESS_CARDS = {
     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' },
+    // its funds go straight to the available balance (ledger.ts reads it; no act follows here)
+    ...Object.fromEntries(Object.entries(BYPASS_PENDING_CARDS).map(([name, c]) => [name, { ...c, outcome: 'available' }])),
 };
 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) {
+    // a card given as a token (card[token], payment_method_data[card][token]) is the card the token names
+    if (ref && typeof ref === 'object' && typeof ref.token === 'string')
+        return afterSuccessOf(ctx, ref.token);
     if (ref && typeof ref === 'object')
         return BY_NUMBER[String(ref.number ?? '').replace(/\D/g, '')];
     if (typeof ref !== 'string' || !ref)

package/dist/src/semantics/charges.js

@@ -15,13 +15,21 @@ export function chargeBody(ctx, c) {
 // (capture=false: its status is succeeded, captured false), and charge.failed, "Occurs whenever a failed charge attempt
 // occurs", for a declined attempt. The twin makes no pending charge (charge.pending, "Occurs whenever a pending charge is
 // created"): its charges settle when made.
+/** The create's parameters as the charge keeps them: without `card`, the request's card details ("A token, like the ones
+ *  returned by Stripe.js", or a hash of the number, expiry and CVC). The Charge object has no `card` property (served
+ *  spec, charge); the card it was made with is its payment_method_details. Kept, it answered the card's full number and
+ *  CVC back on every read of the charge. */
+function withoutCard(params) {
+    const { card: _card, ...rest } = params;
+    return rest;
+}
 /** A Charges-API charge a declining test card refuses: a 402 card_error naming the failed charge Stripe records for the
  *  attempt (docs.stripe.com/declines). */
 async function declinedCharge(ctx, decline) {
     const params = ctx.params;
     const failedId = ctx.mint('charge');
     const amount = Number(params.amount) || 0;
-    await created(ctx, 'charge', { ...params, id: failedId }, {
+    await created(ctx, 'charge', { ...withoutCard(params), id: failedId }, {
         ...chargeDefaults(failedId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
         failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
         outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
@@ -56,7 +64,7 @@ const create = async (ctx) => {
     const card = String(params.source ?? params.payment_method ?? params.card?.number ?? '');
     const bt = captured ? await settleCharge(ctx, id, amount, String(params.currency ?? 'usd'), card) : null;
     const details = paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card);
-    await created(ctx, 'charge', { ...params, id }, { ...chargeDefaults(id, amount, captured, ctx.occurredAt), balance_transaction: bt, payment_method_details: details ?? null }, { operation: 'charge.succeeded' });
+    await created(ctx, 'charge', { ...withoutCard(params), id }, { ...chargeDefaults(id, amount, captured, ctx.occurredAt), balance_transaction: bt, payment_method_details: details ?? null }, { operation: 'charge.succeeded' });
     await afterCharge(ctx, id, { amount, currency: String(params.currency ?? 'usd'), application_fee_amount: params.application_fee_amount, destination: params.transfer_data?.destination }, params.payment_method ?? params.source ?? params.card);
     return ctx.reply(chargeBody(ctx, ctx.get('charge', id)));
 };

package/dist/src/semantics/checkout.js

@@ -158,9 +158,20 @@ async function complete(ctx, id, existing, card) {
     const link = { status: 'complete' };
     const customer = typeof existing.customer === 'string' ? existing.customer : undefined;
     const currency = typeof existing.currency === 'string' ? existing.currency : 'usd';
-    // the entered card becomes a PaymentMethod, on the customer when there is one, carrying what a later charge to it
-    // answers and what Stripe does after it succeeds (docs.stripe.com/testing#declined-payments, #disputes)
-    const pm = card && existing.mode !== 'setup' ? await created(ctx, 'payment_method', {}, { type: 'card', customer: customer ?? null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null, ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}) }) : undefined;
+    // the entered card becomes a PaymentMethod carrying what a later charge to it answers and what Stripe does after it
+    // succeeds (docs.stripe.com/testing#declined-payments, #disputes)
+    const made = card ? await created(ctx, 'payment_method', {}, { type: 'card', customer: null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null, ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}) }) : undefined;
+    // and Checkout attaches it to the customer when it saves it: a subscription's card ("If your Checkout Session uses
+    // subscription mode, Stripe saves the payment method by default", docs.stripe.com/payments/checkout/how-checkout-works),
+    // a setup session's (it exists to save one), and a payment's only under payment_intent_data.setup_future_usage ("to have
+    // Checkout automatically attach the payment method to the Customer you pass in", docs.stripe.com/api/checkout/sessions/
+    // create#create_checkout_session-customer). Attaching is its own write, so payment_method.attached is delivered ("Occurs
+    // whenever a new payment method is attached to a customer", docs.stripe.com/api/events/types) before what the card then
+    // pays for. Where the documentation stops and the twin decides: the order of the events, which Stripe does not
+    // guarantee (docs.stripe.com/webhooks#event-ordering). A gap: the customer's own opt-in to save a payment's card
+    // (saved_payment_method_options.payment_method_save) is not modelled; the page offers no such box.
+    const saves = existing.mode !== 'payment' || !!(ctx.row(CS, id)?._payment_intent_data ?? {}).setup_future_usage;
+    const pm = made && customer && saves ? await ctx.write('payment_method', String(made.id), { customer }, 'payment_method.attach') : made;
     if (existing.mode === 'payment') {
         const amount = Number(existing.amount_total) || 0;
         const piId = ctx.mint('payment_intent');
@@ -169,6 +180,8 @@ async function complete(ctx, id, existing, card) {
             ...(pid.application_fee_amount !== undefined ? { application_fee_amount: Math.trunc(Number(pid.application_fee_amount) || 0) } : {}),
             ...(pid.transfer_data && typeof pid.transfer_data === 'object' ? { transfer_data: { destination: pid.transfer_data.destination } } : {}),
             ...(typeof pid.description === 'string' ? { description: pid.description } : {}),
+            // the session's setup_future_usage is its PaymentIntent's (payment_intent_data: "A subset of parameters to be passed to PaymentIntent creation")
+            ...(typeof pid.setup_future_usage === 'string' ? { setup_future_usage: pid.setup_future_usage } : {}),
             ...(pid.metadata && typeof pid.metadata === 'object' ? { metadata: pid.metadata } : {}),
         };
         const fields = { amount, currency, id: piId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}), ...connect };
@@ -225,7 +238,7 @@ async function complete(ctx, id, existing, card) {
         link.payment_status = 'paid';
     }
     else
-        link.setup_intent = await completeSetup(ctx, customer);
+        link.setup_intent = await completeSetup(ctx, customer, pm);
     return link;
 }
 /** A line item of a one-time Price: a stored Price, or an inline `price_data`, without `recurring` ("Line items with
@@ -261,9 +274,9 @@ async function sessionPrices(ctx, lines, inline) {
     return out;
 }
 /** A setup session saves the card through a succeeded SetupIntent (docs.stripe.com/payments/save-and-reuse?platform=checkout). */
-async function completeSetup(ctx, customer) {
+async function completeSetup(ctx, customer, pm) {
     const siId = ctx.mint('setup_intent');
-    const si = await created(ctx, 'setup_intent', { id: siId, ...(customer ? { customer } : {}) }, { status: 'succeeded', usage: 'off_session', client_secret: mintClientSecret(siId), payment_method_types: ['card'], livemode: false });
+    const si = await created(ctx, 'setup_intent', { id: siId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}) }, { status: 'succeeded', usage: 'off_session', client_secret: mintClientSecret(siId), payment_method_types: ['card'], livemode: false });
     return si.id;
 }
 /** The discount a completed subscription session gives its subscription. */

package/dist/src/semantics/connect.js

@@ -1,6 +1,7 @@
 import { ACCOUNT_TYPES, accountCapabilities, accountRequirements, accountSettings, asBool, PLATFORM_ACCOUNT_ID } from "../stripe-twin.js";
 import { currentlyDue, kindOf } from "../screens/onboarding.js";
 import { at, created, externalList, fail, list, newest, path, syncExternals } from "./shared.js";
+import { OAUTH_CONNECTIONS } from "../stripe-shared.js";
 const accountMissing = (ctx, id, status = 404) => fail(ctx, `No such account: '${id}'`, status, 'resource_missing');
 /** The account, tombstones included where the hand-written routes looked past a deletion. */
 const accountRow = (ctx, id) => ctx.row('account', id, { withDeleted: true });
@@ -19,7 +20,18 @@ export const platformAccountDefault = () => ({
     external_accounts: externalList(PLATFORM_ACCOUNT_ID, []), tos_acceptance: { date: null, ip: null, user_agent: null }, business_profile: {},
     settings: accountSettings(undefined), livemode: false,
 });
-const platform = async (ctx) => ctx.reply(ctx.get('account', PLATFORM_ACCOUNT_ID) ?? platformAccountDefault());
+// GET /v1/account answers the account the request acts as: with the Stripe-Account header (or a connected account's OAuth
+// key, which acts as it: stripe-server.ts) that connected account, "Retrieves the details of an account"
+// (docs.stripe.com/api/accounts/retrieve; docs.stripe.com/connect/authentication), else the platform's own
+const platform = async (ctx) => {
+    const acting = ctx.call.request.headers.get('stripe-account');
+    const connected = acting && acting !== PLATFORM_ACCOUNT_ID ? ctx.get('account', acting) : undefined;
+    // a Stripe-Account naming no account is refused as Stripe refuses a Stripe-Account the key cannot use (account_invalid,
+    // docs.stripe.com/error-codes; stripe-server.ts revokedAccountRefused words it the same)
+    if (acting && acting !== PLATFORM_ACCOUNT_ID && !connected)
+        return fail(ctx, `The provided key does not have access to account '${acting}' (or that account does not exist). Application access may have been revoked.`, 403, 'account_invalid');
+    return ctx.reply(connected ?? ctx.get('account', PLATFORM_ACCOUNT_ID) ?? platformAccountDefault());
+};
 /** A new Express account owes what its hosted onboarding will ask for (screens/onboarding.tsx; the US sets
  *  docs.stripe.com/connect/required-verification-information lists), or, where the twin does not model the set, the
  *  generic list. */
@@ -59,8 +71,13 @@ function controllerOf(type) {
         : type === 'custom' ? ['application', 'application_custom', 'application', 'none'] : ['stripe', 'account', 'stripe', 'full'];
     return { type: 'application', is_controller: true, losses: { payments: losses }, fees: { payer }, requirement_collection: collection, stripe_dashboard: { type: dashboard } };
 }
-// connected accounts only: the platform's own is not one
-const listAccounts = async (ctx) => list(ctx, 'account', newest(ctx, 'account').filter((a) => a.id !== PLATFORM_ACCOUNT_ID));
+// connected accounts only: the platform's own is not one, and neither is an account whose OAuth connection was revoked,
+// which "can't be accessed by your platform in the Dashboard or through the API" (docs.stripe.com/connect/oauth-reference;
+// its connection row is OAUTH_CONNECTIONS, screens/connect-oauth.tsx)
+const listAccounts = async (ctx) => {
+    const revoked = new Set(ctx.rowsRaw(OAUTH_CONNECTIONS).filter((c) => c.revoked === true).map((c) => c.id));
+    return list(ctx, 'account', newest(ctx, 'account').filter((a) => a.id !== PLATFORM_ACCOUNT_ID && !revoked.has(a.id)));
+};
 /** What a Custom account still owes, from what the platform has given for it, as Stripe's requirements endpoint lists it
  *  for a US account with no Stripe Dashboard and the full service agreement
  *  (docs.stripe.com/_endpoint/get-requirements-for-setups, the data behind

package/dist/src/semantics/invoices.js

@@ -307,7 +307,11 @@ const pay = async (ctx) => {
         return send(ctx, cardError(decline, intent ? { payment_intent: intent } : {}));
     const amountPaid = Number(inv.total ?? inv.amount_due) || 0;
     let body = await ctx.write(INV, id, {
+        // paid outside Stripe, the invoice counts it as such: `amount_paid_off_stripe`, "Amount, in cents (or local
+        // equivalent), that was paid on the invoice outside of Stripe" (served spec, invoice), the only place the served
+        // version shows it now that basil renders no `paid_out_of_band` (stripe-version.ts)
         status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
+        ...(paidOutOfBand ? { amount_paid_off_stripe: amountPaid } : {}),
         status_transitions: { ...transitions(inv), paid_at: ctx.now() },
     }, 'invoice.pay');
     if (!paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {

package/dist/src/semantics/issuing.js

@@ -382,10 +382,15 @@ const captureAuthorization = async (ctx) => {
     const captureAmount = ctx.params.capture_amount !== undefined ? Math.trunc(Number(ctx.params.capture_amount) || 0) : remaining;
     if (captureAmount <= 0 || captureAmount > remaining)
         return fail(ctx, 'Invalid capture_amount: must be a positive integer no greater than the uncaptured authorized amount.', 400, 'parameter_invalid_integer');
-    // the capture releases what the approval held and debits the transaction
+    // the capture releases what the approval held and debits the transaction; a capture that closes the authorization
+    // releases ALL it still holds, the uncaptured rest included: the amount is held "until the authorization is either
+    // captured, voided, or expired without capture" (docs.stripe.com/issuing/purchases/authorizations), and a closed
+    // authorization can be captured no further (close_authorization "Defaults to true. Set to false to enable
+    // multi-capture flows", the served spec). A capture that keeps it open releases only what it captured.
     const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+    const released = closeAuthorization ? remaining : captureAmount;
     const release = await created(ctx, 'balance_transaction', {}, {
-        amount: captureAmount, currency, fee: 0, net: captureAmount, type: 'issuing_authorization_release',
+        amount: released, currency, fee: 0, net: released, type: 'issuing_authorization_release',
         status: 'available', balance_type: 'issuing', reporting_category: 'issuing_authorization_release',
         available_on: ctx.now(), fee_details: [], source: id,
     });

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

@@ -1,9 +1,13 @@
 import type { Semantics, SemanticsContext } from '@volter/world-core';
 import { type Row } from './shared.js';
+/** Whether a charge's funds go straight to the available balance: a bypass card as a raw number, a test name (pm_card_*
+ *  or tok_*), or a stored PaymentMethod made from one (which records it as what follows its success, after-payment.ts);
+ *  or a US bank account, stored or one of Stripe's test bank accounts named as one (pm_usBankAccount_*). */
+export declare function bypassesPending(ctx: SemanticsContext, card: string | undefined): boolean;
 /** The connected account a request acts for, or undefined for the platform. */
 export declare const actingAccount: (ctx: SemanticsContext) => string | undefined;
-/** A captured charge's credit: its amount less the fee, pending two days unless the card (a number, or a test
- *  payment method or token named for it) settles at once. The
+/** A captured charge's credit: its amount less the fee, pending two days unless the card bypasses the pending
+ *  balance (bypassesPending), when it is due at once. The
  *  caller mints the charge's id first and stores the returned id as the charge's balance_transaction. */
 export declare function settleCharge(ctx: SemanticsContext, chargeId: string, amount: number, currency: string, card?: string): Promise<string>;
 /** A refund's debit, at once, on the acting account's balance unless one is named (null names the platform). */
@@ -27,9 +31,10 @@ export declare function unpaidEntries(ctx: SemanticsContext, account: string | u
 export declare function settleAutomaticPayout(ctx: SemanticsContext, payoutId: string, amount: number, currency: string, account: string | undefined, at: number, entries: Row[]): Promise<string>;
 /** A payout's debit (negative) or a cancellation's or reversal's credit (positive), at once, on the payout's account. */
 export declare function settlePayout(ctx: SemanticsContext, payoutId: string, amount: number, currency: string, account?: string | null | undefined): Promise<string>;
-/** A transfer's two entries: out of the platform's balance at once, into the destination's when `availableOn` comes
- *  (a plain transfer's funds are available already). Answers the platform's entry. */
-export declare function settleTransfer(ctx: SemanticsContext, transferId: string, amount: number, currency: string, destination: string, availableOn?: number, fromPending?: boolean): Promise<string>;
+/** A transfer's two entries: out of the platform's balance at once, into the destination's when `fromCharge` (its
+ *  charge's funds' availability) comes (a plain transfer, with no `fromCharge`, moves funds available already).
+ *  Answers the platform's entry. */
+export declare function settleTransfer(ctx: SemanticsContext, transferId: string, amount: number, currency: string, destination: string, fromCharge?: number, fromPending?: boolean): Promise<string>;
 /** A transfer reversal's two entries: back into the platform's balance, out of the destination's. */
 export declare function settleTransferReversal(ctx: SemanticsContext, reversalId: string, amount: number, currency: string, destination: string): Promise<string>;
 /** A direct charge's application fee: out of the connected account's balance, into the platform's. */
@@ -41,7 +46,7 @@ export declare function settleTopup(ctx: SemanticsContext, topupId: string, amou
 /** Time's settlements, written: each entry on the acting account's balance whose funds came due by the World's clock
  *  moves pending → available (the clock's move the machine allows), so a settlement is recorded once. A read already
  *  sees it (asOf); the record is what lets Stripe's balance.available be sent once (stripe-server.ts, the drain).
- *  Answers the entries that moved. */
+ *  Funds that were available at once and not yet sent are taken too, and marked sent. Answers the entries taken. */
 export declare function settleDueEntries(ctx: SemanticsContext): Promise<Row[]>;
 /** An account's balance, by currency: what the clock has made available, what is still pending, and Issuing's own. */
 export declare function balanceOf(ctx: SemanticsContext, account?: string | undefined): {

package/dist/src/semantics/ledger.js

@@ -1,36 +1,46 @@
-import { at, created, fail, inRange, kept, list, newest, where } from "./shared.js";
+import { asOf, at, created, fail, inRange, kept, list, newest, where } from "./shared.js";
+import { BYPASS_PENDING_CARDS } from "./test-cards.js";
 const BT = 'balance_transaction';
 const DAY = 86_400;
-const BYPASS_PENDING = '4000000000000077';
-const feeOf = (amount) => (amount > 0 ? Math.round(amount * 0.029) + 30 : 0);
-/** A transaction as the clock reads it: available once its available_on has passed, the clock's move,
- *  asked of the machine as a write asks it. */
-function asOf(ctx, t) {
-    const due = Number(t.available_on);
-    if (t.status !== 'pending' || !Number.isFinite(due) || due > Number(ctx.now()))
-        return t;
-    ctx.legal('balance_transaction', 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time');
-    return { ...t, status: 'available' };
+/** A ledger entry's mark: available at once, its balance.available not yet sent (settleDueEntries). */
+const UNSENT = '_availableUnsent';
+const BYPASS_NUMBERS = new Set(Object.values(BYPASS_PENDING_CARDS).map((c) => c.number));
+/** Whether a charge's funds go straight to the available balance: a bypass card as a raw number, a test name (pm_card_*
+ *  or tok_*), or a stored PaymentMethod made from one (which records it as what follows its success, after-payment.ts);
+ *  or a US bank account, stored or one of Stripe's test bank accounts named as one (pm_usBankAccount_*). */
+export function bypassesPending(ctx, card) {
+    if (!card)
+        return false;
+    const stored = ctx.row('payment_method', card);
+    // the row carries what the method recorded; its type is the vendor object's (ctx.get), not the row's envelope
+    if (stored)
+        return stored._afterSuccess === 'available' || ctx.get('payment_method', card)?.type === 'us_bank_account';
+    if (/^pm_us_?bank_?account/i.test(card))
+        return true;
+    return BYPASS_NUMBERS.has(card.replace(/\D/g, '')) || card.replace(/^tok_/, 'pm_card_') in BYPASS_PENDING_CARDS;
 }
+const feeOf = (amount) => (amount > 0 ? Math.round(amount * 0.029) + 30 : 0);
 /** The connected account a request acts for, or undefined for the platform. */
 export const actingAccount = (ctx) => ctx.call.request.headers.get('stripe-account') ?? undefined;
 /** A ledger entry on an account's balance: the acting account's unless one is named (null names the platform). */
 async function write(ctx, fields, account = actingAccount(ctx)) {
-    const bt = await created(ctx, BT, {}, { status: 'available', fee_details: [], description: null, exchange_rate: null, balance_type: 'payments', ...fields, ...(account ? { _account: account } : {}) });
+    // a credit available at once waits for the drain's balance.available (settleDueEntries)
+    const unsent = (fields.status ?? 'available') === 'available' && Number(fields.net) > 0 ? { [UNSENT]: true } : {};
+    const bt = await created(ctx, BT, {}, { status: 'available', fee_details: [], description: null, exchange_rate: null, balance_type: 'payments', ...fields, ...unsent, ...(account ? { _account: account } : {}) });
     return String(bt.id);
 }
 /** Whether a stored ledger entry is on this account's balance (undefined: the platform's). */
 const onAccount = (t, account) => (typeof t._account === 'string' ? t._account : undefined) === account;
-/** A captured charge's credit: its amount less the fee, pending two days unless the card (a number, or a test
- *  payment method or token named for it) settles at once. The
+/** A captured charge's credit: its amount less the fee, pending two days unless the card bypasses the pending
+ *  balance (bypassesPending), when it is due at once. The
  *  caller mints the charge's id first and stores the returned id as the charge's balance_transaction. */
 export async function settleCharge(ctx, chargeId, amount, currency, card) {
     const now = Number(ctx.now());
     const fee = feeOf(amount);
-    const settled = !!card && (card.replace(/\D/g, '') === BYPASS_PENDING || /bypassPending/i.test(card));
+    const atOnce = bypassesPending(ctx, card);
     const id = await write(ctx, {
         amount, currency, fee, net: amount - fee, type: 'charge', reporting_category: 'charge', source: chargeId,
-        status: settled ? 'available' : 'pending', available_on: settled ? now : now + 2 * DAY,
+        ...(atOnce ? { status: 'available', available_on: now } : { status: 'pending', available_on: now + 2 * DAY }),
         fee_details: fee ? [{ amount: fee, application: null, currency, description: 'Stripe processing fees', type: 'stripe_fee' }] : [],
     });
     return id;
@@ -89,9 +99,11 @@ export async function settlePayout(ctx, payoutId, amount, currency, account = ac
     const type = amount < 0 ? 'payout' : 'payout_cancel';
     return write(ctx, { amount, currency, fee: 0, net: amount, type, reporting_category: type === 'payout' ? 'payout' : 'payout_reversal', source: payoutId, available_on: Number(ctx.now()) }, account);
 }
-/** A transfer's two entries: out of the platform's balance at once, into the destination's when `availableOn` comes
- *  (a plain transfer's funds are available already). Answers the platform's entry. */
-export async function settleTransfer(ctx, transferId, amount, currency, destination, availableOn = Number(ctx.now()), fromPending = false) {
+/** A transfer's two entries: out of the platform's balance at once, into the destination's when `fromCharge` (its
+ *  charge's funds' availability) comes (a plain transfer, with no `fromCharge`, moves funds available already).
+ *  Answers the platform's entry. */
+export async function settleTransfer(ctx, transferId, amount, currency, destination, fromCharge, fromPending = false) {
+    const availableOn = fromCharge ?? Number(ctx.now());
     const settled = availableOn <= Number(ctx.now());
     // a transfer from a charge's pending funds (source_transaction) leaves the platform when they arrive, not before
     const platform = await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'transfer', reporting_category: 'transfer', source: transferId, ...(fromPending ? { status: settled ? 'available' : 'pending', available_on: availableOn } : { available_on: Number(ctx.now()) }) }, null);
@@ -119,13 +131,20 @@ export async function settleTopup(ctx, topupId, amount, currency, destination) {
 /** Time's settlements, written: each entry on the acting account's balance whose funds came due by the World's clock
  *  moves pending → available (the clock's move the machine allows), so a settlement is recorded once. A read already
  *  sees it (asOf); the record is what lets Stripe's balance.available be sent once (stripe-server.ts, the drain).
- *  Answers the entries that moved. */
+ *  Funds that were available at once and not yet sent are taken too, and marked sent. Answers the entries taken. */
 export async function settleDueEntries(ctx) {
     const now = Number(ctx.now());
     const account = actingAccount(ctx);
     const moved = [];
     for (const t of ctx.rowsRaw(BT)) {
-        if (!onAccount(t, account) || t.status !== 'pending' || !(Number(t.available_on) <= now))
+        if (!onAccount(t, account))
+            continue;
+        if (t.status === 'available' && t[UNSENT] === true) {
+            await ctx.write(BT, String(t.id), { [UNSENT]: false }, 'balance_transaction.available_sent');
+            moved.push(t);
+            continue;
+        }
+        if (t.status !== 'pending' || !(Number(t.available_on) <= now))
             continue;
         if (ctx.legal(BT, 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time'))
             continue;

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

@@ -126,6 +126,8 @@ export async function methodFromData(ctx, data) {
         type, customer: null, livemode: false, metadata: {},
         billing_details: { ...noBilling, ...(d.billing_details ?? {}) },
         ...paymentMethodSubObject(type, d),
+        // what follows its card's success (a dispute, funds straight to available), as a PaymentMethod created directly carries
+        ...(type === 'card' && afterSuccessOf(ctx, d.card) ? { _afterSuccess: afterSuccessOf(ctx, d.card) } : {}),
     });
     return String(made.id);
 }

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

@@ -43,8 +43,12 @@ export declare function inRange(t: unknown, v: unknown): boolean;
  *  moment a later request caught it up. */
 export declare function at_(ctx: SemanticsContext): (t: number) => Promise<SemanticsContext>;
 export declare function where(ctx: SemanticsContext, items: Row[], spec: Record<string, (item: Row, value: unknown) => boolean>): Row[];
+/** A balance transaction as the clock reads it: available once its available_on has passed, the clock's move,
+ *  asked of the machine as a write asks it (semantics/ledger.ts). */
+export declare function asOf(ctx: SemanticsContext, t: Row): Row;
 /** Stripe's expand walk: each dotted path replaces an id with the resource the manifest says it
- *  holds, one segment at a time; an id the tree lacks stays an id. */
+ *  holds, one segment at a time; an id the tree lacks stays an id. A balance transaction reads as the clock has it
+ *  (asOf), as its own retrieve does. */
 export declare function expandRow(ctx: SemanticsContext, resource: string, body: Row, paths: string[][]): Row;
 /** One resource with the request's `expand[]` applied. */
 export declare const expanded: (ctx: SemanticsContext, resource: string, body: Row) => Row;

package/dist/src/semantics/shared.js

@@ -109,8 +109,18 @@ function expandPaths(ctx) {
     const expand = ctx.params.expand;
     return Array.isArray(expand) ? expand.map((p) => String(p).split('.')) : [];
 }
+/** A balance transaction as the clock reads it: available once its available_on has passed, the clock's move,
+ *  asked of the machine as a write asks it (semantics/ledger.ts). */
+export function asOf(ctx, t) {
+    const due = Number(t.available_on);
+    if (t.status !== 'pending' || !Number.isFinite(due) || due > Number(ctx.now()))
+        return t;
+    ctx.legal('balance_transaction', 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time');
+    return { ...t, status: 'available' };
+}
 /** Stripe's expand walk: each dotted path replaces an id with the resource the manifest says it
- *  holds, one segment at a time; an id the tree lacks stays an id. */
+ *  holds, one segment at a time; an id the tree lacks stays an id. A balance transaction reads as the clock has it
+ *  (asOf), as its own retrieve does. */
 export function expandRow(ctx, resource, body, paths) {
     const embeds = manifest.resources[resource]?.embeds;
     if (!embeds || paths.length === 0)
@@ -129,9 +139,10 @@ export function expandRow(ctx, resource, body, paths) {
         if (!target)
             continue;
         const cur = out[head];
-        const sub = typeof cur === 'string' && cur ? ctx.get(target, cur) : cur && typeof cur === 'object' && !Array.isArray(cur) ? cur : undefined;
-        if (!sub)
+        const found = typeof cur === 'string' && cur ? ctx.get(target, cur) : cur && typeof cur === 'object' && !Array.isArray(cur) ? cur : undefined;
+        if (!found)
             continue;
+        const sub = target === 'balance_transaction' ? asOf(ctx, found) : found;
         const deeper = tails.filter((t) => t.length > 0);
         out = { ...out, [head]: deeper.length ? expandRow(ctx, target, sub, deeper) : sub };
     }

package/dist/src/semantics/test-cards.d.ts

@@ -0,0 +1,4 @@
+export declare const BYPASS_PENDING_CARDS: Record<string, {
+    brand: string;
+    number: string;
+}>;

package/dist/src/semantics/test-cards.js

@@ -0,0 +1,7 @@
+// Stripe's test cards whose funds bypass the pending balance, by their test names and numbers
+// (docs.stripe.com/testing#available-balance: "Funds are added directly to your available balance, bypassing your
+// pending balance"). A leaf: ledger.ts reads it to settle a charge, after-payment.ts to record it on a PaymentMethod.
+export const BYPASS_PENDING_CARDS = {
+    pm_card_bypassPending: { brand: 'visa', number: '4000000000000077' },
+    pm_card_bypassPendingInternational: { brand: 'visa', number: '4000003720000278' },
+};

package/dist/src/semantics/transfers.js

@@ -55,7 +55,7 @@ const create = async (ctx) => {
             return refused;
     }
     const id = ctx.mint('transfer');
-    const bt = await settleTransfer(ctx, id, amount, currency, destination, availableOn ?? Number(ctx.now()), sourceId !== undefined);
+    const bt = await settleTransfer(ctx, id, amount, currency, destination, availableOn, sourceId !== undefined);
     return ctx.reply(await created(ctx, 'transfer', { id, ...ctx.params, ...(group ? { transfer_group: group } : {}) }, {
         amount_reversed: 0, balance_transaction: bt, livemode: false, metadata: {},
         reversed: false, source_type: 'card', source_transaction: null,