@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/semantics/transfers.js

@@ -0,0 +1,154 @@
+import { validateMoney } from "../stripe-twin.js";
+import { refusePayout, settleTransfer, settleTransferReversal } from "./ledger.js";
+import { at, created, fail, list, newest, send } from "./shared.js";
+const transferMissing = (ctx, id) => fail(ctx, `No such transfer: '${id}'`, 404, 'resource_missing');
+const emptyList = (url) => ({ object: 'list', data: [], has_more: false, total_count: 0, url });
+/** A transfer to an account whose transfers capability is not active. */
+function transfersInactive(ctx) {
+    return ctx.refuse({ status: 400, code: 'insufficient_capabilities_for_transfer', param: 'destination', message: 'Your destination account needs to have at least one of the following capabilities enabled: transfers, crypto_transfers, legacy_payments' });
+}
+const create = async (ctx) => {
+    const bad = validateMoney(ctx.params);
+    if (bad)
+        return send(ctx, bad);
+    const destination = typeof ctx.params.destination === 'string' ? ctx.params.destination : '';
+    if (!destination)
+        return fail(ctx, 'Missing required param: destination.', 400, 'parameter_missing');
+    const account = ctx.get('account', destination);
+    if (!account)
+        return fail(ctx, `No such destination: '${destination}'`, 400, 'resource_missing');
+    if ((account.capabilities?.transfers) !== 'active')
+        return transfersInactive(ctx);
+    const amount = Math.trunc(Number(ctx.params.amount) || 0);
+    const currency = String(ctx.params.currency ?? 'usd');
+    const sourceId = typeof ctx.params.source_transaction === 'string' ? ctx.params.source_transaction : undefined;
+    let availableOn;
+    let group;
+    if (sourceId) {
+        const charge = ctx.get('charge', sourceId);
+        if (!charge)
+            return fail(ctx, `No such charge: '${sourceId}'`, 400, 'resource_missing');
+        if (charge.status !== 'succeeded')
+            return fail(ctx, `The source_transaction ${sourceId} has not succeeded.`, 400, 'invalid_request_error');
+        // an authorization holds no funds to transfer
+        if (charge.captured === false)
+            return fail(ctx, `The source_transaction ${sourceId} has not been captured; capture it before transferring its funds.`, 400);
+        if (String(charge.currency ?? 'usd') !== currency)
+            return fail(ctx, `The currency of source_transaction ${sourceId} (${String(charge.currency)}) does not match the transfer's (${currency}).`, 400, 'invalid_request_error');
+        const already = ctx.rowsRaw('transfer').filter((t) => t.source_transaction === sourceId).reduce((sum, t) => sum + (Number(t.amount) || 0) - (Number(t.amount_reversed) || 0), 0);
+        if (already + amount > Number(charge.amount ?? 0))
+            return fail(ctx, `The transfers from source_transaction ${sourceId} would exceed its amount (${String(charge.amount)}).`, 400, 'invalid_request_error');
+        const bt = typeof charge.balance_transaction === 'string' ? ctx.get('balance_transaction', charge.balance_transaction) : undefined;
+        // a charge that has settled waives nothing: the transfer comes out of what is available
+        const settledRefusal = bt && Number(bt.available_on) <= Number(ctx.now()) ? settledSourceRefused(ctx, amount, currency) : undefined;
+        if (settledRefusal)
+            return settledRefusal;
+        availableOn = Math.max(Number(ctx.now()), Number(bt?.available_on) || 0);
+        group = typeof charge.transfer_group === 'string' ? charge.transfer_group : typeof charge.payment_intent === 'string' ? `group_${charge.payment_intent}` : undefined;
+        // the generated group is the charge's too
+        if (group && charge.transfer_group !== group)
+            await ctx.write('charge', sourceId, { transfer_group: group }, 'charge.transfer_group_assigned');
+    }
+    else {
+        const refused = refusePayout(ctx, amount, currency, undefined);
+        if (refused)
+            return refused;
+    }
+    const id = ctx.mint('transfer');
+    const bt = await settleTransfer(ctx, id, amount, currency, destination, availableOn ?? Number(ctx.now()), 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,
+        reversals: emptyList(`/v1/transfers/${id}/reversals`),
+        destination_payment: `py_${id.replace(/^tr_/, '')}`,
+    }));
+};
+/** A transfer from a charge whose funds have settled: "With a source_transaction, the transfer request returns success
+ *  regardless of your available balance if the related charge hasn't settled yet" (docs.stripe.com/connect/separate-
+ *  charges-and-transfers), so a settled one comes out of the available balance. */
+function settledSourceRefused(ctx, amount, currency) {
+    return refusePayout(ctx, amount, currency, undefined);
+}
+/** An application fee refunded to its whole through its own refunds endpoint: the fee machine's move, or its refusal. */
+function feeFullyRefunded(ctx, resource, flag, id) {
+    const refused = ctx.legal(resource, flag, ctx.call.operation.id, 'false', 'true', id);
+    return refused ? ctx.refuse(refused) : undefined;
+}
+/** Take `amount` (the remainder by default) back out of a parent's total, as a child row appended to its list. */
+async function giveBack(ctx, o) {
+    const id = String(o.parent.id);
+    const total = Number(o.parent.amount ?? 0);
+    const already = Number(o.parent[o.doneField] ?? 0);
+    const remaining = total - already;
+    const amount = ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : remaining;
+    if (amount <= 0 || amount > remaining)
+        return fail(ctx, o.tooLarge(remaining), 400, 'amount_too_large');
+    const done = already + amount;
+    // a fee refunded in full is `refunded`: the application fee machine's move (a transfer's `reversed` is no state)
+    const feeRefusal = o.parentResource === 'application_fee' && done >= total && o.parent[o.flag] !== true ? feeFullyRefunded(ctx, o.parentResource, o.flag, id) : undefined;
+    if (feeRefusal)
+        return feeRefusal;
+    // the `metadata` a reversal or a fee refund is created with is its own ("Set of key-value pairs that you can attach to
+    // an object", docs.stripe.com/api/transfer_reversals/create, docs.stripe.com/api/fee_refunds/create)
+    const metadata = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? { metadata: ctx.params.metadata } : {};
+    const child = await created(ctx, o.child, { ...o.childFields(amount), ...metadata }, o.childDefaults);
+    if (o.settle)
+        await o.settle(child, amount);
+    const existing = o.parent[o.flag === 'reversed' ? 'reversals' : 'refunds'] ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+    const data = [...(existing.data ?? []), child];
+    await ctx.write(o.parentResource, id, {
+        [o.doneField]: done, [o.flag]: done >= total,
+        [o.flag === 'reversed' ? 'reversals' : 'refunds']: { ...existing, data, total_count: data.length, url: o.listUrl },
+    }, o.op);
+    return ctx.reply(child);
+}
+const reverse = async (ctx) => {
+    const id = at(ctx, 'id');
+    const tr = ctx.get('transfer', id);
+    if (!tr)
+        return transferMissing(ctx, id);
+    return giveBack(ctx, {
+        parent: tr, parentResource: 'transfer', child: 'transfer_reversal',
+        childFields: (amount) => ({ amount, currency: tr.currency ?? 'usd', transfer: id }),
+        childDefaults: { balance_transaction: null, destination_payment_refund: null, source_refund: null, metadata: {} },
+        doneField: 'amount_reversed', flag: 'reversed', listUrl: `/v1/transfers/${id}/reversals`, op: 'transfer.reversed',
+        tooLarge: (remaining) => `Transfer ${id} can only be reversed up to ${remaining}.`,
+        settle: async (child, amount) => {
+            const bt = await settleTransferReversal(ctx, String(child.id), amount, String(tr.currency ?? 'usd'), String(tr.destination));
+            await ctx.write('transfer_reversal', String(child.id), { balance_transaction: bt }, 'transfer_reversal.updated');
+        },
+    });
+};
+const reversals = async (ctx) => {
+    const id = at(ctx, 'id');
+    if (!ctx.get('transfer', id))
+        return transferMissing(ctx, id);
+    return list(ctx, 'transfer_reversal', newest(ctx, 'transfer_reversal').filter((r) => r.transfer === id));
+};
+const feeMissing = (ctx, id) => fail(ctx, `No such application fee: '${id}'`, 404, 'resource_missing');
+const refundFee = async (ctx) => {
+    const id = at(ctx, 'id');
+    const fee = ctx.get('application_fee', id);
+    if (!fee)
+        return feeMissing(ctx, id);
+    return giveBack(ctx, {
+        parent: fee, parentResource: 'application_fee', child: 'fee_refund',
+        childFields: (amount) => ({ amount, currency: fee.currency ?? 'usd', fee: id }),
+        childDefaults: { balance_transaction: null, metadata: {} },
+        doneField: 'amount_refunded', flag: 'refunded', listUrl: `/v1/application_fees/${id}/refunds`, op: 'application_fee.refunded',
+        tooLarge: (remaining) => `Application fee ${id} can only be refunded up to ${remaining}.`,
+    });
+};
+const feeRefunds = async (ctx) => {
+    const id = at(ctx, 'id');
+    if (!ctx.get('application_fee', id))
+        return feeMissing(ctx, id);
+    return list(ctx, 'fee_refund', newest(ctx, 'fee_refund').filter((r) => r.fee === id));
+};
+export const transfers = {
+    PostTransfers: create,
+    PostTransfersIdReversals: reverse,
+    GetTransfersIdReversals: reversals,
+    PostApplicationFeesIdRefunds: refundFee,
+    GetApplicationFeesIdRefunds: feeRefunds,
+};

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

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

package/dist/src/semantics/treasury.js

@@ -0,0 +1,377 @@
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,85 @@
+// 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,
+};