@volter/twin-stripe 0.1.2 → 2.0.1

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

@@ -0,0 +1,99 @@
+import { disputeEvidence } from "../stripe-twin.js";
+import { actingAccount, settleApplicationFee, settleDispute, settleTransfer } from "./ledger.js";
+import { BYPASS_PENDING_CARDS } from "./test-cards.js";
+import { created } from "./shared.js";
+const DAY = 86_400;
+/** The test cards whose success Stripe follows with its own act, by number and by their documented test names. */
+export const AFTER_SUCCESS_CARDS = {
+    pm_card_createDispute: { brand: 'visa', number: '4000000000000259', outcome: 'dispute' },
+    pm_card_createDisputeProductNotReceived: { brand: 'visa', number: '4000000000002685', outcome: 'dispute_not_received' },
+    pm_card_createDisputeInquiry: { brand: 'visa', number: '4000000000001976', outcome: 'inquiry' },
+    pm_card_riskLevelElevated: { brand: 'visa', number: '4000000000009235', outcome: 'review' },
+    // its funds go straight to the available balance (ledger.ts reads it; no act follows here)
+    ...Object.fromEntries(Object.entries(BYPASS_PENDING_CARDS).map(([name, c]) => [name, { ...c, outcome: 'available' }])),
+};
+const BY_NUMBER = Object.fromEntries(Object.values(AFTER_SUCCESS_CARDS).map((c) => [c.number, c.outcome]));
+/** What Stripe does after a card succeeds: from a raw number, a test name (pm_card_* or tok_*), or a stored
+ *  PaymentMethod that recorded it when it was made. */
+export function afterSuccessOf(ctx, ref) {
+    // a card given as a token (card[token], payment_method_data[card][token]) is the card the token names
+    if (ref && typeof ref === 'object' && typeof ref.token === 'string')
+        return afterSuccessOf(ctx, ref.token);
+    if (ref && typeof ref === 'object')
+        return BY_NUMBER[String(ref.number ?? '').replace(/\D/g, '')];
+    if (typeof ref !== 'string' || !ref)
+        return undefined;
+    const stored = ctx.row('payment_method', ref);
+    if (stored)
+        return stored._afterSuccess ?? undefined;
+    return AFTER_SUCCESS_CARDS[ref.replace(/^tok_/, 'pm_card_')]?.outcome ?? BY_NUMBER[ref.replace(/\D/g, '')];
+}
+/** Stripe's acts on a charge that just succeeded: a dispute or a review its card brings, and the platform's fee. */
+export async function afterCharge(ctx, chargeId, charge, ref) {
+    const outcome = afterSuccessOf(ctx, ref);
+    const pi = charge.payment_intent ? { payment_intent: charge.payment_intent } : { payment_intent: null };
+    const now = Number(ctx.now());
+    if (outcome === 'dispute' || outcome === 'dispute_not_received' || outcome === 'inquiry') {
+        const dispute = await created(ctx, 'dispute', { charge: chargeId, ...pi, amount: charge.amount, currency: charge.currency }, {
+            reason: outcome === 'dispute_not_received' ? 'product_not_received' : 'fraudulent', status: outcome === 'inquiry' ? 'warning_needs_response' : 'needs_response', is_charge_refundable: false,
+            evidence: disputeEvidence(), evidence_details: { due_by: now + 7 * DAY, has_evidence: false, past_due: false, submission_count: 0, enhanced_eligibility: {} },
+            balance_transactions: [], livemode: false, metadata: {}, enhanced_eligibility_types: [],
+        });
+        // an inquiry moves no money; a dispute takes the amount and its fee until it is decided
+        if (outcome !== 'inquiry') {
+            const bt = await settleDispute(ctx, String(dispute.id), charge.amount, charge.currency);
+            await ctx.write('dispute', String(dispute.id), { balance_transactions: [ctx.get('balance_transaction', bt) ?? bt] }, 'dispute.funds_withdrawn');
+        }
+        await ctx.write('charge', chargeId, { disputed: true }, 'charge.dispute.created');
+    }
+    if (outcome === 'review')
+        await openReview(ctx, chargeId, pi);
+    const feeAmount = Math.trunc(Number(charge.application_fee_amount) || 0);
+    const destination = typeof charge.destination === 'string' && charge.destination ? charge.destination : undefined;
+    const direct = actingAccount(ctx);
+    const account = destination ?? direct;
+    // a destination charge transfers what it collected, less the platform's fee, available when the charge's funds are
+    if (destination) {
+        const amount = charge.amount - feeAmount;
+        const chargeBt = ctx.get('charge', chargeId)?.balance_transaction;
+        const availableOn = Number(ctx.get('balance_transaction', String(chargeBt))?.available_on ?? ctx.now());
+        const tr = await created(ctx, 'transfer', { amount, currency: charge.currency, destination }, {
+            amount_reversed: 0, balance_transaction: null, livemode: false, metadata: {}, reversed: false, source_type: 'card', source_transaction: chargeId,
+            reversals: { object: 'list', data: [], has_more: false, total_count: 0, url: '' },
+        });
+        const bt = await settleTransfer(ctx, String(tr.id), amount, charge.currency, destination, availableOn);
+        await ctx.write('transfer', String(tr.id), { balance_transaction: bt, destination_payment: `py_${String(tr.id).replace(/^tr_/, '')}`, reversals: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/transfers/${String(tr.id)}/reversals` } }, 'transfer.created');
+        await ctx.write('charge', chargeId, { transfer: tr.id }, 'charge.updated');
+    }
+    if (feeAmount > 0 && account) {
+        const fee = await created(ctx, 'application_fee', { account, amount: feeAmount, charge: chargeId, currency: charge.currency }, {
+            amount_refunded: 0, application: 'ca_twin', balance_transaction: null, originating_transaction: null, refunded: false, livemode: false,
+        });
+        // a direct charge's fee moves from the connected account to the platform (a destination charge kept it back)
+        const bt = !destination && direct ? await settleApplicationFee(ctx, String(fee.id), feeAmount, charge.currency, direct) : null;
+        await ctx.write('application_fee', String(fee.id), { balance_transaction: bt, refunds: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/application_fees/${String(fee.id)}/refunds` } }, 'application_fee.created');
+        await ctx.write('charge', chargeId, { application_fee: fee.id, application_fee_amount: feeAmount }, 'charge.updated');
+    }
+}
+/** Radar places an elevated-risk card's charge in review (docs.stripe.com/radar/reviews). */
+async function openReview(ctx, chargeId, pi) {
+    const review = await created(ctx, 'review', { charge: chargeId, ...pi }, {
+        open: true, opened_reason: 'rule', reason: 'rule', closed_reason: null, billing_zip: null, ip_address: null, ip_address_location: null, session: null, livemode: false,
+    });
+    const existing = ctx.get('charge', chargeId)?.outcome ?? {};
+    await ctx.write('charge', chargeId, {
+        review: review.id,
+        outcome: { ...existing, type: 'manual_review', risk_level: 'elevated', risk_score: 67, seller_message: 'Stripe evaluated this payment as having elevated risk, and placed it in review.' },
+    }, 'review.opened');
+}
+/** The mandate a verified bank account carries for a payment (single use) or a setup (multi use). */
+export async function mintMandate(ctx, paymentMethod, use, amount, currency) {
+    const now = Number(ctx.now());
+    const mandate = await created(ctx, 'mandate', { payment_method: typeof paymentMethod === 'string' ? paymentMethod : null }, {
+        status: 'active', type: use, livemode: false,
+        customer_acceptance: { type: 'online', accepted_at: now, online: { ip_address: '127.0.0.1', user_agent: 'twin' } },
+        payment_method_details: { type: 'us_bank_account', us_bank_account: { collection_method: 'paper' } },
+        ...(use === 'single_use' ? { single_use: { amount: amount ?? 0, currency: currency ?? 'usd' } } : { multi_use: {} }),
+    }, { timeField: '_created' });
+    return String(mandate.id);
+}

