@volter/twin-stripe 2.0.38 → 3.0.0

package/dist/src/semantics/terminal.js

@@ -1,182 +0,0 @@
-import { validateMoney } from "../stripe-twin.js";
-import { settleTopup } from "./ledger.js";
-import { authorizeCharge, mintCharge } from "./payment-intents.js";
-import { at, at_, created, fail, send } from "./shared.js";
-const LOC = 'terminal.location';
-const READER = 'terminal.reader';
-const CONF = 'terminal.configuration';
-/** Update and delete by id, finding tombstones as the hand-written routes did, with Stripe's own operation names. */
-function patch(resource, param, missing, op) {
-    return (ctx) => patchRow(ctx, resource, param, missing, op);
-}
-async function patchRow(ctx, resource, param, missing, op) {
-    const id = at(ctx, param);
-    if (!ctx.row(resource, id, { withDeleted: true }))
-        return fail(ctx, `No such ${missing}: '${id}'`, 404, 'resource_missing');
-    return ctx.reply(await ctx.write(resource, id, ctx.params, op));
-}
-// A reader's update takes its label and metadata only; it moves to another location by registering it
-// there again (https://docs.stripe.com/api/terminal/readers/update, docs.stripe.com/terminal/fleet/locations-and-zones)
-// (the parameter check refuses anything else, as Stripe does: ../stripe-params.ts)
-const updateReader = patch(READER, 'reader', 'reader', 'terminal_reader.updated');
-function remove(resource, param, missing, op, object) {
-    return async (ctx) => {
-        const id = at(ctx, param);
-        if (!ctx.row(resource, id, { withDeleted: true }))
-            return fail(ctx, `No such ${missing}: '${id}'`, 404, 'resource_missing');
-        const row = ctx.get(resource, id);
-        await ctx.write(resource, id, { deleted: true }, op);
-        // a deleted reader still says what device it was
-        return ctx.reply({ id, object, deleted: true, ...(object === 'terminal.reader' && row ? { device_type: row.device_type, serial_number: row.serial_number } : {}) });
-    };
-}
-const createLocation = async (ctx) => {
-    if (ctx.params.display_name === undefined || ctx.params.display_name === '')
-        return fail(ctx, 'Missing required param: display_name.', 400, 'parameter_missing');
-    const addr = ctx.params.address && typeof ctx.params.address === 'object' ? ctx.params.address : undefined;
-    if (!addr || addr.country === undefined || addr.country === '')
-        return fail(ctx, 'Missing required param: address[country].', 400, 'parameter_missing');
-    return ctx.reply(await created(ctx, LOC, ctx.params, { livemode: false, metadata: {} }));
-};
-// a test registration code (simulated-wpe) registers a simulated reader, online
-const createReader = async (ctx) => {
-    if (ctx.params.registration_code === undefined || ctx.params.registration_code === '')
-        return fail(ctx, 'Missing required param: registration_code.', 400, 'parameter_missing');
-    return ctx.reply(await created(ctx, READER, ctx.params, {
-        status: 'online', device_type: 'simulated_wisepos_e', device_sw_version: null, ip_address: '0.0.0.0',
-        serial_number: `STR-${ctx.rowsRaw(READER, { withDeleted: true }).length + 1}`, action: null,
-        livemode: false, metadata: {}, label: ctx.params.label ?? 'Twin Reader',
-    }));
-};
-const readerMissing = (ctx, id) => fail(ctx, `No such reader: '${id}'`, 404, 'resource_missing');
-// handing the reader a PaymentIntent puts it in an in-progress process_payment_intent action
-const processPaymentIntent = async (ctx) => {
-    const id = at(ctx, 'reader');
-    if (!ctx.get(READER, id))
-        return readerMissing(ctx, id);
-    const pi = typeof ctx.params.payment_intent === 'string' ? ctx.params.payment_intent : '';
-    if (!pi)
-        return fail(ctx, 'Missing required param: payment_intent.', 400, 'parameter_missing');
-    if (!ctx.get('payment_intent', pi))
-        return fail(ctx, `No such payment_intent: '${pi}'`, 400, 'resource_missing');
-    const action = { type: 'process_payment_intent', status: 'in_progress', failure_code: null, failure_message: null, process_payment_intent: { payment_intent: pi } };
-    return ctx.reply(await ctx.write(READER, id, { action }, 'terminal_reader.updated'));
-};
-/** A card presented to a reader with no payment in progress. */
-function nothingToPresent(ctx) {
-    return fail(ctx, 'This reader has no in-progress payment to present a payment method to.', 400, 'terminal_reader_invalid_state');
-}
-/** Under manual capture the presented card only holds the amount (docs.stripe.com/terminal/payments/collect-card-payment#capture-payment):
- *  the hold is an uncaptured charge, as an online authorization's is (authorizeCharge), which the intent's capture takes. */
-async function holdForCapture(ctx, piId, pi, pm, amount) {
-    const charge = await authorizeCharge(ctx, piId, { ...pi, payment_method: pm }, amount);
-    await ctx.write('payment_intent', piId, { status: 'requires_capture', payment_method: pm, amount_capturable: amount, latest_charge: charge }, 'payment_intent.amount_capturable_updated');
-}
-const presentPaymentMethod = async (ctx) => {
-    const id = at(ctx, 'reader');
-    const reader = ctx.get(READER, id);
-    if (!reader)
-        return readerMissing(ctx, id);
-    const action = reader.action;
-    const piId = String((action?.process_payment_intent?.payment_intent) ?? '');
-    if (!action || action.type !== 'process_payment_intent' || action.status !== 'in_progress' || !piId)
-        return nothingToPresent(ctx);
-    const pi = ctx.get('payment_intent', piId);
-    if (!pi)
-        return fail(ctx, `No such payment_intent: '${piId}'`, 400, 'resource_missing');
-    const manual = pi.capture_method === 'manual' || pi.capture_method === 'manual_preferred';
-    const to = manual ? 'requires_capture' : 'succeeded';
-    const refused = ctx.legal('payment_intent', 'status', 'PostTestHelpersTerminalReadersReaderPresentPaymentMethod', pi.status, to, piId);
-    if (refused)
-        return ctx.refuse(refused);
-    const pm = await created(ctx, 'payment_method', {}, {
-        type: 'card_present', customer: null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null },
-        card_present: { brand: 'visa', last4: '4242', exp_month: 12, exp_year: 2030, funding: 'credit', country: 'US', read_method: 'contactless_emv', networks: { available: ['visa'], preferred: null } },
-    });
-    const amount = Number(pi.amount) || 0;
-    if (manual)
-        await holdForCapture(ctx, piId, pi, String(pm.id), amount);
-    else {
-        const charge = await mintCharge(ctx, piId, { ...pi, payment_method: pm.id }, amount);
-        await ctx.write('payment_intent', piId, { status: 'succeeded', payment_method: pm.id, amount_received: amount, latest_charge: charge }, 'payment_intent.succeeded');
-    }
-    return ctx.reply(await ctx.write(READER, id, { action: { ...action, status: 'succeeded' } }, 'terminal_reader.action_succeeded'));
-};
-const cancelAction = async (ctx) => {
-    const id = at(ctx, 'reader');
-    if (!ctx.get(READER, id))
-        return readerMissing(ctx, id);
-    return ctx.reply(await ctx.write(READER, id, { action: null }, 'terminal_reader.updated'));
-};
-// a short-lived secret for the reader SDK, answered and not kept
-const connectionToken = async (ctx) => {
-    const loc = typeof ctx.params.location === 'string' ? ctx.params.location : undefined;
-    return ctx.reply({ object: 'terminal.connection_token', secret: `pst_test_twin_${ctx.rowsRaw(READER, { withDeleted: true }).length + 1}`, ...(loc ? { location: loc } : {}) });
-};
-const createConfiguration = async (ctx) => ctx.reply(await created(ctx, CONF, ctx.params, { is_account_default: false, livemode: false, tipping: null, name: ctx.params.name ?? null }));
-// ── top-ups ──
-// a top-up adds money to the balance it names, through the ledger, once its funds arrive: "USA (USD) ACH Debit Transfer
-// 5 days" (docs.stripe.com/connect/top-ups), and to the Issuing balance alike: "Top-ups debit your bank account. Your
-// top-ups can take up to 5 business days to become available. While they're pending, they won't be added to your
-// Issuing balance" (docs.stripe.com/issuing/funding/balance). It is pending until its expected_availability_date, then
-// settled by settleTopups. Where the documentation stops and the twin decides: every top-up takes exactly five days,
-// whatever its currency and balance, and succeeds.
-const TOPUP_DAYS = 5;
-const createTopup = async (ctx) => {
-    const bad = validateMoney(ctx.params);
-    if (bad)
-        return send(ctx, bad);
-    const now = Number(ctx.now());
-    return ctx.reply(await created(ctx, 'topup', ctx.params, {
-        status: 'pending', expected_availability_date: now + TOPUP_DAYS * 86_400, livemode: false,
-        metadata: {}, source: null, statement_descriptor: ctx.params.statement_descriptor ?? null,
-        balance_transaction: null, failure_code: null, failure_message: null,
-    }));
-};
-/** Time's settling of top-ups, caught up to the World's clock: a pending top-up succeeds on its expected_availability_date,
- *  its funds entered then in the balance it names. */
-export async function settleTopups(ctx) {
-    const now = Number(ctx.now());
-    for (const t of ctx.rowsRaw('topup')) {
-        if (t.status !== 'pending' || Number(t.expected_availability_date) > now)
-            continue;
-        const c = await at_(ctx)(Number(t.expected_availability_date));
-        c.legal('topup', 'status', ctx.call.operation.id, 'pending', 'succeeded', String(t.id), 'vendor');
-        const bt = await settleTopup(c, String(t.id), Number(t.amount), String(t.currency), t.destination_balance === 'issuing' ? 'issuing' : 'payments');
-        await c.write('topup', String(t.id), { status: 'succeeded', balance_transaction: bt }, 'topup.succeeded');
-    }
-}
-const cancelTopup = async (ctx) => {
-    const id = at(ctx, 'topup');
-    const t = ctx.get('topup', id);
-    if (!t)
-        return fail(ctx, `No such topup: '${id}'`, 404, 'resource_missing');
-    const refused = ctx.legal('topup', 'status', 'PostTopupsTopupCancel', t.status, undefined, id);
-    if (refused)
-        return ctx.refuse(refused);
-    return ctx.reply(await ctx.write('topup', id, { status: 'canceled' }, 'topup.canceled'));
-};
-const updateTopup = async (ctx) => {
-    const id = at(ctx, 'topup');
-    if (!ctx.get('topup', id))
-        return fail(ctx, `No such topup: '${id}'`, 404, 'resource_missing');
-    return ctx.reply(await ctx.write('topup', id, ctx.params, 'topup.updated'));
-};
-export const terminal = {
-    PostTerminalLocations: createLocation,
-    PostTerminalLocationsLocation: patch(LOC, 'location', 'location', 'terminal_location.updated'),
-    DeleteTerminalLocationsLocation: remove(LOC, 'location', 'location', 'terminal_location.deleted', 'terminal.location'),
-    PostTerminalReaders: createReader,
-    PostTerminalReadersReader: updateReader,
-    DeleteTerminalReadersReader: remove(READER, 'reader', 'reader', 'terminal_reader.deleted', 'terminal.reader'),
-    PostTerminalReadersReaderProcessPaymentIntent: processPaymentIntent,
-    PostTerminalReadersReaderCancelAction: cancelAction,
-    PostTestHelpersTerminalReadersReaderPresentPaymentMethod: presentPaymentMethod,
-    PostTerminalConnectionTokens: connectionToken,
-    PostTerminalConfigurations: createConfiguration,
-    PostTerminalConfigurationsConfiguration: patch(CONF, 'configuration', 'configuration', 'terminal_configuration.updated'),
-    DeleteTerminalConfigurationsConfiguration: remove(CONF, 'configuration', 'configuration', 'terminal_configuration.deleted', 'terminal.configuration'),
-    PostTopups: createTopup,
-    PostTopupsTopupCancel: cancelTopup,
-    PostTopupsTopup: updateTopup,
-};

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

