@bongos/core 1.24.23 → 1.24.24

package/src/bongos/cash-outs.js

@@ -0,0 +1,399 @@
+'use strict';
+
+// src/bongos/cash-outs.js — A PERSON WITHDRAWS THEIR OWN BALANCE TO THEIR BANK, WITH HOLDS,
+// A MINIMUM AND A RECORD OF EVERY FAILURE (task 1004911, goal 1000092 N7; ADR 0385 D1/D8,
+// ADR 0397 D2/D7).
+//
+// THE PRODUCT GATE (legal framework, by Article only; a product constraint, not advice).
+//   actor     the person whose money it is, on their own signed-in web session, with their
+//             own logged approval of this one withdrawal (a `cashout_approved` row in the
+//             N9 log: approver and recipient are the same person, by CHECK). Never a CLI,
+//             an agent, a standing rule or the project's owner.
+//   custody   the processor, throughout. The money is in the person's own connected
+//             account and goes from there to the bank they gave the processor. Bongos never
+//             holds it, never sees bank details, and never sums these rows into a balance.
+//   words     balance, cash-out, withdrawal, payout, bank. Never deposit, wallet, interest,
+//             return-on-anything or yield.
+//   control   one approval, one withdrawal; one press, one withdrawal. Nothing repeats.
+//   advice    none is given.
+//   primitive the Stripe Connect payout from a connected account's balance to its external
+//             bank account (ADR 0397 D3 table). Only the processor adapter names Stripe.
+//
+// THE ORDER.
+//   1. Refuse what is malformed or below the minimum, a person with no account here, a
+//      second withdrawal while one is still open, and more than the processor says they
+//      have. Under a per-person lock: record the person's approval and the withdrawal in
+//      ONE transaction, once per instruction id.
+//   2. Check the authority again at send time (core checkApproval): the approval covers
+//      exactly this, and the payout gates (age tier, sanctions, open holds; N10) still pass.
+//      A refusal of money that is the person's files a hold that TELLS them, with the appeal
+//      route; here it is a `held` attempt with the reason.
+//   3. Ask the processor, under a per-withdrawal lock, with the key bongos-cashout-<id>-<try>.
+//      The database (core_293) works out <try> itself and moves it on only after the
+//      processor said the last try did not pay (`refused`) or the bank sent it back
+//      (`returned`). A timeout or an answer we cannot trust is `failed` and keeps the key,
+//      so pressing retry gets back the payout the processor already made, never a second.
+//
+// THE PROCESSOR PORT (optional; with none connected every withdrawal is held `no_processor`):
+//   memberBalanceMicro(accountRef)        the person's balance, the processor's figure
+//   memberPayout({ idempotencyKey, amountCents, currency, account, payTo })
+//                                         → { ref, paid? }; an error with `refused: true`
+//                                         means the processor created no payout
+// and the adapter's webhook reports later news through recordProcessorOutcome (paid, or
+// returned with the bank's reason). The person's account is read through the economy
+// module's `economy.account` port (memberAccount), never from the request.
+
+const seams = require('../module-seams');
+
+const LOCK_SPACE = 1004911;
+const PROCESSOR_TIMEOUT_MS = 15_000;
+const READ_TIMEOUT_MS = 5000;
+const MICRO_PER_CENT = 10_000;
+const CURRENCY = 'USD';
+// The smallest withdrawal: below this the bank's own handling outweighs the amount. A
+// product choice, recorded in the session log; changing it is a code change, not a setting.
+const MIN_CASH_OUT_CENTS = 1000;
+const MAX_CASH_OUT_CENTS = 100_000_000_00; // a sanity ceiling, the approval log's own
+const REASON_MAX = 300;
+const INSTRUCTION_RE = /^[A-Za-z0-9_-]{8,80}$/;
+
+const isId = (v) => (typeof v === 'number' && Number.isSafeInteger(v) && v > 0) || (typeof v === 'string' && /^[1-9][0-9]{0,18}$/.test(v));
+const clip = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, REASON_MAX) || 'unknown';
+const idempotencyKey = (cashOutId, tryNo) => `bongos-cashout-${cashOutId}-${tryNo}`;
+const dollars = (cents) => `$${(cents / 100).toFixed(2)}`;
+
+class CashOutRefusal extends Error {
+  constructor(code, message, status = 400, details = undefined) { super(message); this.code = code; this.status = status; this.details = details; }
+}
+
+// Plain words for why a withdrawal waits.
+const HELD_WORDS = Object.freeze({
+  no_processor: 'No payment processor is connected to this project yet, so nothing was sent. Your money is still in your balance.',
+  no_such_approval: 'The approval for this withdrawal could not be found, so nothing was sent.',
+  different_recipient: 'The approval for this withdrawal is not yours, so nothing was sent.',
+  different_amount: 'The approval for this withdrawal is for a different amount, so nothing was sent.',
+  recipient_gated: 'You cannot be paid out right now. We have told you why under your payout holds, and you can appeal there. Your money is still in your balance.',
+  guardian_cosign_missing: 'Because you are 16 or 17, your parent or guardian needs to co-sign this withdrawal before it can be sent.',
+});
+
+// Plain words for where each withdrawal stands, as the person reads it.
+const STATUS_WORDS = Object.freeze({
+  held: 'Waiting. Nothing has left your balance.',
+  failed: 'We could not confirm with the processor whether this went. Pressing retry is safe: it can never be paid twice.',
+  refused: 'The processor turned this down and nothing was sent. Your money is still in your balance. You can try again.',
+  sent: 'On its way to your bank.',
+  paid: 'Arrived at your bank.',
+  returned: 'Your bank sent this back, so the money is in your balance again. You can try again.',
+  cancelled: 'You cancelled this. Nothing was sent.',
+});
+// Where a withdrawal still needs something: the person can retry or cancel it.
+const OPEN = Object.freeze(['held', 'failed', 'refused', 'returned']);
+
+function defaultPool() { return require('./pool').pool; }
+function defaultAuthority() { return require('./payout-approvals'); }
+function defaultAccount() { return seams.resolveOptional('economy.account'); }
+
+function withTimeout(promise, ms) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, rej) => { timer = setTimeout(() => rej(Object.assign(new Error('the processor did not answer in time'), { code: 'timeout' })), ms); }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+// A transaction on a checked-out client when the pool can give one; a single connection
+// (a test stand-in, or a caller's client) runs the statements as they are.
+async function inTx(pool, fn) {
+  if (typeof pool.connect !== 'function' || typeof pool.release === 'function') return fn(pool);
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const out = await fn(client);
+    await client.query('COMMIT');
+    return out;
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+const lock = (db, key) => db.query('SELECT pg_advisory_xact_lock($1::int, hashtext($2::text))', [LOCK_SPACE, key]);
+
+// ── reading where a withdrawal stands ──────────────────────────────────────
+
+const CASH_OUT_COLS = 'id, builder_id, approval_id, from_account, amount_cents, currency, instruction_id, created_at';
+
+async function readAttempts(db, cashOutId) {
+  const { rows } = await db.query(
+    'SELECT id, try_no, outcome, processor_ref, reason, created_at FROM cash_out_attempts WHERE cash_out_id = $1 ORDER BY id', [cashOutId]);
+  return rows;
+}
+
+// Fold a withdrawal's attempts, oldest first, into where it stands. The try number is the
+// database's rule, repeated: one more than the tries the processor said did not pay.
+function standing(attempts) {
+  const tryNo = 1 + attempts.filter((a) => a.outcome === 'refused' || a.outcome === 'returned').length;
+  const last = attempts[attempts.length - 1] || null;
+  const sent = attempts.find((a) => a.outcome === 'sent' && Number(a.try_no) === tryNo) || null;
+  const cancelled = attempts.some((a) => a.outcome === 'cancelled');
+  let status;
+  if (cancelled) status = 'cancelled';
+  else if (sent) status = attempts.some((a) => a.outcome === 'paid' && Number(a.try_no) === tryNo) ? 'paid' : 'sent';
+  else status = last ? last.outcome : 'held';
+  return { status, try_no: tryNo, processor_ref: sent ? sent.processor_ref : null, last };
+}
+
+function present(row, attempts) {
+  const s = standing(attempts);
+  const reason = s.status === 'paid' || s.status === 'sent' || !s.last ? null : (s.last.reason || null);
+  const heldFor = s.status === 'held' && reason ? reason.split(' ')[0] : null;
+  return {
+    id: String(row.id), amount_cents: Number(row.amount_cents), currency: row.currency,
+    approval_id: String(row.approval_id), created_at: row.created_at,
+    status: s.status, words: (heldFor && HELD_WORDS[heldFor]) || STATUS_WORDS[s.status],
+    reason, processor_ref: s.processor_ref, tries: s.try_no,
+    // the record that this money has not reached the bank yet: it stays until paid or cancelled
+    still_yours: s.status !== 'paid' && s.status !== 'sent' && s.status !== 'cancelled',
+    can_retry: OPEN.includes(s.status), can_cancel: OPEN.includes(s.status),
+    history: attempts.map((a) => ({ outcome: a.outcome, try: Number(a.try_no), reason: a.reason || null, at: a.created_at })),
+  };
+}
+
+async function readCashOut(db, cashOutId) {
+  const { rows } = await db.query(`SELECT ${CASH_OUT_COLS} FROM cash_outs WHERE id = $1`, [cashOutId]);
+  return rows[0] || null;
+}
+
+// The person's own withdrawal that still needs something, if any. Only their newest can
+// be: a new one is recorded only while none is open (requestCashOut, under the person's lock).
+async function openCashOut(db, builderId) {
+  const { rows } = await db.query(`SELECT ${CASH_OUT_COLS} FROM cash_outs WHERE builder_id = $1 ORDER BY id DESC LIMIT 1`, [builderId]);
+  if (!rows[0]) return null;
+  const s = standing(await readAttempts(db, rows[0].id));
+  return OPEN.includes(s.status) || s.status === 'sent' ? { row: rows[0], status: s.status } : null;
+}
+
+async function insertAttempt(db, cashOutId, tryNo, { outcome, processorRef = null, reason = null, actorId = null }) {
+  await db.query(
+    'INSERT INTO cash_out_attempts (cash_out_id, try_no, outcome, processor_ref, reason, actor_id) VALUES ($1,$2,$3,$4,$5,$6)',
+    [cashOutId, tryNo, outcome, processorRef, reason === null ? null : clip(reason), isId(actorId) ? actorId : null]);
+}
+
+// ── step 3: the send ───────────────────────────────────────────────────────
+
+async function send(pool, row, { processor, payTo, actorId, timeoutMs }) {
+  return inTx(pool, async (db) => {
+    await lock(db, `c:${row.id}`);
+    const s = standing(await readAttempts(db, row.id));
+    if (!OPEN.includes(s.status)) return { status: s.status, already: true };
+    let out;
+    try {
+      out = await withTimeout(Promise.resolve(processor.memberPayout({
+        idempotencyKey: idempotencyKey(row.id, s.try_no),
+        amountCents: Number(row.amount_cents), currency: row.currency,
+        account: row.from_account, payTo,
+      })), timeoutMs);
+    } catch (err) {
+      const reason = clip(`${err && err.code ? err.code + ': ' : ''}${err && err.message ? err.message : 'payout failed'}`);
+      // `refused` only when the processor says it made nothing; anything else may have paid
+      const outcome = err && err.refused === true ? 'refused' : 'failed';
+      await insertAttempt(db, row.id, s.try_no, { outcome, reason, actorId });
+      return { status: outcome, reason };
+    }
+    const ref = out && typeof out.ref === 'string' && out.ref.trim() ? out.ref.trim() : null;
+    if (!ref) {
+      await insertAttempt(db, row.id, s.try_no, { outcome: 'failed', reason: 'no_reference: the processor gave no payout reference', actorId });
+      return { status: 'failed', reason: 'no_reference' };
+    }
+    // If the database fails from here the payout exists and nothing says so; the
+    // transaction rolls back, the withdrawal still reads open, and the next retry sends
+    // the same key, so the processor hands back this payout and it is booked then.
+    await insertAttempt(db, row.id, s.try_no, { outcome: 'sent', processorRef: ref, actorId });
+    if (out.paid === true) await insertAttempt(db, row.id, s.try_no, { outcome: 'paid', processorRef: ref, actorId });
+    return { status: out.paid === true ? 'paid' : 'sent', processor_ref: ref };
+  });
+}
+
+// sendCashOut(row, …) — steps 2 and 3 for one recorded withdrawal: re-check the authority,
+// then ask the processor. Every outcome is a returned status, written as an attempt.
+async function sendCashOut(row, { pool, authority, processor, actorId, timeoutMs }) {
+  const s = standing(await readAttempts(pool, row.id));
+  if (!OPEN.includes(s.status)) return { status: s.status, already: true };
+
+  const held = async (reason, extra = {}) => {
+    await insertAttempt(pool, row.id, s.try_no, { outcome: 'held', reason, actorId });
+    return { status: 'held', reason, words: HELD_WORDS[reason.split(' ')[0]] || null, ...extra };
+  };
+  const auth = await authority.checkApproval({
+    id: row.approval_id, kind: 'cashout_approved', recipientId: row.builder_id,
+    amountCents: Number(row.amount_cents), currency: row.currency,
+  }, { pool });
+  if (!auth || !auth.ok) {
+    const why = (auth && auth.reason) || 'no_such_approval';
+    const gate = auth && auth.gate ? auth.gate : null;
+    return held(gate ? `${why} (${gate.reason})` : why, gate ? { freeze_id: gate.freeze_id } : {});
+  }
+  if (!processor || typeof processor.memberPayout !== 'function') return held('no_processor');
+  return send(pool, row, { processor, payTo: auth.pay_to, actorId, timeoutMs });
+}
+
+// ── the person's three acts ────────────────────────────────────────────────
+
+async function readBalance(processor, account, log) {
+  if (!processor || typeof processor.memberBalanceMicro !== 'function' || !account) return null;
+  try {
+    const v = Number(await withTimeout(Promise.resolve(processor.memberBalanceMicro(account)), READ_TIMEOUT_MS));
+    return Number.isSafeInteger(v) ? v : null;
+  } catch (e) {
+    if (log) log.error({ err: e.message }, 'cash-out: member balance unreadable');
+    return null;
+  }
+}
+
+// requestCashOut({ builderId, actor, amountCents, instructionId }, deps) — the person asks
+// to take amountCents of their own balance to their bank. actor is the personal web session
+// ({ id, rank, session_id, session_source:'web' }, payout-approvals personalSession).
+// Throws CashOutRefusal only BEFORE anything is recorded; afterwards every outcome is a
+// returned status. Pressing again with the same instruction id is the same withdrawal.
+async function requestCashOut({ builderId, actor, amountCents, instructionId }, {
+  pool = defaultPool(), authority = defaultAuthority(), account = defaultAccount(),
+  processor = null, timeoutMs = PROCESSOR_TIMEOUT_MS, log = null,
+} = {}) {
+  if (!isId(builderId) || !actor || String(actor.id) !== String(builderId) || actor.session_source !== 'web') {
+    throw new CashOutRefusal('personal_session_required', 'A cash-out is made by the person themself, signed in on the website.', 403);
+  }
+  const amount = Number(amountCents);
+  if (!Number.isSafeInteger(amount) || amount <= 0 || amount > MAX_CASH_OUT_CENTS) {
+    throw new CashOutRefusal('bad_amount', 'amount_cents must be a positive whole number of cents.');
+  }
+  if (amount < MIN_CASH_OUT_CENTS) {
+    throw new CashOutRefusal('below_minimum', `The smallest cash-out is ${dollars(MIN_CASH_OUT_CENTS)}.`, 400, { minimum_cents: MIN_CASH_OUT_CENTS });
+  }
+  if (typeof instructionId !== 'string' || !INSTRUCTION_RE.test(instructionId)) {
+    throw new CashOutRefusal('bad_instruction_id', 'instruction_id must be 8 to 80 letters, digits, dashes or underscores, one per cash-out.');
+  }
+  if (!account || typeof account.memberAccount !== 'function') {
+    throw new CashOutRefusal('no_account_record', 'Balances are switched off in this project, so there is nothing to cash out.', 409);
+  }
+  const from = await account.memberAccount(pool, builderId);
+  if (!from) throw new CashOutRefusal('no_account', 'You have no processor account in this project yet, so there is nothing to cash out.', 409);
+
+  // the processor's figure, when it can be read. When it cannot, nothing here stops the
+  // request: the processor's own payout refuses an overdraw (recorded as `refused`), and
+  // the adapter must keep it so.
+  const balance = await readBalance(processor, from, log);
+  if (balance !== null && amount * MICRO_PER_CENT > balance) {
+    throw new CashOutRefusal('over_balance', `You have ${dollars(Math.floor(balance / MICRO_PER_CENT))} in your balance; you cannot cash out more than that.`, 409);
+  }
+
+  const row = await inTx(pool, async (db) => {
+    await lock(db, `b:${builderId}`);
+    const { rows: had } = await db.query(`SELECT ${CASH_OUT_COLS} FROM cash_outs WHERE builder_id = $1 AND instruction_id = $2`, [builderId, instructionId]);
+    if (had[0]) {
+      if (Number(had[0].amount_cents) !== amount) throw new CashOutRefusal('instruction_reused', 'That instruction id was already used for a different cash-out.', 409);
+      return had[0];
+    }
+    const open = await openCashOut(db, builderId);
+    if (open) {
+      throw new CashOutRefusal('cash_out_open', 'You already have a cash-out that is not finished. Retry or cancel it first.', 409,
+        { cash_out_id: String(open.row.id), status: open.status });
+    }
+    const approval = await authority.insertEvent({
+      kind: 'cashout_approved', actor, recipient_id: String(builderId),
+      amount_cents: amount, currency: CURRENCY, note: 'My own cash-out to my bank.',
+    }, { pool: db });
+    const { rows } = await db.query(
+      `INSERT INTO cash_outs (builder_id, approval_id, from_account, amount_cents, currency, instruction_id)
+       VALUES ($1,$2,$3,$4,$5,$6) RETURNING ${CASH_OUT_COLS}`,
+      [builderId, approval.id, from, amount, CURRENCY, instructionId]);
+    return rows[0];
+  });
+
+  const out = await sendCashOut(row, { pool, authority, processor, actorId: builderId, timeoutMs });
+  return { ...out, cash_out: present(row, await readAttempts(pool, row.id)) };
+}
+
+async function ownCashOut(pool, builderId, cashOutId) {
+  if (!isId(cashOutId)) throw new CashOutRefusal('bad_cash_out_id', 'cash-out id must be a number.');
+  const row = await readCashOut(pool, cashOutId);
+  if (!row || String(row.builder_id) !== String(builderId)) throw new CashOutRefusal('no_such_cash_out', 'You have no cash-out with that id.', 404);
+  return row;
+}
+
+// retryCashOut({ builderId, cashOutId }, deps) — try an open withdrawal again. Safe to press
+// any number of times: the key changes only when the processor said the last try did not pay.
+async function retryCashOut({ builderId, cashOutId }, {
+  pool = defaultPool(), authority = defaultAuthority(), processor = null, timeoutMs = PROCESSOR_TIMEOUT_MS,
+} = {}) {
+  const row = await ownCashOut(pool, builderId, cashOutId);
+  const out = await sendCashOut(row, { pool, authority, processor, actorId: builderId, timeoutMs });
+  return { ...out, cash_out: present(row, await readAttempts(pool, row.id)) };
+}
+
+// cancelCashOut({ builderId, cashOutId }, deps) — the person withdraws a request that has not
+// been sent. A sent one cannot be cancelled here: it is with the processor and the bank.
+async function cancelCashOut({ builderId, cashOutId }, { pool = defaultPool() } = {}) {
+  const row = await ownCashOut(pool, builderId, cashOutId);
+  return inTx(pool, async (db) => {
+    await lock(db, `c:${row.id}`);
+    const s = standing(await readAttempts(db, row.id));
+    if (s.status === 'cancelled') return { status: 'cancelled', already: true, cash_out: present(row, await readAttempts(db, row.id)) };
+    if (!OPEN.includes(s.status)) {
+      throw new CashOutRefusal('cannot_cancel', s.status === 'paid' ? 'This cash-out has already reached your bank.' : 'This cash-out is already on its way to your bank and cannot be cancelled here.', 409);
+    }
+    await insertAttempt(db, row.id, s.try_no, { outcome: 'cancelled', reason: 'cancelled by the person', actorId: builderId });
+    return { status: 'cancelled', already: false, cash_out: present(row, await readAttempts(db, row.id)) };
+  });
+}
+
+// recordProcessorOutcome({ processorRef, outcome, reason }, { pool }) — the processor
+// adapter's later news about a sent payout: `paid` (it reached the bank) or `returned` (the
+// bank sent it back; the money is in the person's balance again and the next try gets a new
+// key). Repeating the same news is a no-op. Returns null for a reference we never sent.
+async function recordProcessorOutcome({ processorRef, outcome, reason = null }, { pool = defaultPool() } = {}) {
+  if (outcome !== 'paid' && outcome !== 'returned') throw new CashOutRefusal('bad_outcome', 'outcome is paid or returned.');
+  const ref = typeof processorRef === 'string' ? processorRef.trim() : '';
+  if (!ref) throw new CashOutRefusal('bad_reference', 'processorRef is the payout reference the processor gave.');
+  if (outcome === 'returned' && !String(reason || '').trim()) throw new CashOutRefusal('no_reason', 'A returned payout says why.');
+  const { rows } = await pool.query("SELECT cash_out_id, try_no FROM cash_out_attempts WHERE processor_ref = $1 AND outcome = 'sent'", [ref]);
+  if (!rows[0]) return null;
+  const { cash_out_id: id, try_no: tryNo } = rows[0];
+  return inTx(pool, async (db) => {
+    await lock(db, `c:${id}`);
+    const attempts = await readAttempts(db, id);
+    const mine = attempts.filter((a) => Number(a.try_no) === Number(tryNo) && a.processor_ref === ref);
+    if (mine.some((a) => a.outcome === 'returned')) return { cash_out_id: String(id), status: 'returned', already: true };
+    if (outcome === 'paid' && mine.some((a) => a.outcome === 'paid')) return { cash_out_id: String(id), status: 'paid', already: true };
+    await insertAttempt(db, id, tryNo, { outcome, processorRef: ref, reason: outcome === 'returned' ? reason : null });
+    return { cash_out_id: String(id), status: outcome, already: false };
+  });
+}
+
+// listMyCashOuts(builderId, { pool, account, processor, limit }) — the person's own
+// withdrawals, newest first, each in plain words, with the minimum and their balance.
+async function listMyCashOuts(builderId, { pool = defaultPool(), account = defaultAccount(), processor = null, limit = 20, log = null } = {}) {
+  const lim = Math.min(Math.max(parseInt(limit, 10) || 20, 1), 100);
+  const { rows } = await pool.query(`SELECT ${CASH_OUT_COLS} FROM cash_outs WHERE builder_id = $1 ORDER BY id DESC LIMIT $2`, [builderId, lim]);
+  const ids = rows.map((r) => String(r.id));
+  const byId = new Map(ids.map((id) => [id, []]));
+  if (ids.length) {
+    const { rows: tries } = await pool.query(
+      'SELECT id, cash_out_id, try_no, outcome, processor_ref, reason, created_at FROM cash_out_attempts WHERE cash_out_id = ANY($1::bigint[]) ORDER BY id', [ids]);
+    for (const t of tries) byId.get(String(t.cash_out_id)).push(t);
+  }
+  const from = account && typeof account.memberAccount === 'function' ? await account.memberAccount(pool, builderId) : null;
+  return {
+    unit: 'cents', holds_money: false, source: 'processor',
+    minimum_cents: MIN_CASH_OUT_CENTS, connected: Boolean(from),
+    balance_micro: await readBalance(processor, from, log),
+    cash_outs: rows.map((r) => present(r, byId.get(String(r.id)))),
+  };
+}
+
+const api = {
+  CashOutRefusal, HELD_WORDS, STATUS_WORDS, MIN_CASH_OUT_CENTS, idempotencyKey, standing,
+  requestCashOut, retryCashOut, cancelCashOut, recordProcessorOutcome, listMyCashOuts,
+};
+module.exports = api;