@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/semantics/treasury.js

@@ -1,377 +0,0 @@
-import { PLATFORM_ACCOUNT_ID, validateMoney } from "../stripe-twin.js";
-import { at, created, fail, list, newest, send, where } from "./shared.js";
-const FA = 'treasury.financial_account';
-const TX = 'treasury.transaction';
-const ENTRY = 'treasury.transaction_entry';
-const ENTRY_TYPES = new Set(['credit_reversal', 'debit_reversal', 'inbound_transfer', 'inbound_transfer_return', 'issuing_authorization_hold', 'issuing_authorization_release', 'outbound_payment', 'outbound_transfer', 'received_credit', 'received_debit']);
-const faMissing = (ctx, id, status = 404) => fail(ctx, `No such financial account: '${id}'`, status, 'resource_missing');
-const metadataOf = (ctx) => (ctx.params.metadata && typeof ctx.params.metadata === 'object' ? ctx.params.metadata : {});
-/** A financial account's features as the served spec's treasury.financial_account_features gives them: a toggle
- *  (card_issuing, deposit_insurance, intra_stripe_flows) or a feature per network (financial_addresses.aba,
- *  inbound_transfers.ach, outbound_payments.ach and .us_domestic_wire, outbound_transfers likewise), each
- *  { requested, status, status_details }. What a request asks for is laid over what the account had. Where the
- *  documentation stops and the twin decides: a requested feature is active at once (test mode), and one never requested
- *  is left out (each is optional in the served spec). Answers the features and the active features' paths. */
-const NETWORKS = { financial_addresses: ['aba'], inbound_transfers: ['ach'], outbound_payments: ['ach', 'us_domestic_wire'], outbound_transfers: ['ach', 'us_domestic_wire'] };
-const TOGGLES = ['card_issuing', 'deposit_insurance', 'intra_stripe_flows'];
-function featuresOf(requested, had = {}) {
-    const on = (v) => v === true || v === 'true';
-    const setting = (asked) => ({ requested: asked, status: asked ? 'active' : 'restricted', status_details: [] });
-    const features = { ...had };
-    for (const t of TOGGLES) {
-        const r = requested[t];
-        if (r && typeof r === 'object' && r.requested !== undefined)
-            features[t] = setting(on(r.requested));
-    }
-    for (const [f, nets] of Object.entries(NETWORKS)) {
-        const r = requested[f];
-        if (!r || typeof r !== 'object')
-            continue;
-        const current = features[f] ?? {};
-        const next = { ...current };
-        for (const n of nets) {
-            const nr = r[n];
-            if (nr && typeof nr === 'object' && nr.requested !== undefined)
-                next[n] = setting(on(nr.requested));
-        }
-        features[f] = next;
-    }
-    const active = [];
-    for (const t of TOGGLES)
-        if (features[t]?.status === 'active')
-            active.push(t);
-    for (const [f, nets] of Object.entries(NETWORKS))
-        for (const n of nets)
-            if (features[f]?.[n]?.status === 'active')
-                active.push(`${f}.${n}`);
-    return { features, active };
-}
-/** The account's bank address once financial_addresses.aba is active: "The FinancialAccount gains a FinancialAddress
- *  when the `financial_addresses.aba` feature is active", and "A FinancialAddress is not added until the
- *  financial_addresses.aba feature has been activated" (docs.stripe.com/treasury/account-management/financial-accounts),
- *  whose test example answers "bank_name": "Stripe Test Bank", "routing_number": "000000001" and the networks "ach",
- *  "us_domestic_wire", "rtp"; "The full account_number is only returned if the request expands it" (the same page).
- *  Where the documentation stops and the twin decides: the account number is ten digits drawn from the account's id,
- *  answered by its last four (the full number is null: expanding it is not modelled), and the holder's name is the
- *  platform account's business name, its dashboard name or, with neither, its id. */
-function abaAddress(ctx, faId) {
-    let n = 0;
-    for (const ch of faId)
-        n = (n * 31 + ch.charCodeAt(0)) % 10_000_000_000;
-    const number = String(n).padStart(10, '0');
-    const platform = ctx.get('account', PLATFORM_ACCOUNT_ID);
-    const name = (platform?.business_profile?.name ?? platform?.settings?.dashboard?.display_name ?? PLATFORM_ACCOUNT_ID);
-    return { type: 'aba', supported_networks: ['ach', 'us_domestic_wire', 'rtp'], aba: { account_holder_name: name, account_number: null, account_number_last4: number.slice(-4), bank_name: 'Stripe Test Bank', routing_number: '000000001' } };
-}
-const addressesOf = (ctx, faId, active) => (active.includes('financial_addresses.aba') ? [abaAddress(ctx, faId)] : []);
-// an account opens with a zero balance in each supported currency and the requested features active
-const open = async (ctx) => {
-    const p = ctx.params;
-    const currencies = Array.isArray(p.supported_currencies) ? p.supported_currencies.map(String) : typeof p.supported_currencies === 'string' ? [p.supported_currencies] : [];
-    if (currencies.length === 0)
-        return fail(ctx, 'Missing required param: supported_currencies.', 400, 'parameter_missing');
-    const requested = p.features && typeof p.features === 'object' ? p.features : {};
-    const { features, active } = featuresOf(requested);
-    const zero = Object.fromEntries(currencies.map((c) => [c, 0]));
-    const id = ctx.mint(FA);
-    return ctx.reply(await created(ctx, FA, { id }, {
-        livemode: false, status: 'open', country: p.country ?? 'US',
-        supported_currencies: currencies, active_features: active, pending_features: [], restricted_features: [],
-        features, balance: { cash: zero, inbound_pending: zero, outbound_pending: zero },
-        financial_addresses: addressesOf(ctx, id, active), platform_restrictions: null,
-        status_details: { closed: null },
-        metadata: metadataOf(ctx),
-    }));
-};
-// reading the features answers them; updating them lays the request over them (featuresOf)
-const features = async (ctx) => {
-    const id = at(ctx, 'financial_account');
-    const f = ctx.get(FA, id);
-    if (!f)
-        return faMissing(ctx, id);
-    if (ctx.call.request.method === 'GET')
-        return ctx.reply({ object: 'treasury.financial_account_features', ...f.features });
-    const next = featuresOf(ctx.params, f.features ?? {});
-    const updated = await ctx.write(FA, id, { features: next.features, active_features: next.active, financial_addresses: addressesOf(ctx, id, next.active) }, 'financial_account.features_updated');
-    return ctx.reply({ object: 'treasury.financial_account_features', ...updated.features });
-};
-// only metadata and platform restrictions change
-const updateAccount = async (ctx) => {
-    const id = at(ctx, 'financial_account');
-    if (!ctx.get(FA, id))
-        return faMissing(ctx, id);
-    const patch = {};
-    if (ctx.params.metadata !== undefined)
-        patch.metadata = ctx.params.metadata;
-    if (ctx.params.platform_restrictions !== undefined)
-        patch.platform_restrictions = ctx.params.platform_restrictions;
-    return ctx.reply(await ctx.write(FA, id, patch, 'financial_account.updated'));
-};
-/** Post a flow's double entry: a ledger transaction with its net balance impact, and its one entry. */
-async function post(ctx, o) {
-    const now = ctx.now();
-    const txnId = ctx.mint(TX);
-    await ctx.write(TX, txnId, {
-        object: 'treasury.transaction', created: now, livemode: false,
-        amount: o.amount, currency: o.currency, financial_account: o.financial_account,
-        flow: o.flow, flow_type: o.flow_type, flow_details: null,
-        status: o.status, balance_impact: o.balance_impact, description: o.description,
-        entries: { object: 'list', has_more: false, url: `/v1/treasury/transaction_entries?transaction=${txnId}`, data: [] },
-        status_transitions: { posted_at: o.status === 'posted' ? now : null, void_at: null },
-    }, 'treasury_transaction.created');
-    await ctx.write(ENTRY, ctx.mint(ENTRY), {
-        object: 'treasury.transaction_entry', created: now, livemode: false,
-        amount: o.amount, currency: o.currency, financial_account: o.financial_account,
-        flow: o.flow, flow_type: o.flow_type,
-        flow_details: o.flowDetailKey ? { type: o.flowDetailKey, [o.flowDetailKey]: o.flow } : null,
-        transaction: txnId, effective_at: now,
-        balance_impact: o.balance_impact,
-        // what the entry records: its flow's kind where Stripe names one (docs.stripe.com/api/treasury/transaction_entries/object);
-        // a vendor `type`, kept apart from the kernel's row type
-        _stripe_type: ENTRY_TYPES.has(String(o.flow_type)) ? o.flow_type : 'other',
-    }, 'treasury_transaction_entry.created');
-    // the account's balance moves by the entry's impact: cash "Funds the user can spend right now", inbound_pending
-    // "Funds not spendable yet", outbound_pending "held for pending outbound flows" (the served spec's balance)
-    const account = ctx.get(FA, o.financial_account);
-    if (account) {
-        const bal = account.balance ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
-        const moved = Object.fromEntries(['cash', 'inbound_pending', 'outbound_pending'].map((k) => [k, { ...(bal[k] ?? {}), [o.currency]: ((bal[k] ?? {})[o.currency] ?? 0) + (Number(o.balance_impact[k]) || 0) }]));
-        await ctx.write(FA, o.financial_account, { balance: moved }, 'financial_account.balance_updated');
-    }
-    return txnId;
-}
-/** The request's funding account, or the refusal. */
-function fundingAccount(ctx) {
-    const bad = validateMoney(ctx.params);
-    if (bad)
-        return send(ctx, bad);
-    const fa = typeof ctx.params.financial_account === 'string' ? ctx.params.financial_account : '';
-    if (!fa)
-        return fail(ctx, 'Missing required param: financial_account.', 400, 'parameter_missing');
-    return ctx.get(FA, fa) ? fa : faMissing(ctx, fa, 400);
-}
-const noTransitions = { canceled_at: null, failed_at: null, posted_at: null, returned_at: null };
-/** Where an outbound flow sends its money, as the served spec's payment method details give it: the bank account's
- *  holder type, last four digits and routing number from what the request sent (a saved method's, or the test bank's
- *  when none is given), and its billing details (required): the name and email sent, the address lines null where not
- *  given. Where the documentation stops and the twin decides: a saved method's details are the test bank's. */
-function destinationDetails(ctx, dest) {
-    const data = ctx.params.destination_payment_method_data && typeof ctx.params.destination_payment_method_data === 'object' ? ctx.params.destination_payment_method_data : {};
-    const bank = data.us_bank_account && typeof data.us_bank_account === 'object' ? data.us_bank_account : {};
-    const billing = data.billing_details && typeof data.billing_details === 'object' ? data.billing_details : {};
-    const address = billing.address && typeof billing.address === 'object' ? billing.address : {};
-    const number = typeof bank.account_number === 'string' ? bank.account_number.replace(/\D/g, '') : '';
-    const billing_details = { name: billing.name ?? null, email: billing.email ?? null, address: Object.fromEntries(['city', 'country', 'line1', 'line2', 'postal_code', 'state'].map((k) => [k, address[k] ?? null])) };
-    if (dest && data.type === undefined && dest.startsWith('fa_'))
-        return { type: 'financial_account', financial_account: { id: dest, network: 'stripe' }, billing_details };
-    return {
-        type: 'us_bank_account', billing_details,
-        us_bank_account: { last4: number ? number.slice(-4) : '6789', network: 'ach', routing_number: typeof bank.routing_number === 'string' ? bank.routing_number : '110000000', account_holder_type: typeof bank.account_holder_type === 'string' ? bank.account_holder_type : 'individual', account_type: typeof bank.account_type === 'string' ? bank.account_type : 'checking', bank_name: 'STRIPE TEST BANK', mandate: null },
-    };
-}
-/** An outbound payment that names no destination: "You must provide either destination_payment_method or
- *  destination_payment_method_data" (the served spec's outbound payment create). */
-function noDestination(ctx) {
-    return fail(ctx, 'You must provide either `destination_payment_method` or `destination_payment_method_data`.', 400, 'parameter_missing');
-}
-const outboundPayment = async (ctx) => {
-    const fa = fundingAccount(ctx);
-    if (fa instanceof Response)
-        return fa;
-    const dest = typeof ctx.params.destination_payment_method === 'string' ? ctx.params.destination_payment_method : null;
-    if (!dest && !(ctx.params.destination_payment_method_data && typeof ctx.params.destination_payment_method_data === 'object'))
-        return noDestination(ctx);
-    const amount = ctx.params.amount;
-    const currency = String(ctx.params.currency);
-    const id = ctx.mint('treasury.outbound_payment');
-    const txn = await post(ctx, { financial_account: fa, amount: -amount, currency, flow: id, flow_type: 'outbound_payment', status: 'open', balance_impact: { cash: -amount, inbound_pending: 0, outbound_pending: amount }, description: 'OutboundPayment' });
-    return ctx.reply(await created(ctx, 'treasury.outbound_payment', { id }, {
-        amount, currency, financial_account: fa, livemode: false, status: 'processing', cancelable: true,
-        destination_payment_method: dest,
-        destination_payment_method_details: destinationDetails(ctx, dest),
-        destination_payment_method_data: null, end_user_details: null, expected_arrival_date: Number(ctx.now()) + 2 * 86400,
-        hosted_regulatory_receipt_url: null, returned_details: null, statement_descriptor: ctx.params.statement_descriptor ?? 'payment',
-        description: typeof ctx.params.description === 'string' ? ctx.params.description : null, transaction: txn, status_transitions: noTransitions, metadata: metadataOf(ctx),
-    }));
-};
-const outboundTransfer = async (ctx) => {
-    const fa = fundingAccount(ctx);
-    if (fa instanceof Response)
-        return fa;
-    const dest = typeof ctx.params.destination_payment_method === 'string' ? ctx.params.destination_payment_method : null;
-    const amount = ctx.params.amount;
-    const currency = String(ctx.params.currency);
-    const id = ctx.mint('treasury.outbound_transfer');
-    const txn = await post(ctx, { financial_account: fa, amount: -amount, currency, flow: id, flow_type: 'outbound_transfer', status: 'open', balance_impact: { cash: -amount, inbound_pending: 0, outbound_pending: amount }, description: 'OutboundTransfer' });
-    return ctx.reply(await created(ctx, 'treasury.outbound_transfer', { id }, {
-        amount, currency, financial_account: fa, livemode: false, status: 'processing', cancelable: true,
-        destination_payment_method: dest, destination_payment_method_details: destinationDetails(ctx, dest),
-        expected_arrival_date: Number(ctx.now()) + 2 * 86400, hosted_regulatory_receipt_url: null,
-        returned_details: null, statement_descriptor: ctx.params.statement_descriptor ?? 'transfer',
-        description: typeof ctx.params.description === 'string' ? ctx.params.description : null, transaction: txn, status_transitions: noTransitions, metadata: metadataOf(ctx),
-    }));
-};
-/** The bank account an inbound transfer may pull from: "You must first set up the account-attached payment method for
- *  inbound flows and verify the bank account using a SetupIntent", and invalid ones ("of unsupported types, containing
- *  an unverified bank account, or not set up for inbound flows") "throw the same errors as in live mode"
- *  (docs.stripe.com/treasury/moving-money/financial-accounts/into/inbound-transfers). A payment method is set up for
- *  inbound flows by a SetupIntent whose flow_directions holds `inbound`, and verified when that SetupIntent succeeded
- *  ("The bank account has been instantly verified or verification isn't necessary", its `succeeded` status,
- *  docs.stripe.com/treasury/connect/legacy/v1/moving-money/working-with-bankaccount-objects).
- *  Where the documentation stops and the twin decides: the page quotes no error, so the twin answers the documented code
- *  for the class, payment_method_unexpected_state ("The provided payment method's state was incompatible with the
- *  operation you were trying to perform", docs.stripe.com/error-codes), in its own words; an existing verified
- *  BankAccount (`ba_`), which the page also allows, is not checked. Answers the payment method, or the refusal. */
-function inboundOrigin(ctx, origin) {
-    if (origin.startsWith('ba_'))
-        return undefined;
-    const pm = ctx.get('payment_method', origin);
-    if (!pm)
-        return fail(ctx, `No such PaymentMethod: '${origin}'`, 400, 'resource_missing');
-    if (pm.type !== 'us_bank_account')
-        return fail(ctx, `The PaymentMethod '${origin}' is of type ${String(pm.type)}; an InboundTransfer pulls from a us_bank_account.`, 400, 'payment_method_unexpected_state');
-    const setUp = ctx.rows('setup_intent').some((si) => si.payment_method === origin && si.status === 'succeeded' && Array.isArray(si.flow_directions) && si.flow_directions.map(String).includes('inbound'));
-    if (!setUp)
-        return fail(ctx, `The PaymentMethod '${origin}' has not been set up for inbound flows and verified with a SetupIntent.`, 400, 'payment_method_unexpected_state');
-    return pm;
-}
-const inboundTransfer = async (ctx) => {
-    const fa = fundingAccount(ctx);
-    if (fa instanceof Response)
-        return fa;
-    const origin = typeof ctx.params.origin_payment_method === 'string' ? ctx.params.origin_payment_method : '';
-    if (!origin)
-        return fail(ctx, 'Missing required param: origin_payment_method.', 400, 'parameter_missing');
-    const pm = inboundOrigin(ctx, origin);
-    if (pm instanceof Response)
-        return pm;
-    const bank = (pm?.us_bank_account ?? {});
-    const billing = (pm?.billing_details ?? {});
-    // the debit mandate the account's verification made (docs.stripe.com/payments/setup-intents#mandates)
-    const mandate = ctx.rows('setup_intent').find((si) => si.payment_method === origin && si.status === 'succeeded' && typeof si.mandate === 'string')?.mandate;
-    const amount = ctx.params.amount;
-    const currency = String(ctx.params.currency);
-    const id = ctx.mint('treasury.inbound_transfer');
-    // it starts processing, its funds pending inbound, until confirmed (succeedInbound)
-    const txn = await post(ctx, { financial_account: fa, amount, currency, flow: id, flow_type: 'inbound_transfer', status: 'open', balance_impact: { cash: 0, inbound_pending: amount, outbound_pending: 0 }, description: 'InboundTransfer', flowDetailKey: 'inbound_transfer' });
-    return ctx.reply(await created(ctx, 'treasury.inbound_transfer', { id }, {
-        amount, currency, financial_account: fa, origin_payment_method: origin, livemode: false,
-        status: 'processing', cancelable: true, returned: null,
-        // the pulled account as its payment method holds it
-        origin_payment_method_details: {
-            type: 'us_bank_account',
-            us_bank_account: { last4: bank.last4 ?? '6789', routing_number: bank.routing_number ?? '110000000', bank_name: bank.bank_name ?? 'STRIPE TEST BANK', account_holder_type: bank.account_holder_type ?? null, account_type: bank.account_type ?? null, fingerprint: bank.fingerprint ?? null, ...(mandate ? { mandate } : {}), network: 'ach' },
-            billing_details: { address: billing.address ?? {}, email: billing.email ?? null, name: billing.name ?? null },
-        },
-        failure_details: null, hosted_regulatory_receipt_url: null,
-        linked_flows: { received_debit: null }, statement_descriptor: ctx.params.statement_descriptor ?? 'transfer',
-        description: typeof ctx.params.description === 'string' ? ctx.params.description : null, transaction: txn, status_transitions: { succeeded_at: null, failed_at: null, canceled_at: null },
-        metadata: metadataOf(ctx),
-    }));
-};
-// test mode's stand-ins for money another party sends to the account or pulls from it
-// (docs.stripe.com/treasury/moving-money/receiving-funds, docs.stripe.com/api/treasury/received_credits/test_mode_create)
-function received(kind) {
-    return async (ctx) => {
-        const fa = fundingAccount(ctx);
-        if (fa instanceof Response)
-            return fa;
-        const network = typeof ctx.params.network === 'string' ? ctx.params.network : '';
-        if (!['ach', 'us_domestic_wire', 'stripe'].includes(network))
-            return fail(ctx, 'Missing required param: network.', 400, 'parameter_missing');
-        const amount = ctx.params.amount;
-        const currency = String(ctx.params.currency);
-        const id = ctx.mint(`treasury.${kind}`);
-        const signed = kind === 'received_credit' ? amount : -amount;
-        const txn = await post(ctx, { financial_account: fa, amount: signed, currency, flow: id, flow_type: kind, status: 'posted', balance_impact: { cash: signed, inbound_pending: 0, outbound_pending: 0 }, description: kind === 'received_credit' ? 'ReceivedCredit' : 'ReceivedDebit', flowDetailKey: kind });
-        return ctx.reply(await created(ctx, `treasury.${kind}`, { id }, {
-            amount, currency, financial_account: fa, network, livemode: false, status: 'succeeded', failure_code: null,
-            description: typeof ctx.params.description === 'string' ? ctx.params.description : kind === 'received_credit' ? 'Received credit' : 'Received debit',
-            hosted_regulatory_receipt_url: null, transaction: txn, reversal_details: null,
-            initiating_payment_method_details: { type: 'us_bank_account', billing_details: { address: {}, email: null, name: null }, us_bank_account: { bank_name: 'STRIPE TEST BANK', last4: '6789', routing_number: '110000000' } },
-            linked_flows: kind === 'received_credit' ? { credit_reversal: null, issuing_authorization: null, issuing_transaction: null, source_flow: null, source_flow_type: null } : { debit_reversal: null, inbound_transfer: null, issuing_authorization: null, issuing_transaction: null, payout: null },
-        }));
-    };
-}
-/** Test mode's confirmation of a processing inbound transfer: it succeeds, its transaction posts and the pending funds
- *  become cash ("The status changes to succeeded once the funds have been "confirmed" and a transaction is created and
- *  posted", docs.stripe.com/api/treasury/inbound_transfers). */
-const succeedInbound = async (ctx) => {
-    const id = at(ctx, 'id');
-    const flow = ctx.get('treasury.inbound_transfer', id);
-    if (!flow)
-        return fail(ctx, `No such inbound transfer: '${id}'`, 404, 'resource_missing');
-    const refused = ctx.legal('treasury.inbound_transfer', 'status', 'PostTestHelpersTreasuryInboundTransfersIdSucceed', flow.status, 'succeeded', id);
-    if (refused)
-        return ctx.refuse(refused);
-    const txn = typeof flow.transaction === 'string' ? ctx.get(TX, flow.transaction) : undefined;
-    const amount = Number(flow.amount) || 0;
-    const cur = String(flow.currency ?? 'usd');
-    if (txn && txn.status === 'open') {
-        await ctx.write(TX, String(txn.id), { status: 'posted', balance_impact: { cash: amount, inbound_pending: 0, outbound_pending: 0 }, status_transitions: { ...txn.status_transitions, posted_at: ctx.now() } }, 'treasury_transaction.posted');
-        const account = ctx.get(FA, String(txn.financial_account));
-        if (account) {
-            const bal = account.balance ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
-            await ctx.write(FA, String(account.id), { balance: { ...bal, cash: { ...(bal.cash ?? {}), [cur]: ((bal.cash ?? {})[cur] ?? 0) + amount }, inbound_pending: { ...(bal.inbound_pending ?? {}), [cur]: ((bal.inbound_pending ?? {})[cur] ?? 0) - amount } } }, 'financial_account.balance_updated');
-        }
-    }
-    return ctx.reply(await ctx.write('treasury.inbound_transfer', id, { status: 'succeeded', cancelable: false, status_transitions: { ...flow.status_transitions, succeeded_at: ctx.now() } }, 'inbound_transfer.succeeded'));
-};
-/** Cancel a flow still processing; an outbound one must also still be cancelable. */
-function cancel(resource, param, name, operationId, op, checkCancelable) {
-    return async (ctx) => {
-        const id = at(ctx, param);
-        const flow = ctx.get(resource, id);
-        if (!flow)
-            return fail(ctx, `No such ${name}: '${id}'`, 404, 'resource_missing');
-        // a processing flow that is no longer cancelable is refused as one no longer processing
-        const refused = ctx.legal(resource, 'status', operationId, checkCancelable && flow.cancelable !== true ? 'not_cancelable' : flow.status, undefined, id);
-        if (refused)
-            return ctx.refuse(refused);
-        // a canceled flow's open transaction is voided and what it held returns to the account (the reverse of its
-        // balance impact). Where the documentation stops and the twin decides: a flow already posted is only marked canceled
-        const txn = typeof flow.transaction === 'string' ? ctx.get(TX, flow.transaction) : undefined;
-        if (txn && txn.status === 'open') {
-            await ctx.write(TX, String(txn.id), { status: 'void', status_transitions: { ...txn.status_transitions, void_at: ctx.now() } }, 'treasury_transaction.voided');
-            const account = ctx.get(FA, String(txn.financial_account));
-            const impact = txn.balance_impact ?? {};
-            const cur = String(txn.currency ?? 'usd');
-            if (account) {
-                const bal = account.balance ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
-                const back = Object.fromEntries(['cash', 'inbound_pending', 'outbound_pending'].map((k) => [k, { ...(bal[k] ?? {}), [cur]: ((bal[k] ?? {})[cur] ?? 0) - (Number(impact[k]) || 0) }]));
-                await ctx.write(FA, String(account.id), { balance: back }, 'financial_account.balance_updated');
-            }
-        }
-        return ctx.reply(await ctx.write(resource, id, { status: 'canceled', cancelable: false, status_transitions: { ...flow.status_transitions, canceled_at: ctx.now() } }, op));
-    };
-}
-// the ledger is always read for one account
-function ledger(resource, spec) {
-    return async (ctx) => {
-        if (typeof ctx.params.financial_account !== 'string' || !ctx.params.financial_account)
-            return fail(ctx, 'Missing required param: financial_account.', 400, 'parameter_missing');
-        return list(ctx, resource, where(ctx, newest(ctx, resource), spec));
-    };
-}
-export const treasury = {
-    PostTreasuryFinancialAccounts: open,
-    GetTreasuryFinancialAccountsFinancialAccountFeatures: features,
-    PostTreasuryFinancialAccountsFinancialAccountFeatures: features,
-    PostTreasuryFinancialAccountsFinancialAccount: updateAccount,
-    PostTreasuryOutboundPayments: outboundPayment,
-    PostTreasuryOutboundPaymentsIdCancel: cancel('treasury.outbound_payment', 'id', 'outbound payment', 'PostTreasuryOutboundPaymentsIdCancel', 'outbound_payment.canceled', true),
-    PostTreasuryOutboundTransfers: outboundTransfer,
-    PostTreasuryOutboundTransfersOutboundTransferCancel: cancel('treasury.outbound_transfer', 'outbound_transfer', 'outbound transfer', 'PostTreasuryOutboundTransfersOutboundTransferCancel', 'outbound_transfer.canceled', true),
-    PostTreasuryInboundTransfers: inboundTransfer,
-    PostTestHelpersTreasuryInboundTransfersIdSucceed: succeedInbound,
-    PostTestHelpersTreasuryReceivedCredits: received('received_credit'),
-    PostTestHelpersTreasuryReceivedDebits: received('received_debit'),
-    PostTreasuryInboundTransfersInboundTransferCancel: cancel('treasury.inbound_transfer', 'inbound_transfer', 'inbound transfer', 'PostTreasuryInboundTransfersInboundTransferCancel', 'inbound_transfer.canceled', false),
-    GetTreasuryTransactions: ledger(TX, {
-        financial_account: (r, v) => r.financial_account === v, status: (r, v) => r.status === v,
-        flow: (r, v) => r.flow === v, flow_type: (r, v) => r.flow_type === v,
-    }),
-    GetTreasuryTransactionEntries: ledger(ENTRY, {
-        financial_account: (r, v) => r.financial_account === v, flow: (r, v) => r.flow === v, transaction: (r, v) => r.transaction === v,
-    }),
-};