package/dist/src/semantics/apps-secrets.d.ts

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

package/dist/src/semantics/apps-secrets.js

@@ -0,0 +1,54 @@
+import { created, fail, list, newest, kept } from "./shared.js";
+const SECRET = 'apps.secret';
+function scopeKeyOf(ctx) {
+    const scope = ctx.params.scope && typeof ctx.params.scope === 'object' ? ctx.params.scope : undefined;
+    const scopeType = scope && typeof scope.type === 'string' ? scope.type : 'account';
+    return scopeType === 'user' ? `user:${String(scope.user)}` : 'account';
+}
+const named = (ctx, name) => ctx.rows(SECRET).find((s) => s.name === name && kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx));
+const set = async (ctx) => {
+    const params = ctx.params;
+    const name = typeof params.name === 'string' ? params.name : '';
+    if (!name)
+        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+    const scope = params.scope && typeof params.scope === 'object' ? params.scope : undefined;
+    const scopeType = scope && typeof scope.type === 'string' ? scope.type : '';
+    if (scopeType !== 'account' && scopeType !== 'user')
+        return fail(ctx, 'Invalid scope[type]: must be account or user.', 400, 'parameter_invalid_string_enum');
+    if (scopeType === 'user' && typeof scope.user !== 'string')
+        return fail(ctx, 'Missing required param: scope[user].', 400, 'parameter_missing');
+    if (params.payload === undefined)
+        return fail(ctx, 'Missing required param: payload.', 400, 'parameter_missing');
+    const expiresAt = params.expires_at !== undefined ? Math.trunc(Number(params.expires_at)) : null;
+    const existing = named(ctx, name);
+    if (existing)
+        return ctx.reply(await ctx.write(SECRET, String(existing.id), { payload: params.payload, expires_at: expiresAt, _updated: ctx.now() }, 'apps_secret.update'));
+    return ctx.reply(await created(ctx, SECRET, { name }, {
+        livemode: false, deleted: false, expires_at: expiresAt, payload: params.payload,
+        scope: scopeType === 'user' ? { type: 'user', user: scope.user } : { type: 'account' },
+        _scope_key: scopeKeyOf(ctx),
+    }));
+};
+const find = async (ctx) => {
+    const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
+    if (!name)
+        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+    const s = named(ctx, name);
+    return s ? ctx.reply(s) : fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
+};
+const remove = async (ctx) => {
+    const name = typeof ctx.params.name === 'string' ? ctx.params.name : '';
+    if (!name)
+        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+    const s = named(ctx, name);
+    if (!s)
+        return fail(ctx, `No such secret: '${name}'`, 404, 'resource_missing');
+    return ctx.reply(await ctx.write(SECRET, String(s.id), { deleted: true }, 'apps_secret.delete'));
+};
+const listSecrets = async (ctx) => list(ctx, SECRET, newest(ctx, SECRET).filter((s) => kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx)));
+export const appsSecrets = {
+    PostAppsSecrets: set,
+    GetAppsSecretsFind: find,
+    PostAppsSecretsDelete: remove,
+    GetAppsSecrets: listSecrets,
+};

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

