@volter/twin-stripe 2.0.38 → 3.0.0

package/dist/src/semantics/ledger.js

@@ -1,200 +0,0 @@
-import { asOf, at, created, fail, inRange, kept, list, newest, where } from "./shared.js";
-import { BYPASS_PENDING_CARDS } from "./test-cards.js";
-const BT = 'balance_transaction';
-const DAY = 86_400;
-/** A ledger entry's mark: available at once, its balance.available not yet sent (settleDueEntries). */
-const UNSENT = '_availableUnsent';
-const BYPASS_NUMBERS = new Set(Object.values(BYPASS_PENDING_CARDS).map((c) => c.number));
-/** Whether a charge's funds go straight to the available balance: a bypass card as a raw number, a test name (pm_card_*
- *  or tok_*), or a stored PaymentMethod made from one (which records it as what follows its success, after-payment.ts);
- *  or a US bank account, stored or one of Stripe's test bank accounts named as one (pm_usBankAccount_*). */
-export function bypassesPending(ctx, card) {
-    if (!card)
-        return false;
-    const stored = ctx.row('payment_method', card);
-    // the row carries what the method recorded; its type is the vendor object's (ctx.get), not the row's envelope
-    if (stored)
-        return stored._afterSuccess === 'available' || ctx.get('payment_method', card)?.type === 'us_bank_account';
-    if (/^pm_us_?bank_?account/i.test(card))
-        return true;
-    return BYPASS_NUMBERS.has(card.replace(/\D/g, '')) || card.replace(/^tok_/, 'pm_card_') in BYPASS_PENDING_CARDS;
-}
-const feeOf = (amount) => (amount > 0 ? Math.round(amount * 0.029) + 30 : 0);
-/** The connected account a request acts for, or undefined for the platform. */
-export const actingAccount = (ctx) => ctx.call.request.headers.get('stripe-account') ?? undefined;
-/** A ledger entry on an account's balance: the acting account's unless one is named (null names the platform). */
-async function write(ctx, fields, account = actingAccount(ctx)) {
-    // a credit available at once waits for the drain's balance.available (settleDueEntries)
-    const unsent = (fields.status ?? 'available') === 'available' && Number(fields.net) > 0 ? { [UNSENT]: true } : {};
-    const bt = await created(ctx, BT, {}, { status: 'available', fee_details: [], description: null, exchange_rate: null, balance_type: 'payments', ...fields, ...unsent, ...(account ? { _account: account } : {}) });
-    return String(bt.id);
-}
-/** Whether a stored ledger entry is on this account's balance (undefined: the platform's). */
-const onAccount = (t, account) => (typeof t._account === 'string' ? t._account : undefined) === account;
-/** A captured charge's credit: its amount less the fee, pending two days unless the card bypasses the pending
- *  balance (bypassesPending), when it is due at once. The
- *  caller mints the charge's id first and stores the returned id as the charge's balance_transaction. */
-export async function settleCharge(ctx, chargeId, amount, currency, card) {
-    const now = Number(ctx.now());
-    const fee = feeOf(amount);
-    const atOnce = bypassesPending(ctx, card);
-    const id = await write(ctx, {
-        amount, currency, fee, net: amount - fee, type: 'charge', reporting_category: 'charge', source: chargeId,
-        ...(atOnce ? { status: 'available', available_on: now } : { status: 'pending', available_on: now + 2 * DAY }),
-        fee_details: fee ? [{ amount: fee, application: null, currency, description: 'Stripe processing fees', type: 'stripe_fee' }] : [],
-    });
-    return id;
-}
-/** A refund's debit, at once, on the acting account's balance unless one is named (null names the platform). */
-export async function settleRefund(ctx, refundId, amount, currency, account = actingAccount(ctx)) {
-    return write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'refund', reporting_category: 'refund', source: refundId, available_on: Number(ctx.now()) }, account);
-}
-/** What an account had available in a currency at a moment: every entry of its payments balance whose funds had come
- *  due by then. */
-export function availableAt(ctx, account, currency, at) {
-    let sum = 0;
-    for (const t of ctx.rowsRaw(BT)) {
-        if (!onAccount(t, account) || t.balance_type === 'issuing' || String(t.currency ?? 'usd') !== currency)
-            continue;
-        const due = Number(t.available_on ?? t.created);
-        if (Number.isFinite(due) && due <= at)
-            sum += Number(t.net ?? 0);
-    }
-    return sum;
-}
-/** The moments after `from` and up to `until` when funds of an account came due, in order: when a held refund can
- *  next be covered. */
-export function fundsDueBetween(ctx, account, currency, from, until) {
-    const times = ctx.rowsRaw(BT).filter((t) => onAccount(t, account) && String(t.currency ?? 'usd') === currency).map((t) => Number(t.available_on ?? t.created)).filter((d) => Number.isFinite(d) && d > from && d <= until);
-    return [...new Set(times)].sort((a, b) => a - b);
-}
-/** A dispute's debit, at once: the disputed amount and the dispute fee (the twin's 1500 cents, Stripe's US $15). */
-export async function settleDispute(ctx, disputeId, amount, currency) {
-    const fee = 1500;
-    return write(ctx, {
-        amount: -amount, currency, fee, net: -amount - fee, type: 'adjustment', reporting_category: 'dispute', source: disputeId, available_on: Number(ctx.now()),
-        fee_details: [{ amount: fee, application: null, currency, description: 'Dispute fee', type: 'stripe_fee' }],
-    });
-}
-/** A won dispute's credit, at once: the disputed amount returned (docs.stripe.com/disputes/how-disputes-work). Where the
- *  documentation stops and the twin decides: the dispute fee is not returned. */
-export async function settleDisputeWon(ctx, disputeId, amount, currency) {
-    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'adjustment', reporting_category: 'dispute_reversal', source: disputeId, available_on: Number(ctx.now()) });
-}
-/** An account's ledger entries an automatic payout has not yet paid out: every entry on its payments balance that no
- *  automatic payout took (the automatic payouts' own debits excluded), as stored. */
-export function unpaidEntries(ctx, account) {
-    const automatic = new Set(ctx.rowsRaw('payout').filter((p) => p.automatic === true).map((p) => p.id));
-    return ctx.rowsRaw(BT).filter((t) => onAccount(t, account) && t.balance_type !== 'issuing' && !t._payout && !automatic.has(t.source));
-}
-/** An automatic payout's debit at `at`, and the entries it pays out marked with it, so the ledger lists them under
- *  the payout (docs.stripe.com/api/balance_transactions/list#balance_transaction_list-payout). */
-export async function settleAutomaticPayout(ctx, payoutId, amount, currency, account, at, entries) {
-    for (const t of entries)
-        await ctx.write(BT, String(t.id), { _payout: payoutId }, 'balance_transaction.paid_out');
-    return write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'payout', reporting_category: 'payout', source: payoutId, available_on: at, _payout: payoutId }, account ?? null);
-}
-/** A payout's debit (negative) or a cancellation's or reversal's credit (positive), at once, on the payout's account. */
-export async function settlePayout(ctx, payoutId, amount, currency, account = actingAccount(ctx)) {
-    const type = amount < 0 ? 'payout' : 'payout_cancel';
-    return write(ctx, { amount, currency, fee: 0, net: amount, type, reporting_category: type === 'payout' ? 'payout' : 'payout_reversal', source: payoutId, available_on: Number(ctx.now()) }, account);
-}
-/** A transfer's two entries: out of the platform's balance at once, into the destination's when `fromCharge` (its
- *  charge's funds' availability) comes (a plain transfer, with no `fromCharge`, moves funds available already).
- *  Answers the platform's entry. */
-export async function settleTransfer(ctx, transferId, amount, currency, destination, fromCharge, fromPending = false) {
-    const availableOn = fromCharge ?? Number(ctx.now());
-    const settled = availableOn <= Number(ctx.now());
-    // a transfer from a charge's pending funds (source_transaction) leaves the platform when they arrive, not before
-    const platform = await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'transfer', reporting_category: 'transfer', source: transferId, ...(fromPending ? { status: settled ? 'available' : 'pending', available_on: availableOn } : { available_on: Number(ctx.now()) }) }, null);
-    await write(ctx, { amount, currency, fee: 0, net: amount, type: 'payment', reporting_category: 'charge', source: transferId, status: settled ? 'available' : 'pending', available_on: availableOn }, destination);
-    return platform;
-}
-/** A transfer reversal's two entries: back into the platform's balance, out of the destination's. */
-export async function settleTransferReversal(ctx, reversalId, amount, currency, destination) {
-    const platform = await write(ctx, { amount, currency, fee: 0, net: amount, type: 'transfer_refund', reporting_category: 'transfer_reversal', source: reversalId, available_on: Number(ctx.now()) }, null);
-    await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'payment_refund', reporting_category: 'refund', source: reversalId, available_on: Number(ctx.now()) }, destination);
-    return platform;
-}
-/** A direct charge's application fee: out of the connected account's balance, into the platform's. */
-export async function settleApplicationFee(ctx, feeId, amount, currency, account) {
-    await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'application_fee', reporting_category: 'platform_earning', source: feeId, available_on: Number(ctx.now()) }, account);
-    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'application_fee', reporting_category: 'platform_earning', source: feeId, available_on: Number(ctx.now()) }, null);
-}
-/** A top-up's credit, to the payments balance or, with `destination_balance=issuing`, to Issuing's
- *  (docs.stripe.com/issuing/funding/balance). Where the documentation stops and the twin decides: a test-mode top-up
- *  is available at once. */
-export async function settleTopup(ctx, topupId, amount, currency, destination) {
-    const issuing = destination === 'issuing';
-    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'topup', reporting_category: 'topup', source: topupId, available_on: Number(ctx.now()), balance_type: issuing ? 'issuing' : 'payments' });
-}
-/** Time's settlements, written: each entry on the acting account's balance whose funds came due by the World's clock
- *  moves pending → available (the clock's move the machine allows), so a settlement is recorded once. A read already
- *  sees it (asOf); the record is what lets Stripe's balance.available be sent once (stripe-server.ts, the drain).
- *  Funds that were available at once and not yet sent are taken too, and marked sent. Answers the entries taken. */
-export async function settleDueEntries(ctx) {
-    const now = Number(ctx.now());
-    const account = actingAccount(ctx);
-    const moved = [];
-    for (const t of ctx.rowsRaw(BT)) {
-        if (!onAccount(t, account))
-            continue;
-        if (t.status === 'available' && t[UNSENT] === true) {
-            await ctx.write(BT, String(t.id), { [UNSENT]: false }, 'balance_transaction.available_sent');
-            moved.push(t);
-            continue;
-        }
-        if (t.status !== 'pending' || !(Number(t.available_on) <= now))
-            continue;
-        if (ctx.legal(BT, 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time'))
-            continue;
-        await ctx.write(BT, String(t.id), { status: 'available' }, 'balance_transaction.available');
-        moved.push(t);
-    }
-    return moved;
-}
-/** An account's balance, by currency: what the clock has made available, what is still pending, and Issuing's own. */
-export function balanceOf(ctx, account = actingAccount(ctx)) {
-    const available = new Map();
-    const pending = new Map();
-    const issuing = new Map();
-    for (const raw of ctx.rowsRaw(BT)) {
-        if (!onAccount(raw, account))
-            continue;
-        const t = asOf(ctx, raw);
-        const cur = String(t.currency ?? 'usd');
-        const net = Number(t.net ?? 0);
-        const bucket = t.balance_type === 'issuing' ? issuing : t.status === 'available' ? available : pending;
-        bucket.set(cur, (bucket.get(cur) ?? 0) + net);
-    }
-    return { available, pending, issuing };
-}
-/** balance_insufficient when a payout or transfer would take more than the account has available in its currency. */
-export function refusePayout(ctx, amount, currency, account = actingAccount(ctx)) {
-    const have = balanceOf(ctx, account).available.get(currency) ?? 0;
-    if (amount <= have)
-        return undefined;
-    return fail(ctx, "The transfer or payout couldn't be completed because the associated account doesn't have a sufficient balance available.", 400, 'balance_insufficient');
-}
-/** The ids of the ledger entries on the acting account's balance. */
-const mine = (ctx) => new Set(ctx.rowsRaw(BT).filter((t) => onAccount(t, actingAccount(ctx))).map((t) => t.id));
-const retrieve = async (ctx) => {
-    const t = ctx.get(BT, at(ctx, 'id'));
-    return t && mine(ctx).has(t.id) ? ctx.reply(asOf(ctx, t)) : ctx.notFound(BT, at(ctx, 'id'));
-};
-const listAll = async (ctx) => {
-    const own = mine(ctx);
-    return list(ctx, BT, where(ctx, newest(ctx, BT).filter((t) => own.has(t.id)).map((t) => asOf(ctx, t)), {
-        type: (t, v) => t.type === v,
-        currency: (t, v) => t.currency === v,
-        source: (t, v) => t.source === v,
-        // an automatic payout lists the entries it paid out, its own debit among them
-        payout: (t, v) => t.source === v || kept(ctx, BT, t, '_payout') === v,
-        // a range of creation times (docs.stripe.com/api/balance_transactions/list#balance_transaction_list-created)
-        created: (t, v) => inRange(t.created, v),
-    }));
-};
-export const ledger = {
-    GetBalanceTransactions: listAll,
-    GetBalanceTransactionsId: retrieve,
-};

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

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