@volter/twin-stripe 0.1.1 → 2.0.0

package/dist/src/semantics/ledger.js

@@ -0,0 +1,181 @@
+import { at, created, fail, inRange, kept, list, newest, where } from "./shared.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' };
+}
+/** 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 } : {}) });
+    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
+ *  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 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,
+        fee_details: fee ? [{ amount: fee, application: null, currency, description: 'Stripe processing fees', type: 'stripe_fee' }] : [],
+    });
+    return id;
+}
+/** A refund's debit, at once, on the acting account's balance unless one is named (null names the platform). */
+export async function settleRefund(ctx, refundId, amount, currency, account = actingAccount(ctx)) {
+    return write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'refund', reporting_category: 'refund', source: refundId, available_on: Number(ctx.now()) }, account);
+}
+/** What an account had available in a currency at a moment: every entry of its payments balance whose funds had come
+ *  due by then. */
+export function availableAt(ctx, account, currency, at) {
+    let sum = 0;
+    for (const t of ctx.rowsRaw(BT)) {
+        if (!onAccount(t, account) || t.balance_type === 'issuing' || String(t.currency ?? 'usd') !== currency)
+            continue;
+        const due = Number(t.available_on ?? t.created);
+        if (Number.isFinite(due) && due <= at)
+            sum += Number(t.net ?? 0);
+    }
+    return sum;
+}
+/** The moments after `from` and up to `until` when funds of an account came due, in order: when a held refund can
+ *  next be covered. */
+export function fundsDueBetween(ctx, account, currency, from, until) {
+    const times = ctx.rowsRaw(BT).filter((t) => onAccount(t, account) && String(t.currency ?? 'usd') === currency).map((t) => Number(t.available_on ?? t.created)).filter((d) => Number.isFinite(d) && d > from && d <= until);
+    return [...new Set(times)].sort((a, b) => a - b);
+}
+/** A dispute's debit, at once: the disputed amount and the dispute fee (the twin's 1500 cents, Stripe's US $15). */
+export async function settleDispute(ctx, disputeId, amount, currency) {
+    const fee = 1500;
+    return write(ctx, {
+        amount: -amount, currency, fee, net: -amount - fee, type: 'adjustment', reporting_category: 'dispute', source: disputeId, available_on: Number(ctx.now()),
+        fee_details: [{ amount: fee, application: null, currency, description: 'Dispute fee', type: 'stripe_fee' }],
+    });
+}
+/** A won dispute's credit, at once: the disputed amount returned (docs.stripe.com/disputes/how-disputes-work). Where the
+ *  documentation stops and the twin decides: the dispute fee is not returned. */
+export async function settleDisputeWon(ctx, disputeId, amount, currency) {
+    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'adjustment', reporting_category: 'dispute_reversal', source: disputeId, available_on: Number(ctx.now()) });
+}
+/** An account's ledger entries an automatic payout has not yet paid out: every entry on its payments balance that no
+ *  automatic payout took (the automatic payouts' own debits excluded), as stored. */
+export function unpaidEntries(ctx, account) {
+    const automatic = new Set(ctx.rowsRaw('payout').filter((p) => p.automatic === true).map((p) => p.id));
+    return ctx.rowsRaw(BT).filter((t) => onAccount(t, account) && t.balance_type !== 'issuing' && !t._payout && !automatic.has(t.source));
+}
+/** An automatic payout's debit at `at`, and the entries it pays out marked with it, so the ledger lists them under
+ *  the payout (docs.stripe.com/api/balance_transactions/list#balance_transaction_list-payout). */
+export async function settleAutomaticPayout(ctx, payoutId, amount, currency, account, at, entries) {
+    for (const t of entries)
+        await ctx.write(BT, String(t.id), { _payout: payoutId }, 'balance_transaction.paid_out');
+    return write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'payout', reporting_category: 'payout', source: payoutId, available_on: at, _payout: payoutId }, account ?? null);
+}
+/** A payout's debit (negative) or a cancellation's or reversal's credit (positive), at once, on the payout's account. */
+export async function settlePayout(ctx, payoutId, amount, currency, account = actingAccount(ctx)) {
+    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) {
+    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);
+    await write(ctx, { amount, currency, fee: 0, net: amount, type: 'payment', reporting_category: 'charge', source: transferId, status: settled ? 'available' : 'pending', available_on: availableOn }, destination);
+    return platform;
+}
+/** A transfer reversal's two entries: back into the platform's balance, out of the destination's. */
+export async function settleTransferReversal(ctx, reversalId, amount, currency, destination) {
+    const platform = await write(ctx, { amount, currency, fee: 0, net: amount, type: 'transfer_refund', reporting_category: 'transfer_reversal', source: reversalId, available_on: Number(ctx.now()) }, null);
+    await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'payment_refund', reporting_category: 'refund', source: reversalId, available_on: Number(ctx.now()) }, destination);
+    return platform;
+}
+/** A direct charge's application fee: out of the connected account's balance, into the platform's. */
+export async function settleApplicationFee(ctx, feeId, amount, currency, account) {
+    await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'application_fee', reporting_category: 'platform_earning', source: feeId, available_on: Number(ctx.now()) }, account);
+    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'application_fee', reporting_category: 'platform_earning', source: feeId, available_on: Number(ctx.now()) }, null);
+}
+/** A top-up's credit, to the payments balance or, with `destination_balance=issuing`, to Issuing's
+ *  (docs.stripe.com/issuing/funding/balance). Where the documentation stops and the twin decides: a test-mode top-up
+ *  is available at once. */
+export async function settleTopup(ctx, topupId, amount, currency, destination) {
+    const issuing = destination === 'issuing';
+    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'topup', reporting_category: 'topup', source: topupId, available_on: Number(ctx.now()), balance_type: issuing ? 'issuing' : 'payments' });
+}
+/** 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. */
+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))
+            continue;
+        if (ctx.legal(BT, 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time'))
+            continue;
+        await ctx.write(BT, String(t.id), { status: 'available' }, 'balance_transaction.available');
+        moved.push(t);
+    }
+    return moved;
+}
+/** An account's balance, by currency: what the clock has made available, what is still pending, and Issuing's own. */
+export function balanceOf(ctx, account = actingAccount(ctx)) {
+    const available = new Map();
+    const pending = new Map();
+    const issuing = new Map();
+    for (const raw of ctx.rowsRaw(BT)) {
+        if (!onAccount(raw, account))
+            continue;
+        const t = asOf(ctx, raw);
+        const cur = String(t.currency ?? 'usd');
+        const net = Number(t.net ?? 0);
+        const bucket = t.balance_type === 'issuing' ? issuing : t.status === 'available' ? available : pending;
+        bucket.set(cur, (bucket.get(cur) ?? 0) + net);
+    }
+    return { available, pending, issuing };
+}
+/** balance_insufficient when a payout or transfer would take more than the account has available in its currency. */
+export function refusePayout(ctx, amount, currency, account = actingAccount(ctx)) {
+    const have = balanceOf(ctx, account).available.get(currency) ?? 0;
+    if (amount <= have)
+        return undefined;
+    return fail(ctx, "The transfer or payout couldn't be completed because the associated account doesn't have a sufficient balance available.", 400, 'balance_insufficient');
+}
+/** The ids of the ledger entries on the acting account's balance. */
+const mine = (ctx) => new Set(ctx.rowsRaw(BT).filter((t) => onAccount(t, actingAccount(ctx))).map((t) => t.id));
+const retrieve = async (ctx) => {
+    const t = ctx.get(BT, at(ctx, 'id'));
+    return t && mine(ctx).has(t.id) ? ctx.reply(asOf(ctx, t)) : ctx.notFound(BT, at(ctx, 'id'));
+};
+const listAll = async (ctx) => {
+    const own = mine(ctx);
+    return list(ctx, BT, where(ctx, newest(ctx, BT).filter((t) => own.has(t.id)).map((t) => asOf(ctx, t)), {
+        type: (t, v) => t.type === v,
+        currency: (t, v) => t.currency === v,
+        source: (t, v) => t.source === v,
+        // an automatic payout lists the entries it paid out, its own debit among them
+        payout: (t, v) => t.source === v || kept(ctx, BT, t, '_payout') === v,
+        // a range of creation times (docs.stripe.com/api/balance_transactions/list#balance_transaction_list-created)
+        created: (t, v) => inRange(t.created, v),
+    }));
+};
+export const ledger = {
+    GetBalanceTransactions: listAll,
+    GetBalanceTransactionsId: retrieve,
+};

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