package/dist/src/semantics/webhook-endpoints.d.ts

@@ -1,3 +0,0 @@
-import { type Semantics } from '@volter/world-core';
-export declare function worldEndpointSecret(connect: boolean): string | undefined;
-export declare const webhookEndpoints: Record<string, Semantics>;

package/dist/src/semantics/webhook-endpoints.js

@@ -1,85 +0,0 @@
-// Webhook endpoint semantics: registering a URL and the events it subscribes to. Delivery reads
-// the endpoints from the tree, signing each POST with the endpoint's own secret; a disabled one
-// (the machine in ../manifest.ts) receives nothing. Endpoint list, retrieve and delete are the derived core's.
-//
-// The Events API lists and retrieves the stored events of the account a request acts for: an event of a connected
-// account carries it ("Each event for a connected account contains a top-level `account` property that identifies the
-// connected account. Because the connected account owns the object that triggered the event, you must make API
-// requests for that object as the connected account", docs.stripe.com/connect/webhooks; the event's `account`: "The
-// connected account that originates the event", spec/openapi.json.gz), so a request with the Stripe-Account header
-// sees that account's events and one without it the platform's, those with no `account`. Where the documentation
-// stops and the twin decides: a platform request does not see its connected accounts' events.
-import { worldEnvValue } from '@volter/world-core';
-import { asBool } from "../stripe-twin.js";
-import { actingAccount } from "./ledger.js";
-import { at, created, fail, inRange, list, newest, where } from "./shared.js";
-const WE = 'webhook_endpoint';
-// The signing secret is the World's where the World set one. Stripe mints an endpoint's secret and the app is given it
-// (the dashboard, `stripe listen`); in a World the app's env is the World's, made at boot, so the World's value is the
-// one the app verifies with, and an endpoint the app registers is signed with it: the twin's decision, since Stripe
-// lets no one choose a secret. A Connect endpoint (`connect`) takes a Connect name first. Only a value the World sets
-// counts (worldEnvValue), never one the caller's shell passes through; with none (a twin outside a World) the twin
-// mints, as Stripe does.
-const ACCOUNT_SECRET_ENV = ['STRIPE_WEBHOOK_SECRET', 'STRIPE_WEBHOOK_SIGNING_SECRET', 'STRIPE_ENDPOINT_SECRET', 'STRIPE_WEBHOOK_SECRET_KEY', 'NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET'];
-const CONNECT_SECRET_ENV = ['STRIPE_CONNECT_WEBHOOK_SECRET', 'STRIPE_WEBHOOK_SECRET_CONNECT', 'STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET'];
-export function worldEndpointSecret(connect) {
-    for (const name of connect ? [...CONNECT_SECRET_ENV, ...ACCOUNT_SECRET_ENV] : ACCOUNT_SECRET_ENV) {
-        const value = worldEnvValue(name);
-        if (value)
-            return value;
-    }
-    return undefined;
-}
-const create = async (ctx) => {
-    const params = ctx.params;
-    const url = typeof params.url === 'string' ? params.url : '';
-    if (!url)
-        return fail(ctx, 'Missing required param: url.', 400, 'parameter_missing');
-    const enabledEvents = Array.isArray(params.enabled_events) ? params.enabled_events.map(String) : typeof params.enabled_events === 'string' ? [params.enabled_events] : undefined;
-    if (!enabledEvents || enabledEvents.length === 0)
-        return fail(ctx, 'Missing required param: enabled_events.', 400, 'parameter_missing');
-    const id = ctx.mint(WE);
-    return ctx.reply(await created(ctx, WE, { ...params, id }, {
-        url, enabled_events: enabledEvents, status: 'enabled', livemode: false, metadata: {},
-        api_version: '2024-06-20', application: null, description: typeof params.description === 'string' ? params.description : null,
-        secret: worldEndpointSecret(asBool(params.connect)) ?? `whsec_twin_${id}`,
-    }));
-};
-// `disabled` switches delivery off (status disabled) and back on; it is a parameter, not a field
-const update = async (ctx) => {
-    const id = at(ctx, 'webhook_endpoint');
-    const we = ctx.get(WE, id);
-    if (!we)
-        return ctx.notFound(WE, id);
-    const { disabled, ...fields } = { ...ctx.params };
-    if (Array.isArray(ctx.params.enabled_events))
-        fields.enabled_events = ctx.params.enabled_events.map(String);
-    if (disabled !== undefined)
-        return switchDelivery(ctx, id, we, fields, asBool(disabled));
-    return ctx.reply(await ctx.write(WE, id, fields, 'webhook_endpoint.update'));
-};
-/** `disabled` switches delivery off or back on (docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled). */
-async function switchDelivery(ctx, id, we, fields, off) {
-    const status = off ? 'disabled' : 'enabled';
-    const refused = ctx.legal(WE, 'status', 'PostWebhookEndpointsWebhookEndpoint', we.status, status, id);
-    if (refused)
-        return ctx.refuse(refused);
-    return ctx.reply(await ctx.write(WE, id, { ...fields, status }, 'webhook_endpoint.update'));
-}
-/** Whether a stored event is the acting account's (no `account`: the platform's). */
-const ownEvent = (ctx, e) => (typeof e.account === 'string' ? e.account : undefined) === actingAccount(ctx);
-const listEvents = async (ctx) => list(ctx, 'event', where(ctx, newest(ctx, 'event').filter((e) => ownEvent(ctx, e)), {
-    type: (e, v) => e.type === v,
-    types: (e, v) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String(e.type)),
-    created: (e, v) => inRange(e.created, v),
-}));
-const retrieveEvent = async (ctx) => {
-    const e = ctx.get('event', at(ctx, 'id'));
-    return e && ownEvent(ctx, e) ? ctx.reply(e) : ctx.notFound('event', at(ctx, 'id'));
-};
-export const webhookEndpoints = {
-    GetEvents: listEvents,
-    GetEventsId: retrieveEvent,
-    PostWebhookEndpoints: create,
-    PostWebhookEndpointsWebhookEndpoint: update,
-};

