@volter/twin-stripe 0.1.2 → 2.0.1

package/src/semantics/ledger.ts

@@ -0,0 +1,253 @@
+// 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).
+//
+// Test mode (the twin serves livemode: false), as docs.stripe.com/testing documents it:
+// - cards keep that delay but two: "Other test cards send funds from a successful payment to your pending balance",
+//   while 4000000000000077 and 4000003720000278 (and their test names pm_card_bypassPending,
+//   pm_card_bypassPendingInternational, tok_bypassPending, tok_bypassPendingInternational) "succeed. Funds are added
+//   directly to your available balance, bypassing your pending balance" (#available-balance; test-cards.ts). A
+//   PaymentMethod made from one keeps that (payment-methods.ts, after-payment.ts), so a saved card charged later by
+//   id bypasses too;
+// - a US bank account debit: "Test transactions settle instantly and are added to your available test balance. This
+//   behavior differs from live mode" (ACH Direct Debit, "Test settlement behavior");
+// - a source_transaction transfer "takes on the pending status of the associated charge"
+//   (docs.stripe.com/connect/separate-charges-and-transfers), so it is available at once when its charge is;
+// - "Test payouts simulate a live payout but aren't processed with the bank" (docs.stripe.com/payouts#test-payouts):
+//   the payout clock (semantics/balance.ts) is live's.
+// No other test-mode speed-up is documented, so 4242 4242 4242 4242 funds sit pending the two days.
+//
+// Where the documentation stops and the twin decides: every credit written available at once (a bypass or bank-debit
+// charge, a transfer, a transfer from such a charge, an application fee, a top-up, an Issuing top-up included, a reversal) is marked not yet
+// sent, and the drain sends its account balance.available for it ("Occurs whenever your Stripe balance has been
+// updated (e.g., when a charge is available to be paid out). ... This event is not fired for negative
+// transactions", docs.stripe.com/api/events/types), as it does for funds that came due after the delay. The Balance
+// it carries is the account's at the drain: a debit or an automatic payout landing first shows in it.
+//
+// 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 { asOf, at, created, fail, inRange, kept, list, newest, where, type Row } from './shared.ts';
+import { BYPASS_PENDING_CARDS } from './test-cards.ts';
+
+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: SemanticsContext, card: string | undefined): boolean {
+  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: number): number => (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: 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> {
+  // 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: 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 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: SemanticsContext, chargeId: string, amount: number, currency: string, card?: string): Promise<string> {
+  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: 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 `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: SemanticsContext, transferId: string, amount: number, currency: string, destination: string, fromCharge?: number, fromPending = false): Promise<string> {
+  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: 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).
+ *  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: 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)) 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: 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,
+};