@@ -0,0 +1,18 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+export declare function mintCharge(ctx: SemanticsContext, piId: string, pi: Row, amount: number): Promise<string>;
+/** A manual-capture intent's authorization: "Separate payment authorization and capture to create a charge now, but
+ *  capture funds later", and on capture "A partial capture automatically releases the remaining amount"
+ *  (docs.stripe.com/payments/place-a-hold-on-a-payment-method). The charge succeeded and is not captured, holding the
+ *  amount until capture_before, with nothing on the balance yet. Written as
+ *  charge.succeeded, as a charge made with capture=false is (charges.ts); its capture writes charge.captured
+ *  (captureAuthorization). Where the documentation stops and the twin decides: the events page names no event for an
+ *  authorization of its own, so the authorized charge sends charge.succeeded, its status being succeeded. */
+export declare function authorizeCharge(ctx: SemanticsContext, piId: string, pi: Row, amount: number): Promise<string>;
+/** Whether the method an intent is confirmed with is a bank debit: a us_bank_account PaymentMethod, or one of Stripe's
+ *  test bank accounts named as one (pm_usBankAccount_*, pm_us_bank_account). */
+export declare function isBankDebit(ctx: SemanticsContext, method: unknown): boolean;
+/** Time's settling of bank debits, caught up to the World's clock: each processing debit whose moment has come succeeds
+ *  then, its Charge made (naming the mandate it ran under) and the invoice it collects for paid. */
+export declare function settleBankDebits(ctx: SemanticsContext): Promise<void>;
+export declare const paymentIntents: Record<string, Semantics>;

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