@@ -0,0 +1,11 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** The acting account's Balance object (docs.stripe.com/api/balance/balance_object). */
+export declare function balanceBody(ctx: SemanticsContext): Row;
+/** Time's arrivals, written: each of the acting account's payouts whose arrival date has come moves pending → paid
+ *  (the clock's move, as asOf reads it), written as `payout.paid`, the event Stripe sends for it. Answers their ids. */
+export declare function payDuePayouts(ctx: SemanticsContext): Promise<string[]>;
+/** Time's payouts, caught up to the World's clock: each account on an automatic schedule is paid out, on each of its
+ *  scheduled days that has come, what became available by then. */
+export declare function advancePayouts(ctx: SemanticsContext): Promise<void>;
+export declare const balances: Record<string, Semantics>;

package/dist/src/semantics/balance.js

@@ -0,0 +1,195 @@
+import { validateMoney } from "../stripe-twin.js";
+import { accountSettings, PLATFORM_ACCOUNT_ID } from "../stripe-twin.js";
+import { actingAccount, balanceOf, refusePayout, settleAutomaticPayout, settlePayout, unpaidEntries } from "./ledger.js";
+import { at, at_, created, fail, inRange, list, newest, send, where, kept } from "./shared.js";
+const account = actingAccount;
+const DAY = 86_400;
+const payoutMissing = (ctx, id) => fail(ctx, `No such payout: '${id}'`, 404, 'resource_missing');
+/** The acting account's Balance object (docs.stripe.com/api/balance/balance_object). */
+export function balanceBody(ctx) {
+    const { available, pending, issuing } = balanceOf(ctx);
+    const toArr = (m) => {
+        const out = [...m.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } }));
+        return out.length ? out : [{ amount: 0, currency: 'usd', source_types: { card: 0 } }];
+    };
+    // a platform's balance holds its connected accounts' reserve, "Funds held due to negative balances on connected accounts
+    // where account.controller.requirement_collection is `application`" (docs.stripe.com/api/balance/balance_object, whose
+    // example answers `[{"amount": 0, "currency": "usd"}]`); the twin models no such reserve, so it is zero in each currency
+    const reserved = account(ctx) ? {} : { connect_reserved: toArr(available).map((b) => ({ amount: 0, currency: b.currency })) };
+    return {
+        object: 'balance', available: toArr(available), pending: toArr(pending), ...reserved, livemode: false,
+        ...(issuing.size ? { issuing: { available: [...issuing.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } })) } } : {}),
+    };
+}
+const balance = async (ctx) => ctx.reply(balanceBody(ctx));
+/** Time's arrivals, written: each of the acting account's payouts whose arrival date has come moves pending → paid
+ *  (the clock's move, as asOf reads it), written as `payout.paid`, the event Stripe sends for it. Answers their ids. */
+export async function payDuePayouts(ctx) {
+    const acct = account(ctx);
+    const now = Number(ctx.now());
+    const paid = [];
+    for (const p of newest(ctx, 'payout')) {
+        if ((acct ? kept(ctx, 'payout', p, '_account') !== acct : !!kept(ctx, 'payout', p, '_account')) || p.status !== 'pending' || Number(p.arrival_date) > now)
+            continue;
+        if (ctx.legal('payout', 'status', ctx.call.operation.id, 'pending', 'paid', String(p.id), 'time'))
+            continue;
+        await ctx.write('payout', String(p.id), { status: 'paid' }, 'payout.paid');
+        paid.push(String(p.id));
+    }
+    return paid;
+}
+/** Where a connected account's payout goes: "ID of the bank account or card the payout is sent to" (served spec,
+ *  payout.destination), its default external account for the currency, "When multiple accounts are available for a given
+ *  currency, Stripe uses the one set as `default_for_currency`" (docs.stripe.com/connect/payouts-bank-accounts), the
+ *  newest such. Where the documentation stops and the twin decides: the platform's own bank account is not modelled, so
+ *  its payouts name none. */
+function payoutBank(ctx, account, currency) {
+    const banks = newest(ctx, 'external_account').filter((e) => e.account === account && String(e.currency ?? currency) === currency);
+    return String((banks.find((e) => e.default_for_currency === true) ?? banks[0])?.id ?? '') || null;
+}
+const payoutDefaults = (ctx) => ({
+    method: 'standard', type: 'bank_account', source_type: 'card', automatic: false,
+    reconciliation_status: 'not_applicable', arrival_date: Number(ctx.now()) + 2 * DAY, livemode: false, metadata: {},
+});
+/** A payout as the clock reads it: paid once its arrival date has come, the clock's move, asked of the
+ *  machine as a write asks it. */
+function asOf(ctx, p) {
+    if (p.status !== 'pending' || Number(p.arrival_date) > Number(ctx.now()))
+        return p;
+    ctx.legal('payout', 'status', ctx.call.operation.id, 'pending', 'paid', String(p.id), 'time');
+    return { ...p, status: 'paid' };
+}
+/** A connected account's payout in a currency none of its bank accounts takes. */
+function noExternalAccount(ctx, currency) {
+    return fail(ctx, `Sorry, you don't have any external accounts in that currency (${currency}).`, 400);
+}
+const createPayout = async (ctx) => {
+    const bad = validateMoney(ctx.params);
+    if (bad)
+        return send(ctx, bad);
+    const acct = account(ctx);
+    if (acct && !ctx.get('account', acct))
+        return fail(ctx, `No such account: '${acct}'`, 400, 'account_invalid');
+    const amount = Math.trunc(Number(ctx.params.amount) || 0);
+    const currency = String(ctx.params.currency ?? 'usd');
+    // a connected account is paid out to its own bank account
+    if (acct && !ctx.rows('external_account').some((e) => e.account === acct && (e.currency ?? currency) === currency))
+        return noExternalAccount(ctx, currency);
+    const refused = refusePayout(ctx, amount, currency);
+    if (refused)
+        return refused;
+    const id = ctx.mint('payout');
+    const bt = await settlePayout(ctx, id, -amount, currency);
+    return ctx.reply(await created(ctx, 'payout', { ...ctx.params, id }, { status: 'pending', ...payoutDefaults(ctx), balance_transaction: bt, destination: acct ? payoutBank(ctx, acct, currency) : null, ...(acct ? { _account: acct } : {}) }));
+};
+const listPayouts = async (ctx) => {
+    const acct = account(ctx);
+    const scoped = newest(ctx, 'payout').filter((p) => (acct ? kept(ctx, 'payout', p, '_account') === acct : !kept(ctx, 'payout', p, '_account'))).map((p) => asOf(ctx, p));
+    return list(ctx, 'payout', where(ctx, scoped, { status: (p, v) => p.status === v, created: (p, v) => inRange(p.created, v), arrival_date: (p, v) => inRange(p.arrival_date, v) }));
+};
+const DAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+/** The first scheduled payout time on or after `from`: midnight UTC of a day the schedule pays out on. */
+function payoutDay(from, schedule) {
+    const first = Math.ceil(from / DAY) * DAY;
+    const pays = (day) => {
+        const d = new Date(day * 1000);
+        if (schedule.interval === 'weekly')
+            return DAYS[d.getUTCDay()] === String(schedule.weekly_anchor ?? 'monday');
+        if (schedule.interval === 'monthly')
+            return d.getUTCDate() === Math.min(Number(schedule.monthly_anchor ?? 1), new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate());
+        return true;
+    };
+    return Array.from({ length: 62 }, (_, i) => first + i * DAY).find(pays) ?? first;
+}
+/** Time's payouts, caught up to the World's clock: each account on an automatic schedule is paid out, on each of its
+ *  scheduled days that has come, what became available by then. */
+export async function advancePayouts(ctx) {
+    const now = Number(ctx.now());
+    const platform = ctx.get('account', PLATFORM_ACCOUNT_ID);
+    const accounts = [{ id: undefined, settings: platform?.settings }];
+    for (const a of ctx.rows('account')) {
+        if (a.id === PLATFORM_ACCOUNT_ID || a.payouts_enabled !== true)
+            continue;
+        if (!ctx.rows('external_account').some((e) => e.account === a.id))
+            continue;
+        accounts.push({ id: String(a.id), settings: a.settings });
+    }
+    for (const acct of accounts) {
+        const schedule = (accountSettings(acct.settings, acct.settings ?? undefined).payouts.schedule ?? {});
+        if (schedule.interval === 'manual')
+            continue;
+        const unpaid = unpaidEntries(ctx, acct.id);
+        const days = [...new Set(unpaid.map((t) => payoutDay(Number(t.available_on) || 0, schedule)))].filter((d) => d <= now).sort((x, y) => x - y);
+        const paid = new Set();
+        for (const day of days) {
+            const due = unpaid.filter((t) => !paid.has(t.id) && (Number(t.available_on) || 0) <= day);
+            const byCurrency = new Map();
+            for (const t of due)
+                byCurrency.set(String(t.currency ?? 'usd'), [...(byCurrency.get(String(t.currency ?? 'usd')) ?? []), t]);
+            for (const [currency, entries] of byCurrency) {
+                const amount = entries.reduce((n, t) => n + (Number(t.net) || 0), 0);
+                // nothing to pay yet: what came due is carried to the next payout
+                if (amount <= 0)
+                    continue;
+                // made on its day, as Stripe makes it, whenever the request that catches it up comes
+                const c = await at_(ctx)(day);
+                const id = c.mint('payout');
+                const bt = await settleAutomaticPayout(c, id, amount, currency, acct.id, day, entries);
+                await created(c, 'payout', { id, amount, currency }, {
+                    status: 'pending', ...payoutDefaults(c), arrival_date: day + 2 * DAY, automatic: true, balance_transaction: bt, destination: acct.id ? payoutBank(c, String(acct.id), currency) : null,
+                    description: 'STRIPE PAYOUT', ...(acct.id ? { _account: acct.id } : {}),
+                });
+                for (const t of entries)
+                    paid.add(t.id);
+            }
+        }
+    }
+}
+const retrievePayout = async (ctx) => {
+    const p = ctx.get('payout', at(ctx, 'payout'));
+    return p ? ctx.reply(asOf(ctx, p)) : payoutMissing(ctx, at(ctx, 'payout'));
+};
+const cancelPayout = async (ctx) => {
+    const id = at(ctx, 'payout');
+    const po = ctx.get('payout', id);
+    if (!po)
+        return payoutMissing(ctx, id);
+    const refused = ctx.legal('payout', 'status', 'PostPayoutsPayoutCancel', asOf(ctx, po).status, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    // the money comes back to the balance it left
+    const owner = kept(ctx, 'payout', po, '_account');
+    await settlePayout(ctx, id, Number(po.amount) || 0, String(po.currency ?? 'usd'), typeof owner === 'string' ? owner : null);
+    return ctx.reply(await ctx.write('payout', id, { status: 'canceled' }, 'payout.cancel'));
+};
+// a reversal is itself a payout in the other direction, back into the connected account's balance, as the reverse page's
+// example answers it: a negative amount, pending until it arrives, carrying the request's metadata
+// (docs.stripe.com/api/payouts/reverse); the original stays paid and names it
+const reversePayout = async (ctx) => {
+    const id = at(ctx, 'payout');
+    const po = ctx.get('payout', id);
+    if (!po)
+        return payoutMissing(ctx, id);
+    const owner = kept(ctx, 'payout', po, '_account');
+    if (typeof owner !== 'string')
+        return fail(ctx, "Payout reversals are only supported for payouts to connected accounts' bank accounts.", 400);
+    const status = String(asOf(ctx, po).status);
+    if (po.reversed_by || status !== 'paid')
+        return ctx.refuse({ status: 400, code: 'payout_reversal_not_allowed', message: po.reversed_by ? 'This payout has already been reversed.' : `This payout cannot be reversed because it has a status of ${status}. A pending payout can be canceled instead.` });
+    const reversalId = ctx.mint('payout');
+    const bt = await settlePayout(ctx, reversalId, Number(po.amount) || 0, String(po.currency ?? 'usd'), owner);
+    const metadata = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? { metadata: ctx.params.metadata } : {};
+    const reversal = await created(ctx, 'payout', { id: reversalId, amount: -(Number(po.amount) || 0), currency: po.currency, ...metadata }, {
+        status: 'pending', ...payoutDefaults(ctx), balance_transaction: bt, original_payout: id, destination: po.destination ?? null, _account: owner,
+    });
+    await ctx.write('payout', id, { reversed_by: reversal.id }, 'payout.reversed');
+    return ctx.reply(reversal);
+};
+export const balances = {
+    GetBalance: balance,
+    PostPayouts: createPayout,
+    GetPayouts: listPayouts,
+    GetPayoutsPayout: retrievePayout,
+    PostPayoutsPayoutCancel: cancelPayout,
+    PostPayoutsPayoutReverse: reversePayout,
+};

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

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

package/dist/src/semantics/billing.js

@@ -0,0 +1,220 @@
+import { at, created, fail, list, newest, path, where } from "./shared.js";
+const METER = 'billing.meter';
+const meterMissing = (ctx, id) => fail(ctx, `No such meter: '${id}'`, 404, 'resource_missing');
+const objectOf = (v) => (v && typeof v === 'object' ? v : {});
+// a meter needs a display name, the event name it counts, and how it aggregates (sum or count)
+const createMeter = async (ctx) => {
+    const params = ctx.params;
+    const displayName = typeof params.display_name === 'string' ? params.display_name : '';
+    if (!displayName)
+        return fail(ctx, 'Missing required param: display_name.', 400, 'parameter_missing');
+    if (!(params.event_name ?? ''))
+        return fail(ctx, 'Missing required param: event_name.', 400, 'parameter_missing');
+    const formula = objectOf(params.default_aggregation).formula;
+    if (typeof formula !== 'string' || !formula)
+        return fail(ctx, 'Missing required param: default_aggregation[formula] (sum or count).', 400, 'parameter_missing');
+    return ctx.reply(await created(ctx, METER, params, {
+        status: 'active', livemode: false,
+        customer_mapping: params.customer_mapping ?? { event_payload_key: 'stripe_customer_id', type: 'by_id' },
+        event_time_window: params.event_time_window ?? null,
+        value_settings: params.value_settings ?? { event_payload_key: 'value' },
+        status_transitions: { deactivated_at: null }, updated: ctx.now(),
+    }));
+};
+function activation(kind) {
+    return async (ctx) => {
+        const id = at(ctx, 'id');
+        const m = ctx.get(METER, id);
+        if (!m)
+            return meterMissing(ctx, id);
+        const refused = ctx.legal(METER, 'status', kind === 'deactivate' ? 'PostBillingMetersIdDeactivate' : 'PostBillingMetersIdReactivate', m.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const fields = { ...(kind === 'deactivate' ? { status: 'inactive', status_transitions: { deactivated_at: ctx.now() } } : { status: 'active', status_transitions: { deactivated_at: null } }), updated: ctx.now() };
+        return ctx.reply(await ctx.write(METER, id, fields, `billing_meter.${kind}`));
+    };
+}
+// a meter event has no id of its own on Stripe (it carries an `identifier`); its object is billing.meter_event
+const reportUsage = async (ctx) => {
+    const params = ctx.params;
+    if (typeof params.event_name !== 'string' || !params.event_name)
+        return fail(ctx, 'Missing required param: event_name.', 400, 'parameter_missing');
+    const payload = objectOf(params.payload);
+    const body = await created(ctx, 'billing.meter_event', { ...params }, {
+        livemode: false, timestamp: params.timestamp !== undefined ? Math.trunc(Number(params.timestamp)) : ctx.now(),
+        identifier: payload.identifier ?? null, payload,
+    });
+    return ctx.reply({ ...body, object: 'billing.meter_event' });
+};
+// the meter's events for one customer in [start_time, end_time), aggregated by its formula
+const eventSummaries = async (ctx) => {
+    const id = at(ctx, 'id');
+    const m = ctx.get(METER, id);
+    if (!m)
+        return meterMissing(ctx, id);
+    const params = ctx.params;
+    const customer = typeof params.customer === 'string' ? params.customer : '';
+    if (!customer)
+        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+    if (params.start_time === undefined)
+        return fail(ctx, 'Missing required param: start_time.', 400, 'parameter_missing');
+    if (params.end_time === undefined)
+        return fail(ctx, 'Missing required param: end_time.', 400, 'parameter_missing');
+    const startTime = Math.trunc(Number(params.start_time) || 0);
+    const endTime = Math.trunc(Number(params.end_time) || 0);
+    // "Must be aligned with minute boundaries" (start_time, end_time); "For hourly granularity, start and end times must
+    // align with hour boundaries … For daily granularity, … with UTC day boundaries (00:00 UTC)" (value_grouping_window;
+    // the served spec). Where the documentation stops and the twin decides: Stripe documents no error for it, so the
+    // twin answers a 400 naming the parameter and the boundary.
+    const window = params.value_grouping_window === 'hour' ? 3600 : params.value_grouping_window === 'day' ? 86_400 : 60;
+    const unit = window === 3600 ? 'hour' : window === 86_400 ? 'UTC day' : 'minute';
+    for (const [name, t] of [['start_time', startTime], ['end_time', endTime]]) {
+        if (t % window !== 0)
+            return fail(ctx, `Invalid ${name}: ${t} is not aligned with ${unit} boundaries.`, 400);
+    }
+    const mapKey = typeof objectOf(m.customer_mapping).event_payload_key === 'string' ? String(objectOf(m.customer_mapping).event_payload_key) : 'stripe_customer_id';
+    const valueKey = typeof objectOf(m.value_settings).event_payload_key === 'string' ? String(objectOf(m.value_settings).event_payload_key) : 'value';
+    const formula = objectOf(m.default_aggregation).formula ?? 'sum';
+    let aggregate = 0;
+    for (const ev of ctx.rowsRaw('billing.meter_event', { withDeleted: true })) {
+        if (ev.event_name !== String(m.event_name ?? ''))
+            continue;
+        const ts = Number(ev.timestamp) || 0;
+        if (ts < startTime || ts >= endTime)
+            continue;
+        const payload = objectOf(ev.payload);
+        if (String(payload[mapKey] ?? '') !== customer)
+            continue;
+        aggregate += formula === 'count' ? 1 : Number(payload[valueKey]) || 0;
+    }
+    return ctx.reply({
+        object: 'list', url: path(ctx), has_more: false,
+        data: [{ id: `mtrusg_twin_${id}_${customer}`, object: 'billing.meter_event_summary', meter: id, aggregated_value: aggregate, start_time: startTime, end_time: endTime, livemode: false }],
+    });
+};
+// ── credit grants: a customer's prepaid credit, paid or promotional, in a monetary amount ──
+const GRANT = 'billing.credit_grant';
+const grantMissing = (ctx, id) => fail(ctx, `No such credit grant: '${id}'`, 404, 'resource_missing');
+const createGrant = async (ctx) => {
+    const params = ctx.params;
+    const customer = typeof params.customer === 'string' ? params.customer : '';
+    if (!customer)
+        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+    if (!ctx.row('customer', customer, { withDeleted: true }))
+        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
+    const category = typeof params.category === 'string' ? params.category : '';
+    if (category !== 'paid' && category !== 'promotional')
+        return fail(ctx, 'Invalid category: must be paid or promotional.', 400, 'parameter_invalid_string_enum');
+    const monetary = params.amount && typeof params.amount === 'object' ? objectOf(params.amount.monetary) : undefined;
+    if (!monetary || monetary.value === undefined || monetary.currency === undefined)
+        return fail(ctx, 'Missing required param: amount[monetary][value] and amount[monetary][currency].', 400, 'parameter_missing');
+    return ctx.reply(await created(ctx, GRANT, { customer }, {
+        category, livemode: false, name: params.name ?? null,
+        amount: { type: 'monetary', monetary: { currency: String(monetary.currency), value: Math.trunc(Number(monetary.value) || 0) } },
+        applicability_config: params.applicability_config && typeof params.applicability_config === 'object' ? params.applicability_config : { scope: { price_type: 'metered' } },
+        effective_at: params.effective_at !== undefined ? Math.trunc(Number(params.effective_at)) : ctx.now(),
+        expires_at: params.expires_at !== undefined ? Math.trunc(Number(params.expires_at)) : null,
+        priority: params.priority !== undefined ? Math.trunc(Number(params.priority)) : 50,
+        voided_at: null, metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {}, updated: ctx.now(),
+    }));
+};
+// expiring or voiding a grant stamps the instant; it no longer counts toward the balance
+function endGrant(kind) {
+    return async (ctx) => {
+        const id = at(ctx, 'id');
+        if (!ctx.get(GRANT, id))
+            return grantMissing(ctx, id);
+        return ctx.reply(await ctx.write(GRANT, id, { ...(kind === 'void' ? { voided_at: ctx.now() } : { expires_at: ctx.now() }), updated: ctx.now() }, `credit_grant.${kind}`));
+    };
+}
+// only the expiry and metadata change
+const updateGrant = async (ctx) => {
+    const id = at(ctx, 'id');
+    if (!ctx.get(GRANT, id))
+        return grantMissing(ctx, id);
+    const patch = { updated: ctx.now() };
+    if (ctx.params.expires_at !== undefined)
+        patch.expires_at = Math.trunc(Number(ctx.params.expires_at));
+    if (ctx.params.metadata !== undefined)
+        patch.metadata = ctx.params.metadata;
+    return ctx.reply(await ctx.write(GRANT, id, patch, 'credit_grant.update'));
+};
+// the customer's live (unvoided, unexpired) monetary grants, summed per currency
+const creditBalance = async (ctx) => {
+    const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
+    if (!customer)
+        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+    if (!ctx.row('customer', customer, { withDeleted: true }))
+        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
+    const now = Number(ctx.now());
+    const byCurrency = {};
+    for (const g of ctx.rows(GRANT)) {
+        if (g.customer !== customer || g.voided_at != null)
+            continue;
+        if (typeof g.expires_at === 'number' && g.expires_at <= now)
+            continue;
+        const monetary = objectOf(objectOf(g.amount).monetary);
+        const cur = String(monetary.currency ?? 'usd');
+        byCurrency[cur] = (byCurrency[cur] ?? 0) + (Number(monetary.value) || 0);
+    }
+    const balances = Object.entries(byCurrency).map(([currency, value]) => ({
+        available_balance: { type: 'monetary', monetary: { currency, value } },
+        ledger_balance: { type: 'monetary', monetary: { currency, value } },
+    }));
+    return ctx.reply({ object: 'billing.credit_balance_summary', customer, balances, livemode: false });
+};
+// ── alerts: a usage threshold on a meter ──
+const ALERT = 'billing.alert';
+const createAlert = async (ctx) => {
+    const params = ctx.params;
+    if (params.alert_type !== 'usage_threshold')
+        return fail(ctx, 'Invalid alert_type: must be usage_threshold.', 400, 'parameter_invalid_string_enum');
+    if (typeof params.title !== 'string' || !params.title)
+        return fail(ctx, 'Missing required param: title.', 400, 'parameter_missing');
+    const ut = params.usage_threshold && typeof params.usage_threshold === 'object' ? params.usage_threshold : undefined;
+    if (!ut || ut.gte === undefined || typeof ut.meter !== 'string')
+        return fail(ctx, 'Missing required param: usage_threshold[gte] and usage_threshold[meter].', 400, 'parameter_missing');
+    // the spec requires recurrence too (one_time: the alert fires once)
+    if (ut.recurrence === undefined || ut.recurrence === '')
+        return fail(ctx, 'Missing required param: usage_threshold[recurrence].', 400, 'parameter_missing');
+    if (!ctx.get(METER, ut.meter))
+        return fail(ctx, `No such meter: '${ut.meter}'`, 400, 'resource_missing');
+    return ctx.reply(await created(ctx, ALERT, {}, {
+        alert_type: 'usage_threshold', livemode: false, status: 'active', title: params.title,
+        usage_threshold: { gte: Math.trunc(Number(ut.gte) || 0), meter: ut.meter, recurrence: String(ut.recurrence), filters: null },
+    }));
+};
+const listAlerts = async (ctx) => list(ctx, ALERT, where(ctx, newest(ctx, ALERT), {
+    alert_type: (a, v) => a.alert_type === v,
+    meter: (a, v) => objectOf(a.usage_threshold).meter === v,
+}));
+function alertMove(kind, operationId) {
+    return async (ctx) => {
+        const id = at(ctx, 'id');
+        const a = ctx.get(ALERT, id);
+        if (!a)
+            return fail(ctx, `No such alert: '${id}'`, 404, 'resource_missing');
+        const refused = ctx.legal(ALERT, 'status', operationId, a.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const status = kind === 'activate' ? 'active' : kind === 'deactivate' ? 'inactive' : 'archived';
+        return ctx.reply(await ctx.write(ALERT, id, { status }, `billing_alert.${kind}`));
+    };
+}
+export const billing = {
+    PostBillingMeters: createMeter,
+    PostBillingMetersIdDeactivate: activation('deactivate'),
+    PostBillingMetersIdReactivate: activation('reactivate'),
+    PostBillingMeterEvents: reportUsage,
+    GetBillingMetersIdEventSummaries: eventSummaries,
+    PostBillingCreditGrants: createGrant,
+    PostBillingCreditGrantsIdExpire: endGrant('expire'),
+    PostBillingCreditGrantsIdVoid: endGrant('void'),
+    PostBillingCreditGrantsId: updateGrant,
+    GetBillingCreditBalanceSummary: creditBalance,
+    PostBillingAlerts: createAlert,
+    GetBillingAlerts: listAlerts,
+    PostBillingAlertsIdActivate: alertMove('activate', 'PostBillingAlertsIdActivate'),
+    PostBillingAlertsIdDeactivate: alertMove('deactivate', 'PostBillingAlertsIdDeactivate'),
+    PostBillingAlertsIdArchive: alertMove('archive', 'PostBillingAlertsIdArchive'),
+};

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

@@ -0,0 +1,28 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** Every egress of a charge carries its refunds, derived from the refund rows in list order. */
+export declare function chargeBody(ctx: SemanticsContext, c: Row): Row;
+/** A capture=false charge refunded while uncaptured: its authorization is released by the refund, as it would be
+ *  "automatically refunded if uncaptured" (spec/openapi.json.gz, `capture_before`). The charge stays uncaptured and
+ *  becomes refunded in full, a Refund records the release, and no money moves: none was ever received. Written as
+ *  charge.refunded. Where the documentation stops and the twin decides: Stripe's basil change ("Partially capturing or
+ *  canceling payments no longer creates a Refund", docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-
+ *  capture-and-payment-cancellation-flow) names partial capture and cancellation, not a refund asked for, so a refund
+ *  still makes one; its reason is null and it has no balance transaction. Answers the Refund. */
+export declare function releaseAuthorization(ctx: SemanticsContext, ch: Row, operationId: string, given?: Row): Promise<Row>;
+/** A PaymentIntent's authorization released by its cancel: "For PaymentIntents with a `status` of `requires_capture`, the
+ *  remaining `amount_capturable` is automatically refunded" (docs.stripe.com/api/payment_intents/cancel), and since basil
+ *  a cancellation makes no Refund: "`amount_captured` will be 0 instead of `nil` in payment cancellation flows",
+ *  "`amount_refunded` will no longer be updated by these actions", "`refunded` will no longer be `true` for payment
+ *  cancellation flows", and no charge.refunded is sent (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-
+ *  partial-capture-and-payment-cancellation-flow). The charge stays uncaptured; nothing is written as an event. */
+export declare function cancelAuthorization(ctx: SemanticsContext, ch: Row): Promise<Row>;
+/** An authorized charge captured, by the charge's capture or its PaymentIntent's: what is captured credits the balance.
+ *  Written as charge.captured, "Occurs whenever a previously uncaptured charge is captured" (docs.stripe.com/api/events/types).
+ *  A partial capture releases the rest with no Refund and leaves amount_refunded and refunded as they were: "The following
+ *  flows no longer result in a `Refund` object created and linked to the payment: Partial capture", "`amount_refunded`
+ *  will no longer be updated by these actions", and "There will only be a single balance transaction for partial captures"
+ *  (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-capture-and-payment-cancellation-flow).
+ *  The caller has asked the machine whether it may capture. */
+export declare function captureAuthorization(ctx: SemanticsContext, ch: Row, toCapture: number, _operationId: string): Promise<Row>;
+export declare const charges: Record<string, Semantics>;