@volter/twin-stripe 0.1.2 → 2.0.0

package/src/semantics/ledger.ts

@@ -0,0 +1,216 @@
+// Stripe's balance ledger (docs.stripe.com/api/balance_transactions): every movement of the account's money writes
+// a balance transaction, and the balance is their sum. A captured charge adds its amount less Stripe's fee, pending
+// until its available_on; a refund takes its amount back at once; a payout takes its amount out of what is available
+// and is refused beyond it (balance_insufficient). A transaction's status is what the World clock says of its
+// available_on (the machine's time move, pending → available), so a `wait` in a story settles funds as time does.
+//
+// Where the documentation stops and the twin decides: the fee is Stripe's standard US card pricing, 2.9% + 30¢
+// (stripe.com/pricing), for every charge; funds become available two days after capture (Stripe's standard US
+// payout schedule counts business days); the card 4000000000000077 settles at once, as Stripe's test card of that
+// number does (docs.stripe.com/testing#available-balance).
+//
+// Each connected account keeps its own balance (docs.stripe.com/connect/account-balances): a transaction belongs to
+// the account the request acts for (the Stripe-Account header), else to the platform. A transfer takes its amount out
+// of the platform's available balance and adds it to the destination's; a destination charge transfers its amount
+// less the application fee, available when the charge's funds are; a direct charge's application fee moves from the
+// connected account to the platform.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { at, created, fail, inRange, kept, list, newest, where, type Row } from './shared.ts';
+
+const BT = 'balance_transaction';
+const DAY = 86_400;
+const BYPASS_PENDING = '4000000000000077';
+
+const feeOf = (amount: number): number => (amount > 0 ? Math.round(amount * 0.029) + 30 : 0);
+
+/** A transaction as the clock reads it: available once its available_on has passed, the clock's move,
+ *  asked of the machine as a write asks it. */
+function asOf(ctx: SemanticsContext, t: Row): Row {
+  const due = Number(t.available_on);
+  if (t.status !== 'pending' || !Number.isFinite(due) || due > Number(ctx.now())) return t;
+  ctx.legal('balance_transaction', 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time');
+  return { ...t, status: 'available' };
+}
+
+/** The connected account a request acts for, or undefined for the platform. */
+export const actingAccount = (ctx: SemanticsContext): string | undefined => 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: SemanticsContext, fields: Row, account: string | null | undefined = actingAccount(ctx)): Promise<string> {
+  const bt = await created(ctx, BT, {}, { status: 'available', fee_details: [], description: null, exchange_rate: null, balance_type: 'payments', ...fields, ...(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: Row, account: string | undefined): boolean => (typeof t._account === 'string' ? t._account : undefined) === account;
+
+/** A captured charge's credit: its amount less the fee, pending two days unless the card (a number, or a test
+ *  payment method or token named for it) settles 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: SemanticsContext, chargeId: string, amount: number, currency: string, card?: string): Promise<string> {
+  const now = Number(ctx.now());
+  const fee = feeOf(amount);
+  const settled = !!card && (card.replace(/\D/g, '') === BYPASS_PENDING || /bypassPending/i.test(card));
+  const id = await write(ctx, {
+    amount, currency, fee, net: amount - fee, type: 'charge', reporting_category: 'charge', source: chargeId,
+    status: settled ? 'available' : 'pending', available_on: settled ? now : 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: SemanticsContext, refundId: string, amount: number, currency: string, account: string | null | undefined = actingAccount(ctx)): Promise<string> {
+  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: SemanticsContext, account: string | undefined, currency: string, at: number): number {
+  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: SemanticsContext, account: string | undefined, currency: string, from: number, until: number): number[] {
+  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: SemanticsContext, disputeId: string, amount: number, currency: string): Promise<string> {
+  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: SemanticsContext, disputeId: string, amount: number, currency: string): Promise<string> {
+  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: SemanticsContext, account: string | undefined): Row[] {
+  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: SemanticsContext, payoutId: string, amount: number, currency: string, account: string | undefined, at: number, entries: Row[]): Promise<string> {
+  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: SemanticsContext, payoutId: string, amount: number, currency: string, account: string | null | undefined = actingAccount(ctx)): Promise<string> {
+  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 `availableOn` comes
+ *  (a plain transfer's funds are available already). Answers the platform's entry. */
+export async function settleTransfer(ctx: SemanticsContext, transferId: string, amount: number, currency: string, destination: string, availableOn = Number(ctx.now()), fromPending = false): Promise<string> {
+  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: SemanticsContext, reversalId: string, amount: number, currency: string, destination: string): Promise<string> {
+  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: SemanticsContext, feeId: string, amount: number, currency: string, account: string): Promise<string> {
+  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: SemanticsContext, topupId: string, amount: number, currency: string, destination: string): Promise<string> {
+  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).
+ *  Answers the entries that moved. */
+export async function settleDueEntries(ctx: SemanticsContext): Promise<Row[]> {
+  const now = Number(ctx.now());
+  const account = actingAccount(ctx);
+  const moved: Row[] = [];
+  for (const t of ctx.rowsRaw(BT)) {
+    if (!onAccount(t, account) || 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: SemanticsContext, account: string | undefined = actingAccount(ctx)): { available: Map<string, number>; pending: Map<string, number>; issuing: Map<string, number> } {
+  const available = new Map<string, number>();
+  const pending = new Map<string, number>();
+  const issuing = new Map<string, number>();
+  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: SemanticsContext, amount: number, currency: string, account: string | undefined = actingAccount(ctx)): Response | undefined {
+  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: SemanticsContext): Set<unknown> => new Set(ctx.rowsRaw(BT).filter((t) => onAccount(t, actingAccount(ctx))).map((t) => t.id));
+
+const retrieve: Semantics = 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: Semantics = 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: Record<string, Semantics> = {
+  GetBalanceTransactions: listAll,
+  GetBalanceTransactionsId: retrieve,
+};