@@ -0,0 +1,404 @@
+import { asBool, cardError, chargeDefaults, declineFor, microdepositsNextAction, mintClientSecret, requiresAuthentication, requiresMicrodeposits, threeDsNextAction, validateMoney, verifyMicrodeposits, } from "../stripe-twin.js";
+import { afterCharge, mintMandate } from "./after-payment.js";
+import { cancelAuthorization, captureAuthorization } from "./charges.js";
+import { settleCharge } from "./ledger.js";
+import { materializeTestMethod, methodFromData, microdepositsAsked, paymentMethodDetails } from "./payment-methods.js";
+import { at_, confirmOnly, created, fail, finder, search } from "./shared.js";
+const PI = 'payment_intent';
+const send = (ctx, r) => ctx.reply(r.body, r.status);
+// ── THE MONEY MODEL, continued: a succeeded intent has a Charge ──
+//
+// Real Stripe always materializes a Charge when a PaymentIntent succeeds and points the intent's
+// `latest_charge` at it: the charge is what a refund lands on, so an intent that succeeds without
+// one cannot answer "refund this payment" at all. Idempotent against a repeated confirm: an intent
+// that already names a successful charge keeps it (a second one would double the money collected); a
+// declined attempt's failed charge is history, and the payment that succeeds makes its own. The id is
+// returned so the caller folds `latest_charge` into the same intent write (one write, one event). The
+// charge is written as the event Stripe sends for it, `charge.succeeded` ("Occurs whenever a charge is
+// successful", docs.stripe.com/api/events/types); Stripe has no `charge.created`.
+/** What every charge an intent makes carries of it: its transfer_group, which "identifies the resulting payment as part
+ *  of a group" (docs.stripe.com/api/payment_intents/object), its description and its metadata. */
+function intentCarries(pi) {
+    return {
+        ...(typeof pi.transfer_group === 'string' ? { transfer_group: pi.transfer_group } : {}),
+        ...(typeof pi.description === 'string' ? { description: pi.description } : {}),
+        // "When a PaymentIntent creates a Charge, the metadata copies to the Charge in a one-time snapshot"
+        // (docs.stripe.com/metadata, "Copy metadata to another object")
+        ...(pi.metadata && typeof pi.metadata === 'object' ? { metadata: { ...pi.metadata } } : {}),
+    };
+}
+export async function mintCharge(ctx, piId, pi, amount) {
+    const already = ctx.get(PI, piId)?.latest_charge;
+    if (typeof already === 'string' && ctx.get('charge', already)?.status === 'succeeded')
+        return already;
+    const chargeId = ctx.mint('charge');
+    const bt = await settleCharge(ctx, chargeId, amount, String(pi.currency ?? 'usd'), typeof pi.payment_method === 'string' ? pi.payment_method : undefined);
+    await created(ctx, 'charge', {
+        id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
+        ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
+        ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
+        ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
+        ...intentCarries(pi),
+    }, { ...chargeDefaults(chargeId, amount, true, ctx.occurredAt), balance_transaction: bt, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
+    await afterCharge(ctx, chargeId, { amount, currency: String(pi.currency ?? 'usd'), payment_intent: piId, application_fee_amount: pi.application_fee_amount, destination: pi.transfer_data?.destination }, pi.payment_method);
+    return chargeId;
+}
+/** A manual-capture intent's authorization: "Separate payment authorization and capture to create a charge now, but
+ *  capture funds later", and on capture "A partial capture automatically releases the remaining amount"
+ *  (docs.stripe.com/payments/place-a-hold-on-a-payment-method). The charge succeeded and is not captured, holding the
+ *  amount until capture_before, with nothing on the balance yet. Written as
+ *  charge.succeeded, as a charge made with capture=false is (charges.ts); its capture writes charge.captured
+ *  (captureAuthorization). Where the documentation stops and the twin decides: the events page names no event for an
+ *  authorization of its own, so the authorized charge sends charge.succeeded, its status being succeeded. */
+export async function authorizeCharge(ctx, piId, pi, amount) {
+    const chargeId = ctx.mint('charge');
+    await created(ctx, 'charge', {
+        id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
+        ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
+        ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
+        ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
+        ...intentCarries(pi),
+    }, { ...chargeDefaults(chargeId, amount, false, ctx.occurredAt), balance_transaction: null, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
+    return chargeId;
+}
+/**
+ * An intent an invoice collects through succeeded (the default_incomplete subscription flow: create
+ * now, confirm client-side): its invoice is paid and, when it is a subscription's first, the
+ * subscription leaves incomplete for active. Both are moves the invoice and subscription machines
+ * declare under the confirming operation. No-op when the intent names no invoice, or the invoice is
+ * already paid (a duplicate confirm) or void (voiding ends what it collects).
+ */
+async function payInvoiceOf(ctx, pi, operationId, actor) {
+    const invoiceId = typeof pi.invoice === 'string' ? pi.invoice : undefined;
+    const invoice = invoiceId ? ctx.get('invoice', invoiceId) : undefined;
+    if (!invoiceId || !invoice || invoice.status === 'paid' || invoice.status === 'void')
+        return;
+    if (ctx.legal('invoice', 'status', operationId, invoice.status, 'paid', invoiceId, actor))
+        return;
+    const amount = Number(invoice.total ?? invoice.amount_due) || 0;
+    // `invoice.pay` is the event the standalone pay action sends: invoice.paid
+    await ctx.write('invoice', invoiceId, {
+        status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0,
+        status_transitions: { ...(invoice.status_transitions ?? {}), paid_at: ctx.now() },
+    }, 'invoice.pay');
+    const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
+    const sub = subId ? ctx.get('subscription', subId) : undefined;
+    if (subId && sub && sub.status === 'incomplete' && !ctx.legal('subscription', 'status', operationId, sub.status, 'active', subId, actor)) {
+        await ctx.write('subscription', subId, { status: 'active' }, 'subscription.update');
+    }
+}
+/** The intent the path names, and the machine's refusal when this operation may not move it. */
+function load(ctx, operationId) {
+    const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
+    if (!pi)
+        return { answer: ctx.notFound(PI, String(ctx.id)) };
+    const refusal = ctx.legal(PI, 'status', operationId, pi.status);
+    return refusal ? { answer: ctx.refuse(refusal) } : { pi };
+}
+const create = async (ctx) => {
+    const params = ctx.params;
+    const bad = validateMoney(params);
+    if (bad)
+        return send(ctx, bad);
+    // what describes a confirmation needs one: error_on_requires_action, mandate, mandate_data, off_session and return_url
+    // are each, in the served spec, a parameter that "can only be used with `confirm=true`" (shared.ts confirmOnly)
+    const unconfirmed = confirmOnly(ctx, ['error_on_requires_action', 'mandate', 'mandate_data', 'off_session', 'return_url'], asBool(params.confirm));
+    if (unconfirmed)
+        return unconfirmed;
+    // automatic_payment_methods: when enabled, Stripe selects eligible methods and answers the
+    // normalized { enabled, allow_redirects } object
+    const apmIn = params.automatic_payment_methods;
+    const apmEnabled = apmIn && typeof apmIn === 'object' ? asBool(apmIn.enabled) : false;
+    const automatic_payment_methods = apmEnabled ? { enabled: true, allow_redirects: apmIn.allow_redirects ?? 'always' } : null;
+    // the methods it may be paid with: allowed_payment_method_types in the served version, payment_method_types for a
+    // caller pinned to an earlier one (docs.stripe.com/api/payment_intents/create)
+    const given = Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types : params.payment_method_types;
+    const payment_method_types = Array.isArray(given) ? given.map(String) : ['card'];
+    // `confirm` is an instruction, not a field: `confirm=true` attempts to confirm the intent at once
+    // (https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm)
+    const { automatic_payment_methods: _a, payment_method_types: _p, allowed_payment_method_types: _ap, id: provided, expand: _e, confirm: confirmNow, payment_method_data: data, mandate_data: _mandate, ...rest } = params;
+    // a create's payment_method_data makes its method, as a confirm's does (payment-methods.ts methodFromData)
+    const made = await methodFromData(ctx, data);
+    if (made)
+        rest.payment_method = made;
+    // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
+    const id = typeof provided === 'string' && provided ? provided : ctx.mint(PI);
+    // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
+    const hasMethod = typeof rest.payment_method === 'string' && rest.payment_method !== '';
+    if (hasMethod)
+        ctx.legal(PI, 'status', 'PostPaymentIntents', 'requires_payment_method', 'requires_confirmation', id);
+    const body = await ctx.write(PI, id, {
+        object: 'payment_intent',
+        created: ctx.now(),
+        status: hasMethod ? 'requires_confirmation' : 'requires_payment_method',
+        client_secret: mintClientSecret(id),
+        livemode: false,
+        capture_method: 'automatic',
+        amount_capturable: 0,
+        amount_received: 0,
+        next_action: null,
+        automatic_payment_methods,
+        payment_method_types,
+        ...(Array.isArray(params.allowed_payment_method_types) ? { allowed_payment_method_types: payment_method_types } : {}),
+        payment_method_options: params.payment_method_options ?? {},
+        ...rest,
+    }, 'payment_intent.create');
+    if (asBool(confirmNow))
+        return confirmIntent(ctx, body, {});
+    return ctx.reply(ctx.expand(PI, body));
+};
+const confirm = async (ctx) => {
+    const loaded = load(ctx, 'PostPaymentIntentsIntentConfirm');
+    if ('answer' in loaded)
+        return loaded.answer;
+    const { expand: _e, payment_method_data: data, mandate_data: _mandate, ...params } = ctx.params;
+    // a confirm's payment_method_data makes the method it pays with; neither it nor mandate_data is a field of the intent
+    const made = await methodFromData(ctx, data);
+    return confirmIntent(ctx, loaded.pi, made ? { ...params, payment_method: made } : params);
+};
+/** Confirm an intent the confirm machine allows to move: the confirm action, and a create with `confirm=true`. */
+async function confirmIntent(ctx, existing, params) {
+    const id = String(existing.id);
+    // a payment names a mandate only an active one authorizes: an inactive mandate "was rejected, revoked, or previously
+    // used, and may not be used to initiate future payments" (docs.stripe.com/api/mandates/object), refused as
+    // payment_intent_mandate_invalid, "The provided mandate is invalid and can't be used for the payment intent"
+    // (docs.stripe.com/error-codes)
+    const named = typeof params.mandate === 'string' ? params.mandate : typeof existing.mandate === 'string' ? existing.mandate : undefined;
+    if (named && ctx.get('mandate', named)?.status !== 'active')
+        return fail(ctx, 'The provided mandate is invalid and can\'t be used for the payment intent.', 400, 'payment_intent_mandate_invalid');
+    // a declining test card leaves the intent needing a payment method, with the error on it and a 402
+    const decline = declineFor(finder(ctx), params, existing);
+    if (decline) {
+        // Stripe records the attempt: a failed charge the intent's latest_charge names, the declined card on
+        // last_payment_error (a test name made a real PaymentMethod), and no payment_method left on the intent
+        // (docs.stripe.com/payments/paymentintents/lifecycle, docs.stripe.com/declines)
+        const ref = params.payment_method ?? existing.payment_method;
+        let pmId = typeof ref === 'string' ? ref : undefined;
+        if (pmId && !ctx.get('payment_method', pmId) && pmId.startsWith('pm_card_'))
+            pmId = String((await materializeTestMethod(ctx, pmId, typeof existing.customer === 'string' ? existing.customer : null)).id);
+        const pm = pmId ? ctx.get('payment_method', pmId) : undefined;
+        const amount = Number(params.amount ?? existing.amount) || 0;
+        const chargeId = ctx.mint('charge');
+        await created(ctx, 'charge', {
+            id: chargeId, amount, currency: existing.currency ?? 'usd', payment_intent: id,
+            ...(typeof existing.customer === 'string' ? { customer: existing.customer } : {}),
+            ...(pmId ? { payment_method: pmId } : {}),
+            ...intentCarries({ ...existing, ...params }),
+        }, {
+            ...chargeDefaults(chargeId, 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.' },
+            payment_method_details: pmId ? paymentMethodDetails(ctx, pmId) ?? null : null,
+        }, { operation: 'charge.failed' }); // "Occurs whenever a failed charge attempt occurs." (docs.stripe.com/api/events/types)
+        const { payment_method: _pm, ...rest } = params;
+        const last_payment_error = { type: 'card_error', code: decline.code, ...(decline.decline_code ? { decline_code: decline.decline_code } : {}), message: decline.message, param: 'card', charge: chargeId, payment_method: pm ?? null };
+        const failed = await ctx.write(PI, id, { ...rest, payment_method: null, latest_charge: chargeId, status: 'requires_payment_method', last_payment_error }, 'payment_intent.payment_failed');
+        return send(ctx, cardError(decline, { payment_intent: failed, charge: chargeId }));
+    }
+    // a bank debit that needs micro-deposit verification waits in requires_action
+    const method = typeof params.payment_method === 'string' ? params.payment_method : typeof existing.payment_method === 'string' ? existing.payment_method : undefined;
+    // a bank transfer is paid from the customer's cash balance, or waits for the transfer (fundFromCashBalance)
+    if (method && ctx.get('payment_method', method)?.type === 'customer_balance')
+        return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, { ...existing, ...params }, params)));
+    if (requiresMicrodeposits(params, existing) || microdepositsAsked(ctx, params, existing, method)) {
+        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: microdepositsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
+    }
+    // 3DS: the first confirm asks for authentication; a second one completes it
+    if (existing.status !== 'requires_action' && requiresAuthentication(params, existing)) {
+        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: threeDsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
+    }
+    // manual capture authorizes and waits for /capture: the authorization is a charge, succeeded and not captured, the
+    // intent's latest_charge
+    if ((params.capture_method ?? existing.capture_method) === 'manual') {
+        const amount = Number(existing.amount ?? params.amount ?? 0);
+        const charge = await authorizeCharge(ctx, id, { ...existing, ...params }, amount);
+        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_capture', amount_capturable: amount, amount_received: 0, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.amount_capturable_updated')));
+    }
+    // a bank debit is submitted and settles later (beginBankDebit)
+    if (isBankDebit(ctx, method))
+        return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, id, params)));
+    const amount = Number(existing.amount ?? params.amount ?? 0);
+    // a succeeded intent has a Charge, and latest_charge names it: what a refund of it lands on
+    const charge = await mintCharge(ctx, id, { ...existing, ...params }, amount);
+    const body = await ctx.write(PI, id, { ...params, status: 'succeeded', amount_received: amount, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.confirm');
+    await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentConfirm');
+    return ctx.reply(ctx.expand(PI, body));
+}
+const capture = async (ctx) => {
+    const loaded = load(ctx, 'PostPaymentIntentsIntentCapture');
+    if ('answer' in loaded)
+        return loaded.answer;
+    const pi = loaded.pi;
+    const authorized = Number(pi.amount_capturable ?? pi.amount ?? 0);
+    // amount_to_capture lowers the captured amount (a partial capture); it never raises it
+    const asked = ctx.params.amount_to_capture !== undefined ? Math.max(0, Math.trunc(Number(ctx.params.amount_to_capture) || 0)) : authorized;
+    const captured = Math.min(asked, authorized);
+    // the authorization confirm made is captured; an intent authorized before it was kept is charged as before
+    const auth = typeof pi.latest_charge === 'string' ? ctx.get('charge', pi.latest_charge) : undefined;
+    const held = auth && auth.status === 'succeeded' && auth.captured === false ? auth : undefined;
+    if (held) {
+        const refused = ctx.legal('charge', 'captured', 'PostPaymentIntentsIntentCapture', 'false', 'true', String(held.id));
+        if (refused)
+            return ctx.refuse(refused);
+        await captureAuthorization(ctx, held, captured, 'PostPaymentIntentsIntentCapture');
+        await afterCharge(ctx, String(held.id), { amount: captured, currency: String(pi.currency ?? 'usd'), payment_intent: String(pi.id), application_fee_amount: pi.application_fee_amount, destination: pi.transfer_data?.destination }, pi.payment_method);
+    }
+    const charge = held ? String(held.id) : await mintCharge(ctx, String(pi.id), pi, captured);
+    const body = await ctx.write(PI, String(pi.id), { status: 'succeeded', amount_received: captured, amount_capturable: 0, latest_charge: charge }, 'payment_intent.succeeded');
+    await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentCapture');
+    return ctx.reply(ctx.expand(PI, body));
+};
+/** An increment that does not raise the authorization. */
+function incrementTooSmall(ctx) {
+    return ctx.refuse({ status: 400, code: 'parameter_invalid_integer', message: 'The new amount must be greater than the current amount of the PaymentIntent.' });
+}
+const incrementAuthorization = async (ctx) => {
+    const loaded = load(ctx, 'PostPaymentIntentsIntentIncrementAuthorization');
+    if ('answer' in loaded)
+        return loaded.answer;
+    const pi = loaded.pi;
+    if (ctx.params.amount === undefined)
+        return ctx.refuse({ status: 400, code: 'parameter_missing', message: 'Missing required param: amount.' });
+    const amount = Math.trunc(Number(ctx.params.amount) || 0);
+    if (!Number.isInteger(amount) || amount <= Number(pi.amount ?? 0))
+        return incrementTooSmall(ctx);
+    // the authorization the charge holds grows with it: "If the incremental authorization fails ... no other fields on
+    // the PaymentIntent or Charge update" (docs.stripe.com/api/payment_intents/increment_authorization), so on success the
+    // charge's amount is the new authorized amount. Where the documentation stops and the twin decides: the charge's
+    // update sends no event of its own (the events page names none for it).
+    const held = typeof pi.latest_charge === 'string' ? ctx.get('charge', pi.latest_charge) : undefined;
+    if (held && held.captured === false)
+        await ctx.write('charge', String(held.id), { amount }, 'charge.authorization_incremented');
+    return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(pi.id), { amount, amount_capturable: amount }, 'payment_intent.amount_capturable_updated')));
+};
+const cancel = async (ctx) => {
+    const loaded = load(ctx, 'PostPaymentIntentsIntentCancel');
+    if ('answer' in loaded)
+        return loaded.answer;
+    const cancellation_reason = typeof ctx.params.cancellation_reason === 'string' ? ctx.params.cancellation_reason : 'requested_by_customer';
+    // "For PaymentIntents with a `status` of `requires_capture`, the remaining `amount_capturable` is automatically
+    // refunded" (docs.stripe.com/api/payment_intents/cancel): the authorization is released (charges.ts)
+    const held = loaded.pi.status === 'requires_capture' && typeof loaded.pi.latest_charge === 'string' ? ctx.get('charge', loaded.pi.latest_charge) : undefined;
+    if (held && held.captured === false && held.refunded !== true)
+        await cancelAuthorization(ctx, held);
+    return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(loaded.pi.id), { status: 'canceled', cancellation_reason, amount_capturable: 0 }, 'payment_intent.canceled')));
+};
+const verifyMicrodepositsHandler = async (ctx) => {
+    const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
+    if (!pi)
+        return ctx.notFound(PI, String(ctx.id));
+    // the deposit amounts are checked before the intent's state, as Stripe does
+    const wrong = verifyMicrodeposits(ctx.params, pi);
+    if (wrong)
+        return send(ctx, wrong);
+    const refusal = ctx.legal(PI, 'status', 'PostPaymentIntentsIntentVerifyMicrodeposits', pi.status);
+    if (refusal)
+        return ctx.refuse(refusal);
+    const amount = Number(pi.amount) || 0;
+    // a debit saved for reuse ("If you want to reuse the payment method in the future, provide the setup_future_usage
+    // parameter with the value of off_session", the ACH page) is authorized for many payments (multi_use, "Represents
+    // permission given for multiple payments"); else for this one (single_use, "a one-time permission given for a single
+    // payment", docs.stripe.com/api/mandates/object)
+    const reuse = pi.setup_future_usage === 'off_session' || pi.setup_future_usage === 'on_session';
+    const mandate = reuse ? await mintMandate(ctx, pi.payment_method, 'multi_use') : await mintMandate(ctx, pi.payment_method, 'single_use', amount, String(pi.currency ?? 'usd'));
+    // "When the bank account is successfully verified, Stripe returns the PaymentIntent object with a status of
+    // `processing`" (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api)
+    return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, String(pi.id), { mandate })));
+};
+// ── a bank debit is submitted, and settles ──
+//
+// ACH Direct Debit "is a delayed notification payment method ... The PaymentIntent you create initially has a status
+// of `processing`. After the payment has succeeded, the PaymentIntent status is updated from `processing` to
+// `succeeded`"; verification by micro-deposits returns "a status of `processing`, and sends a payment_intent.processing
+// webhook event"; and, the twin being a test-mode account: "Test transactions settle instantly and are added to your
+// available test balance. This behavior differs from live mode, where transactions can take multiple days to settle"
+// (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api). A confirm answers processing; the
+// debit succeeds at that same instant of the World's clock, caught up before the next request is answered (as
+// renewals and payouts are). The page's test accounts give each debit its outcome: pm_usBankAccount_success
+// (000123456789) "The payment succeeds"; pm_usBankAccount_processing (000000000009) "The payment stays in processing
+// indefinitely". Where the documentation stops and the twin decides: its Charge is made when it succeeds (the page
+// names none while it processes); the failing test accounts (closed, no account, insufficient funds, debit not
+// authorized, invalid currency, dispute, weekly limit, Radar block) are not modelled and succeed.
+/** Whether the method an intent is confirmed with is a bank debit: a us_bank_account PaymentMethod, or one of Stripe's
+ *  test bank accounts named as one (pm_usBankAccount_*, pm_us_bank_account). */
+export function isBankDebit(ctx, method) {
+    if (typeof method !== 'string')
+        return false;
+    return ctx.get('payment_method', method)?.type === 'us_bank_account' || /^pm_us_?bank_?account/i.test(method);
+}
+/** Whether a bank debit stays processing: the page's pm_usBankAccount_processing, or its account 000000000009. */
+function staysProcessing(ctx, method) {
+    if (method === 'pm_usBankAccount_processing')
+        return true;
+    const bank = typeof method === 'string' ? ctx.get('payment_method', method)?.us_bank_account : undefined;
+    return bank?.last4 === '0009';
+}
+/** A bank debit submitted: the intent processes, nothing received yet, sent as payment_intent.processing; it is due to
+ *  settle at this instant, unless its test account stays processing. */
+async function beginBankDebit(ctx, id, fields) {
+    const method = fields.payment_method ?? ctx.get(PI, id)?.payment_method;
+    return ctx.write(PI, id, { ...fields, status: 'processing', amount_received: 0, next_action: null, last_payment_error: null, _settles_at: staysProcessing(ctx, method) ? null : Number(ctx.now()) }, 'payment_intent.processing');
+}
+/** Time's settling of bank debits, caught up to the World's clock: each processing debit whose moment has come succeeds
+ *  then, its Charge made (naming the mandate it ran under) and the invoice it collects for paid. */
+export async function settleBankDebits(ctx) {
+    const now = Number(ctx.now());
+    const due = ctx.rowsRaw(PI).filter((p) => p.status === 'processing' && typeof p._settles_at === 'number' && p._settles_at <= now).sort((a, b) => Number(a._settles_at) - Number(b._settles_at));
+    for (const pi of due) {
+        const id = String(pi.id);
+        const c = await at_(ctx)(Number(pi._settles_at));
+        c.legal(PI, 'status', ctx.call.operation.id, 'processing', 'succeeded', id, 'vendor');
+        const amount = Number(pi.amount) || 0;
+        const charge = await mintCharge(c, id, pi, amount);
+        // the charge names the mandate its bank debit ran under (payment_method_details.us_bank_account.mandate)
+        const details = (c.get('charge', charge)?.payment_method_details ?? null);
+        const kind = typeof details?.type === 'string' ? details.type : undefined;
+        if (details && kind && typeof pi.mandate === 'string')
+            await c.write('charge', charge, { payment_method_details: { ...details, [kind]: { ...(details[kind] ?? {}), mandate: pi.mandate } } }, 'charge.mandate');
+        const body = await c.write(PI, id, { status: 'succeeded', amount_received: amount, latest_charge: charge, _settles_at: null }, 'payment_intent.succeeded');
+        // a single-use mandate is spent by its payment: "previously used, and may not be used to initiate future payments"
+        const used = typeof pi.mandate === 'string' ? c.get('mandate', pi.mandate) : undefined;
+        if (used && used.type === 'single_use' && used.status === 'active') {
+            c.legal('mandate', 'status', ctx.call.operation.id, 'active', 'inactive', String(used.id), 'vendor');
+            await c.write('mandate', String(used.id), { status: 'inactive' }, 'mandate.updated');
+        }
+        await payInvoiceOf(c, body, ctx.call.operation.id, 'vendor');
+    }
+}
+/** A customer_balance intent funded from the customer's cash balance: paid when the balance covers it ("If the customer
+ *  already has a balance high enough to cover the payment amount, the PaymentIntent immediately succeeds"), else
+ *  waiting for a transfer: "If the customer balance isn’t high enough to cover the request amount, the PaymentIntent
+ *  shows a requires_action status ... next_action ... display_bank_transfer_instructions" with the amount_remaining
+ *  (docs.stripe.com/payments/bank-transfers/accept-a-payment). Answers the intent as written. */
+async function fundFromCashBalance(ctx, pi, fields = {}) {
+    const customer = typeof pi.customer === 'string' ? pi.customer : '';
+    const currency = String(pi.currency ?? 'usd');
+    // what the customer's funded cash balance holds in this currency, from its ledger
+    const available = customer ? ctx.rows('customer_cash_balance_transaction').filter((t) => t.customer === customer && String(t.currency) === currency).reduce((n, t) => n + (Number(t.net_amount) || 0), 0) : 0;
+    const amount = Number(pi.amount) || 0;
+    if (available >= amount) {
+        // the balance pays the intent: its ledger records what was applied
+        await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'applied_to_payment', net_amount: -amount, ending_balance: available - amount, applied_to_payment: { payment_intent: String(pi.id) }, livemode: false });
+        const charge = await mintCharge(ctx, String(pi.id), { ...pi, ...fields }, amount);
+        return ctx.write(PI, String(pi.id), { ...fields, status: 'succeeded', next_action: null, amount_received: amount, last_payment_error: null, latest_charge: charge }, 'payment_intent.succeeded');
+    }
+    // not enough yet: the intent waits for the rest, with the instructions to send it
+    const next_action = { type: 'display_bank_transfer_instructions', display_bank_transfer_instructions: { amount_remaining: amount - available, currency, type: 'us_bank_transfer' } };
+    return ctx.write(PI, String(pi.id), { ...fields, status: 'requires_action', next_action }, 'payment_intent.requires_action');
+}
+const applyCustomerBalance = async (ctx) => {
+    const loaded = load(ctx, 'PostPaymentIntentsIntentApplyCustomerBalance');
+    if ('answer' in loaded)
+        return loaded.answer;
+    return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, loaded.pi)));
+};
+export const paymentIntents = {
+    PostPaymentIntents: create,
+    GetPaymentIntentsSearch: async (ctx) => search(ctx, PI),
+    PostPaymentIntentsIntentConfirm: confirm,
+    PostPaymentIntentsIntentCapture: capture,
+    PostPaymentIntentsIntentIncrementAuthorization: incrementAuthorization,
+    PostPaymentIntentsIntentCancel: cancel,
+    PostPaymentIntentsIntentVerifyMicrodeposits: verifyMicrodepositsHandler,
+    PostPaymentIntentsIntentApplyCustomerBalance: applyCustomerBalance,
+};

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

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