@@ -1,6 +0,0 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-/** Each advancing clock whose advance has taken its time reaches its target, caught up before anything is answered:
- *  its frozen_time moves, it is ready, and its customers' trials and periods that ended by then end
- *  (./renewals.ts advanceBilling). The advance's own write is when it began (the kernel's updatedAt). */
-export declare function finishClockAdvances(ctx: SemanticsContext): Promise<void>;
-export declare const testClocks: Record<string, Semantics>;

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

@@ -1,4 +0,0 @@
-import type { Semantics } from '@volter/world-core';
-import { type Row } from './shared.js';
-export declare function legacyCard(id: string, card: Row): Row;
-export declare const tokens: Record<string, Semantics>;

package/dist/src/semantics/tokens.js

@@ -1,44 +0,0 @@
-import { paymentMethodSubObject } from "../stripe-twin.js";
-import { created, fail } from "./shared.js";
-/** The Card object a card token carries, as the served spec's `card` describes it: its brand as a name ("Card brand.
- *  Can be `American Express`, ... `MasterCard`, `UnionPay`, `Visa`, or `Unknown`"), the holder's name and address as
- *  given ("Cardholder name"), and the CVC's check when one was given ("If a CVC was provided, results of the check:
- *  pass, fail, unavailable, or unchecked"). Where the documentation stops and the twin decides: a test card's CVC passes. */
-const BRAND_NAMES = { amex: 'American Express', cartes_bancaires: 'Cartes Bancaires', diners: 'Diners Club', discover: 'Discover', eftpos_au: 'Eftpos Australia', girocard: 'Girocard', jcb: 'JCB', mastercard: 'MasterCard', unionpay: 'UnionPay', visa: 'Visa' };
-export function legacyCard(id, card) {
-    const pm = paymentMethodSubObject('card', { card }).card;
-    const given = (k) => (typeof card[k] === 'string' && card[k] !== '' ? card[k] : null);
-    return {
-        id, object: 'card', brand: BRAND_NAMES[String(pm.brand)] ?? 'Unknown', last4: pm.last4, exp_month: pm.exp_month, exp_year: pm.exp_year,
-        funding: pm.funding ?? 'credit', country: pm.country ?? null, fingerprint: pm.fingerprint ?? null, name: given('name'),
-        address_line1: given('address_line1'), address_line2: given('address_line2'), address_city: given('address_city'), address_state: given('address_state'),
-        address_zip: given('address_zip'), address_country: given('address_country'), address_line1_check: null, address_zip_check: null,
-        cvc_check: card.cvc !== undefined && card.cvc !== '' ? 'pass' : null, dynamic_last4: null, tokenization_method: null, metadata: {}, customer: null,
-    };
-}
-/** A token asked for none of what a token holds. */
-function noTokenSource(ctx) {
-    return fail(ctx, 'You must provide one of the following parameters: card, bank_account, pii.', 400, 'parameter_missing');
-}
-/** A bank account token's account, as the legacy BankAccount object holds it. */
-function bankAccountOf(ctx, ba) {
-    const acct = typeof ba.account_number === 'string' ? ba.account_number.replace(/\D/g, '') : '';
-    return {
-        id: ctx.mint('external_account'), object: 'bank_account', account_holder_name: ba.account_holder_name ?? null,
-        account_holder_type: ba.account_holder_type ?? null, bank_name: 'STRIPE TEST BANK',
-        country: ba.country ?? 'US', currency: ba.currency ?? 'usd', fingerprint: 'twin_ba_fp',
-        last4: acct ? acct.slice(-4) : '6789', routing_number: ba.routing_number ?? '110000000', status: 'new',
-    };
-}
-const create = async (ctx) => {
-    const params = ctx.params;
-    const isObject = (v) => !!v && typeof v === 'object';
-    const type = isObject(params.card) ? 'card' : isObject(params.bank_account) ? 'bank_account' : isObject(params.pii) ? 'pii' : undefined;
-    if (!type)
-        return noTokenSource(ctx);
-    const sub = type === 'card'
-        ? { card: legacyCard(ctx.mint('payment_method').replace('pm_', 'card_'), params.card) }
-        : type === 'bank_account' ? { bank_account: bankAccountOf(ctx, params.bank_account) } : {};
-    return ctx.reply(await created(ctx, 'token', { type }, { ...sub, client_ip: null, used: false, livemode: false }));
-};
-export const tokens = { PostTokens: create };

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

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

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>;