package/dist/src/stripe-budget.d.ts

@@ -1,55 +0,0 @@
-import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
-/** Rolling window, in ms. Spend older than this is pruned. */
-export declare const STRIPE_BUDGET_WINDOW_MS = 60000;
-/**
- * Weighted units allowed inside one window. 120/60s = 120 reads a minute (2/second) — 2% of
- * Stripe's documented live-mode 100/second and 8% of the 25/second a sandbox key or any single
- * endpoint gets.
- */
-export declare const STRIPE_BUDGET_CEILING = 120;
-/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly, don't sleep. */
-export declare const STRIPE_BUDGET_MAX_RETRY_AFTER_S = 300;
-/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
-export declare const STRIPE_CALL_WEIGHTS: {
-    /** `POST /v1/payouts` — documented at 15 creates/second, and the most irreversible object here. */
-    readonly payout: 5;
-    /** Any other `POST`/`DELETE` — creates charges, refunds, subscriptions, receipt e-mail. */
-    readonly write: 2;
-    /** Reads: list/retrieve. */
-    readonly other: 1;
-};
-/** THE PACK'S DECLARATION — pure data, the only Stripe-specific thing in the whole budget. */
-export declare const STRIPE_RATE_BUDGET: RateBudgetDeclaration;
-/**
- * Price one call. The key is `"<METHOD> <path>"` — Stripe's executor carries filters as separate
- * `params` rather than in the path, so there is no query string to split off here; a `?` is still
- * handled defensively in case a caller inlines one. An unclassified endpoint costs `defaultWeight`.
- */
-export declare function stripeCallWeight(method: string, path: string): number;
-/** Where Stripe's ledger lives. Key-keyed and cwd-independent by default (limits attach to the
- *  account behind the secret key, so a cwd-scoped ledger would hand the same key a fresh allowance
- *  in every checkout, worktree and CI matrix leg); pass `root` for world-scoped accounting.
- *
- *  A live key and a test key are different strings, so they get different ledgers — which matches
- *  Stripe, whose live and sandbox limits are separate (100/s vs 25/s). */
-export declare function stripeBudgetPath(opts?: {
-    root?: string;
-    token?: string;
-} | string): string;
-/** Construction options for Stripe's budget. The vendor is fixed; everything else may only TIGHTEN. */
-export type StripeBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
-/**
- * Stripe's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
- * not an alias, so `budget instanceof StripeBudget` in `liveStripeExecute` means "a budget that
- * accounts against STRIPE's ledger under STRIPE's ceiling": another vendor's `RateBudget` (with its
- * own, possibly larger, ceiling) is NOT assignable there.
- */
-export declare class StripeBudget extends RateBudget {
-    constructor(opts?: StripeBudgetOptions);
-}
-/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
- *  which one refused, and `err.kind` says why. */
-export { RateBudgetError as StripeBudgetError } from '@volter/world-core';
-export type { RateBudgetErrorKind as StripeBudgetErrorKind } from '@volter/world-core';
-export type StripeBudgetReservation = RateBudgetReservation;
-export type StripeBudgetSnapshot = RateBudgetSnapshot;