@firedrill-tools/trolley 0.1.1

package/firedrill/tools/trolley/ops/accounts-write.mjs

@@ -0,0 +1,117 @@
+// PATCH and DELETE /v1/recipients/{recipientId}/accounts/{accountId}.
+import { requireKey } from "../lib/access.mjs";
+import { accountOrFail, accountsOf, hasPendingOpenPayment, recipientOrFail, refreshRecipient } from "../lib/records.mjs";
+import { accountOut } from "../lib/serialize.mjs";
+import { accountRowId } from "../lib/store.mjs";
+import { nowIso } from "../lib/time.mjs";
+import { checkCountry, checkCurrency, checkDigits, checkEmail, checkText, empty, hasOwn, invalid, rejectReservedKeys, requireText } from "../lib/validate.mjs";
+
+const IMMUTABLE = {
+  type: "Create a new account to change the payout method",
+  country: "Create a new account to change the bank country",
+  accountNum: "Create a new account to change the account number",
+  iban: "Create a new account to change the account number",
+};
+const BRANCH_DIGITS = { US: 9, CA: 5, GB: 6, AU: 6 };
+
+function notApplicable(context, field) {
+  invalid(context, field, "Field does not apply to this payout method");
+}
+
+function applyChanges(context, account, changes) {
+  const next = { ...account };
+  const bank = account.type === "bank-transfer";
+  for (const key of Object.keys(changes)) {
+    if (Object.hasOwn(IMMUTABLE, key)) invalid(context, key, IMMUTABLE[key]);
+  }
+  if (hasOwn(changes, "primary") && changes.primary !== true) invalid(context, "primary", "Set another account as primary instead");
+  if (hasOwn(changes, "accountHolderName")) {
+    if (!bank) notApplicable(context, "accountHolderName");
+    next.accountHolderName = requireText(context, changes, "accountHolderName", 200);
+  }
+  if (hasOwn(changes, "currency")) {
+    const currency = checkCurrency(context, changes.currency, "currency");
+    if (!bank && account.type !== "paypal" && currency !== "USD") invalid(context, "currency", "This payout method pays in USD");
+    next.currency = currency;
+  }
+  if (hasOwn(changes, "emailAddress")) {
+    if (account.type !== "paypal") notApplicable(context, "emailAddress");
+    next.emailAddress = checkEmail(context, changes.emailAddress, "emailAddress");
+  }
+  if (hasOwn(changes, "phoneNumber")) {
+    if (account.type !== "venmo") notApplicable(context, "phoneNumber");
+    const raw = typeof changes.phoneNumber === "string" ? changes.phoneNumber.replace(/[-() +]/g, "") : changes.phoneNumber;
+    next.phoneNumber = checkDigits(context, raw, "phoneNumber", 10, 11);
+  }
+  if (hasOwn(changes, "mailing")) {
+    if (account.type !== "check") notApplicable(context, "mailing");
+    const value = changes.mailing;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) empty(context, "mailing");
+    const mailing = { ...account.mailing };
+    for (const key of Object.keys(value)) {
+      if (!["name", "street1", "street2", "city", "region", "postal", "country"].includes(key)) invalid(context, `mailing.${key}`, "Field is not allowed");
+      if (key === "street2") mailing.street2 = value.street2 === null || value.street2 === "" ? null : checkText(context, value.street2, "mailing.street2", 200);
+      else mailing[key] = requireText(context, value, key, 200, `mailing.${key}`);
+    }
+    if (checkCountry(context, mailing.country, "mailing.country") !== "US") invalid(context, "mailing.country", "Checks can only be mailed within the US");
+    mailing.country = "US";
+    next.mailing = mailing;
+  }
+  if (hasOwn(changes, "branchId")) {
+    if (!bank || !Object.hasOwn(BRANCH_DIGITS, account.country)) notApplicable(context, "branchId");
+    const n = BRANCH_DIGITS[account.country];
+    next.branchId = checkDigits(context, changes.branchId, "branchId", n, n);
+  }
+  if (hasOwn(changes, "bankId")) {
+    if (!bank || account.country !== "CA") notApplicable(context, "bankId");
+    next.bankId = checkDigits(context, changes.bankId, "bankId", 3, 3);
+  }
+  if (hasOwn(changes, "swiftBic")) {
+    if (!bank) notApplicable(context, "swiftBic");
+    if (changes.swiftBic === null || changes.swiftBic === "") next.swiftBic = null;
+    else {
+      const swift = checkText(context, changes.swiftBic, "swiftBic", 11).toUpperCase();
+      if (!/^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/.test(swift)) invalid(context, "swiftBic", "SWIFT/BIC is invalid");
+      next.swiftBic = swift;
+    }
+  }
+  return next;
+}
+
+export function accountsUpdate(input, context) {
+  requireKey(context, true);
+  rejectReservedKeys(context, input);
+  const recipient = recipientOrFail(context, input.recipientId);
+  const account = accountOrFail(context, recipient.id, input.accountId);
+  const { recipientId, accountId, ...changes } = input;
+  if (Object.keys(changes).length === 0) empty(context, "body");
+  if (account.status === "disabled") context.fail({ code: "INVALID_STATUS", message: "Account is disabled" });
+  const now = nowIso(context);
+  const next = { ...applyChanges(context, account, changes), updatedAt: now };
+  const siblings = accountsOf(context, recipient.id);
+  if (changes.primary === true && !account.primary) {
+    for (const sibling of siblings) {
+      if (sibling.id === account.id || !sibling.primary) continue;
+      context.state.put("recipient_accounts", accountRowId(recipient.id, sibling.id), { ...sibling, primary: false, status: "active", updatedAt: now });
+    }
+    next.primary = true;
+    next.status = "primary";
+  }
+  context.state.put("recipient_accounts", accountRowId(recipient.id, account.id), next);
+  refreshRecipient(context, recipient, accountsOf(context, recipient.id), now);
+  return { ok: true, account: accountOut(next) };
+}
+
+export function accountsDelete(input, context) {
+  requireKey(context, true);
+  const recipient = recipientOrFail(context, input.recipientId);
+  const account = accountOrFail(context, recipient.id, input.accountId);
+  if (account.status === "disabled") context.fail({ code: "INVALID_STATUS", message: "Account is already disabled" });
+  if (hasPendingOpenPayment(context, (payment) => payment.accountId === account.id)) {
+    context.fail({ code: "INVALID_STATUS", message: "Account has pending payments" });
+  }
+  const now = nowIso(context);
+  context.state.put("recipient_accounts", accountRowId(recipient.id, account.id), { ...account, primary: false, status: "disabled", disabledAt: now, updatedAt: now });
+  refreshRecipient(context, recipient, accountsOf(context, recipient.id), now);
+  return { ok: true };
+}

package/firedrill/tools/trolley/ops/accounts.mjs

@@ -0,0 +1,129 @@
+// Recipient accounts (payout methods): bank-transfer, paypal, check, venmo. Full account numbers are never stored.
+import { requireKey } from "../lib/access.mjs";
+import { nextId } from "../lib/ids.mjs";
+import { accountOrFail, accountsOf, hasPendingOpenPayment, recipientOrFail, refreshRecipient } from "../lib/records.mjs";
+import { accountOut, activeAccounts } from "../lib/serialize.mjs";
+import { accountRowId } from "../lib/store.mjs";
+import { nowIso } from "../lib/time.mjs";
+import { IBAN_COUNTRIES, checkCountry, checkCurrency, checkDigits, checkEmail, checkText, empty, fieldError, hasOwn, invalid, requireText } from "../lib/validate.mjs";
+
+const MAX_ACCOUNTS = 20;
+const BRANCH_DIGITS = { US: 9, CA: 5, GB: 6, AU: 6 };
+
+function bankName(country) {
+  return `Firedrill Test Bank ${country}`;
+}
+
+function checkSwift(context, value, field) {
+  const text = checkText(context, value, field, 11).toUpperCase();
+  if (!/^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/.test(text)) invalid(context, field, "SWIFT/BIC is invalid");
+  return text;
+}
+
+function checkMailing(context, value, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) empty(context, field);
+  const out = {};
+  for (const key of ["name", "street1", "city", "region", "postal", "country"]) out[key] = requireText(context, value, key, 200, `${field}.${key}`);
+  out.street2 = hasOwn(value, "street2") && value.street2 !== null ? checkText(context, value.street2, `${field}.street2`, 200) : null;
+  out.country = checkCountry(context, out.country, `${field}.country`);
+  if (out.country !== "US") invalid(context, `${field}.country`, "Checks can only be mailed within the US");
+  return out;
+}
+
+function blank(recipientId, id, type, now) {
+  return {
+    id, recipientId, type, primary: false, status: "active", currency: "USD", country: "US", accountHolderName: null,
+    accountNumLast4: null, ibanLast4: null, bankId: null, branchId: null, swiftBic: null, bankName: null,
+    emailAddress: null, phoneNumber: null, mailing: null, disabledAt: null, createdAt: now, updatedAt: now,
+  };
+}
+
+/** Validates a create payload and returns an unsaved account row (ids allocated). `p` prefixes field names. */
+export function buildAccount(context, recipient, input, p, now) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) invalid(context, p.replace(/\.$/, "") || "accounts");
+  const type = requireText(context, input, "type", 40, `${p}type`);
+  if (type === "debit-card" || type === "mobile-wallet") invalid(context, `${p}type`, "This payout method cannot be created via the API");
+  if (!["bank-transfer", "paypal", "check", "venmo"].includes(type)) invalid(context, `${p}type`, "Payout method is not supported");
+  const fallbackCountry = typeof recipient.address?.country === "string" ? recipient.address.country : "US";
+  const row = blank(recipient.id, nextId(context, "A"), type, now);
+  if (type === "bank-transfer") {
+    row.currency = checkCurrency(context, input.currency, `${p}currency`);
+    row.country = checkCountry(context, input.country, `${p}country`);
+    row.accountHolderName = requireText(context, input, "accountHolderName", 200, `${p}accountHolderName`);
+    const usesIban = hasOwn(input, "iban") && input.iban !== null;
+    if (usesIban) {
+      const iban = checkText(context, input.iban, `${p}iban`, 42).replace(/ /g, "").toUpperCase();
+      if (!IBAN_COUNTRIES.includes(row.country) || !/^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$/.test(iban) || iban.slice(0, 2) !== row.country) invalid(context, `${p}iban`, "IBAN is invalid");
+      row.ibanLast4 = iban.slice(-4);
+    } else {
+      if (!hasOwn(input, "accountNum")) empty(context, IBAN_COUNTRIES.includes(row.country) && row.country !== "GB" ? `${p}iban` : `${p}accountNum`);
+      row.accountNumLast4 = checkDigits(context, input.accountNum, `${p}accountNum`, 4, 34).slice(-4);
+      if (Object.hasOwn(BRANCH_DIGITS, row.country)) {
+        if (!hasOwn(input, "branchId")) empty(context, `${p}branchId`);
+        const n = BRANCH_DIGITS[row.country];
+        row.branchId = checkDigits(context, input.branchId, `${p}branchId`, n, n);
+      }
+      if (row.country === "CA") {
+        if (!hasOwn(input, "bankId")) empty(context, `${p}bankId`);
+        row.bankId = checkDigits(context, input.bankId, `${p}bankId`, 3, 3);
+      }
+    }
+    if (hasOwn(input, "swiftBic") && input.swiftBic !== null) row.swiftBic = checkSwift(context, input.swiftBic, `${p}swiftBic`);
+    row.bankName = bankName(row.country);
+  } else if (type === "paypal") {
+    row.emailAddress = checkEmail(context, input.emailAddress, `${p}emailAddress`);
+    row.currency = hasOwn(input, "currency") ? checkCurrency(context, input.currency, `${p}currency`) : "USD";
+    row.country = hasOwn(input, "country") ? checkCountry(context, input.country, `${p}country`) : fallbackCountry;
+  } else if (type === "venmo") {
+    if (hasOwn(input, "country") && checkCountry(context, input.country, `${p}country`) !== "US") invalid(context, `${p}country`, "Venmo is only available in the US");
+    if (hasOwn(input, "currency") && checkCurrency(context, input.currency, `${p}currency`) !== "USD") invalid(context, `${p}currency`, "Venmo pays in USD");
+    row.phoneNumber = checkDigits(context, typeof input.phoneNumber === "string" ? input.phoneNumber.replace(/[-() +]/g, "") : input.phoneNumber, `${p}phoneNumber`, 10, 11);
+  } else {
+    if (hasOwn(input, "currency") && checkCurrency(context, input.currency, `${p}currency`) !== "USD") invalid(context, `${p}currency`, "Checks are paid in USD");
+    row.mailing = checkMailing(context, input.mailing, `${p}mailing`);
+  }
+  if (hasOwn(input, "primary") && typeof input.primary !== "boolean") invalid(context, `${p}primary`);
+  row.primary = input.primary === true;
+  return row;
+}
+
+/** Stores `row`, making it primary when requested or when no active primary exists, demoting siblings. */
+export function attachAccount(context, row, existing) {
+  const active = existing.filter((account) => account.status !== "disabled");
+  if (active.length >= MAX_ACCOUNTS) invalid(context, "type", "Recipient has the maximum number of payout methods");
+  const makePrimary = row.primary || !active.some((account) => account.primary);
+  if (makePrimary) {
+    for (const sibling of active.filter((account) => account.primary)) {
+      context.state.put("recipient_accounts", accountRowId(sibling.recipientId, sibling.id), { ...sibling, primary: false, status: "active", updatedAt: row.updatedAt });
+    }
+  }
+  const stored = { ...row, primary: makePrimary, status: makePrimary ? "primary" : "active" };
+  context.state.put("recipient_accounts", accountRowId(row.recipientId, row.id), stored);
+  return stored;
+}
+
+export function accountsCreate(input, context) {
+  requireKey(context, true);
+  const recipient = recipientOrFail(context, input.recipientId);
+  if (recipient.status === "archived") context.fail({ code: "INVALID_STATUS", message: "Recipient is archived" });
+  const now = nowIso(context);
+  const existing = accountsOf(context, recipient.id);
+  const { recipientId, ...payload } = input;
+  const stored = attachAccount(context, buildAccount(context, recipient, payload, "", now), existing);
+  refreshRecipient(context, recipient, accountsOf(context, recipient.id), now);
+  return { ok: true, account: accountOut(stored) };
+}
+
+export function accountsList(input, context) {
+  requireKey(context, false);
+  const recipient = recipientOrFail(context, input.recipientId);
+  return { ok: true, accounts: activeAccounts(accountsOf(context, recipient.id)).map(accountOut) };
+}
+
+export function accountsGet(input, context) {
+  requireKey(context, false);
+  recipientOrFail(context, input.recipientId);
+  return { ok: true, account: accountOut(accountOrFail(context, input.recipientId, input.accountId)) };
+}
+
+export { fieldError };

package/firedrill/tools/trolley/ops/balances.mjs

@@ -0,0 +1,23 @@
+// GET /v1/balances and /v1/balances/{kind}. `serverTime` (virtual time) is a Firedrill addition for the app.
+import { requireKey } from "../lib/access.mjs";
+import { scanAll } from "../lib/store.mjs";
+import { nowIso } from "../lib/time.mjs";
+import { checkEnum, hasOwn } from "../lib/validate.mjs";
+
+export function balancesList(input, context) {
+  requireKey(context, false);
+  const kind = hasOwn(input, "kind") ? checkEnum(context, input.kind, ["paymentrails", "paypal"], "kind") : undefined;
+  const balances = scanAll(context, "balances")
+    .filter((row) => kind === undefined || row.type === kind)
+    .sort((a, b) => (a.primary !== b.primary ? (a.primary ? -1 : 1) : a.currency < b.currency ? -1 : a.currency > b.currency ? 1 : a.type < b.type ? -1 : 1))
+    .map((row) => ({
+      primary: row.primary,
+      amount: row.amount,
+      currency: row.currency,
+      type: row.type,
+      accountNumber: row.accountNumber,
+      display: row.display,
+      pendingAmount: row.pendingAmount,
+    }));
+  return { ok: true, balances, serverTime: nowIso(context) };
+}

package/firedrill/tools/trolley/ops/batches.mjs

@@ -0,0 +1,139 @@
+// Batches: create (optionally with payments), get, update, delete, list, summary.
+import { merchant, requireKey } from "../lib/access.mjs";
+import { nextId } from "../lib/ids.mjs";
+import { fromCents, toCents } from "../lib/money.mjs";
+import { filterList, filterText, pageArgs, pageOf, sortArgs, sortItems } from "../lib/paging.mjs";
+import { batchOrFail, paymentsOf } from "../lib/records.mjs";
+import { batchOut } from "../lib/serialize.mjs";
+import { paymentRowId, scanAll } from "../lib/store.mjs";
+import { nowIso } from "../lib/time.mjs";
+import { CURRENCIES, checkCurrency, checkEnum, checkTags, checkText, hasOwn, invalid, rejectReservedKeys } from "../lib/validate.mjs";
+import { MAX_PAYMENTS, createPayment } from "./payment-build.mjs";
+
+const STATUSES = ["open", "processing", "complete", "failed"];
+
+export function batchesCreate(input, context) {
+  requireKey(context, true);
+  rejectReservedKeys(context, input);
+  const payments = hasOwn(input, "payments") ? input.payments : [];
+  if (!Array.isArray(payments)) invalid(context, "payments");
+  if (payments.length > MAX_PAYMENTS) invalid(context, "payments", `A batch can hold at most ${MAX_PAYMENTS} payments`);
+  const first = payments[0] !== null && typeof payments[0] === "object" ? payments[0] : {};
+  const currencySource = hasOwn(input, "currency") ? ["currency", input.currency]
+    : hasOwn(first, "sourceCurrency") ? ["payments[0].sourceCurrency", first.sourceCurrency]
+    : hasOwn(first, "currency") && hasOwn(first, "amount") ? ["payments[0].currency", first.currency] : undefined;
+  const currency = currencySource === undefined ? merchant(context).defaultCurrency : checkCurrency(context, currencySource[1], currencySource[0]);
+  const now = nowIso(context);
+  const batch = {
+    id: nextId(context, "B"), status: "open", currency,
+    description: hasOwn(input, "description") && input.description !== null ? checkText(context, input.description, "description", 1024) : "",
+    tags: hasOwn(input, "tags") ? checkTags(context, input.tags) : [],
+    quoteExpiredAt: null, sentAt: null, completedAt: null, createdAt: now, updatedAt: now,
+  };
+  context.state.put("batches", batch.id, batch);
+  const rows = [];
+  for (const [index, payment] of payments.entries()) {
+    rows.push(createPayment(context, batch, payment, `payments[${index}].`, now, rows).row);
+  }
+  return { ok: true, batch: batchOut(batch, rows) };
+}
+
+export function batchesGet(input, context) {
+  requireKey(context, false);
+  const batch = batchOrFail(context, input.batchId);
+  return { ok: true, batch: batchOut(batch, paymentsOf(context, batch.id)) };
+}
+
+export function batchesUpdate(input, context) {
+  requireKey(context, true);
+  rejectReservedKeys(context, input);
+  const batch = batchOrFail(context, input.batchId);
+  for (const key of ["status", "amount", "totalPayments", "quoteExpiredAt", "sentAt", "completedAt"]) {
+    if (hasOwn(input, key)) invalid(context, key, "Field is read-only");
+  }
+  if (batch.status !== "open") context.fail({ code: "INVALID_STATUS", message: "Batch is not open" });
+  const payments = paymentsOf(context, batch.id);
+  const next = { ...batch, updatedAt: nowIso(context) };
+  if (hasOwn(input, "description")) next.description = input.description === null ? "" : checkText(context, input.description, "description", 1024);
+  if (hasOwn(input, "tags")) next.tags = checkTags(context, input.tags);
+  if (hasOwn(input, "currency")) {
+    const currency = checkCurrency(context, input.currency, "currency");
+    if (currency !== batch.currency && payments.length > 0) invalid(context, "currency", "Currency cannot change once the batch has payments");
+    if (currency !== batch.currency) next.quoteExpiredAt = null;
+    next.currency = currency;
+  }
+  context.state.put("batches", batch.id, next);
+  return { ok: true, batch: batchOut(next, payments) };
+}
+
+export function batchesDelete(input, context) {
+  requireKey(context, true);
+  const batch = batchOrFail(context, input.batchId);
+  if (batch.status !== "open") context.fail({ code: "INVALID_STATUS", message: "Only open batches can be deleted" });
+  for (const payment of paymentsOf(context, batch.id)) {
+    context.state.delete("payments", paymentRowId(batch.id, payment.id));
+    context.state.delete("payment_index", payment.id);
+  }
+  context.state.delete("batches", batch.id);
+  return { ok: true };
+}
+
+export function batchesList(input, context) {
+  requireKey(context, false);
+  const paging = pageArgs(context, input);
+  const search = filterText(context, input, "search")?.toLowerCase();
+  const status = hasOwn(input, "status") ? checkEnum(context, input.status, STATUSES, "status") : undefined;
+  const currency = hasOwn(input, "currency") ? checkEnum(context, String(input.currency).toUpperCase(), CURRENCIES, "currency") : undefined;
+  const tags = filterList(context, input, "tags");
+  const { orderBy, sortBy } = sortArgs(context, input, ["createdAt", "amount", "status"], "createdAt");
+  const byBatch = new Map();
+  for (const payment of scanAll(context, "payments")) {
+    if (!byBatch.has(payment.batchId)) byBatch.set(payment.batchId, []);
+    byBatch.get(payment.batchId).push(payment);
+  }
+  const items = scanAll(context, "batches")
+    .filter((batch) => {
+      if (status !== undefined && batch.status !== status) return false;
+      if (currency !== undefined && batch.currency !== currency) return false;
+      if (tags !== undefined && !tags.every((tag) => (batch.tags ?? []).includes(tag))) return false;
+      if (search !== undefined && ![batch.id, batch.description, ...(batch.tags ?? [])].some((field) => String(field).toLowerCase().includes(search))) return false;
+      return true;
+    })
+    .map((batch) => batchOut(batch, byBatch.get(batch.id) ?? []));
+  sortItems(items, orderBy === "amount" ? (item) => toCents(item.amount) : (item) => item[orderBy], sortBy);
+  return pageOf(context, items, paging, "batches");
+}
+
+function emptySummary() {
+  return { count: 0, totalFees: 0n, merchantFees: 0n, sendingAmount: 0n };
+}
+
+function renderSummary(entry) {
+  return {
+    count: entry.count,
+    totalFees: fromCents(entry.totalFees),
+    merchantFees: fromCents(entry.merchantFees),
+    debitAmount: fromCents(entry.sendingAmount + entry.merchantFees),
+    sendingAmount: fromCents(entry.sendingAmount),
+    totalWithheld: "0.00",
+  };
+}
+
+export function batchesSummary(input, context) {
+  requireKey(context, false);
+  const batch = batchOrFail(context, input.batchId);
+  const detail = new Map();
+  const total = emptySummary();
+  for (const payment of paymentsOf(context, batch.id)) {
+    if (!detail.has(payment.payoutMethod)) detail.set(payment.payoutMethod, emptySummary());
+    for (const entry of [detail.get(payment.payoutMethod), total]) {
+      entry.count += 1;
+      entry.totalFees += toCents(payment.fees);
+      entry.merchantFees += toCents(payment.merchantFees);
+      entry.sendingAmount += toCents(payment.sourceAmount);
+    }
+  }
+  const rendered = {};
+  for (const method of [...detail.keys()].sort()) rendered[method] = renderSummary(detail.get(method));
+  return { ok: true, batchSummary: { detail: rendered, total: renderSummary(total) } };
+}

package/firedrill/tools/trolley/ops/payment-build.mjs

@@ -0,0 +1,79 @@
+// Payment validation and construction shared by POST /v1/batches (with payments) and POST /v1/batches/{id}/payments.
+import { nextId } from "../lib/ids.mjs";
+import { fromCents, isAmount, toCents } from "../lib/money.mjs";
+import { pricePayment } from "../lib/pricing.mjs";
+import { accountsOf, resolveRecipient } from "../lib/records.mjs";
+import { primaryAccount } from "../lib/serialize.mjs";
+import { paymentRowId } from "../lib/store.mjs";
+import { CATEGORIES, checkCurrency, checkTags, checkText, empty, fieldError, hasOwn, invalid } from "../lib/validate.mjs";
+
+export const MAX_PAYMENTS = 1000;
+const BLOCKED = ["archived", "suspended", "blocked", "disabled"];
+const PAIRS = [["amount", "currency"], ["sourceAmount", "sourceCurrency"], ["targetAmount", "targetCurrency"]];
+
+function checkAmount(context, value, field) {
+  if (value === undefined || value === null || value === "") empty(context, field);
+  if (!isAmount(value) || toCents(value) === 0n) invalid(context, field, "Amount must be a positive decimal with at most two decimals");
+  return fromCents(toCents(value));
+}
+
+/** The amount pair the caller fixed: `{ side, amount }` for the batch currency or the payout account currency. */
+export function amountChoice(context, input, p, batchCurrency, account) {
+  const present = PAIRS.filter(([amountKey, currencyKey]) => hasOwn(input, amountKey) || hasOwn(input, currencyKey));
+  if (present.length === 0) empty(context, `${p}amount`);
+  if (present.length > 1) invalid(context, `${p}${present[1][0]}`, "Send exactly one amount and currency pair");
+  const [amountKey, currencyKey] = present[0];
+  const amount = checkAmount(context, input[amountKey], `${p}${amountKey}`);
+  if (!hasOwn(input, currencyKey)) empty(context, `${p}${currencyKey}`);
+  const currency = checkCurrency(context, input[currencyKey], `${p}${currencyKey}`);
+  const payoutCurrency = account.type === "paypal" ? batchCurrency : account.currency;
+  const isSource = currency === batchCurrency && amountKey !== "targetAmount";
+  const isTarget = currency === payoutCurrency && amountKey !== "sourceAmount";
+  if (!isSource && !isTarget) invalid(context, `${p}${currencyKey}`, "Currency must be the batch currency or the recipient's payout currency");
+  return isSource ? { side: "source", amount } : { side: "target", amount };
+}
+
+/** Optional descriptive payment fields into `row`. */
+export function applyPaymentDetails(context, input, p, row) {
+  if (hasOwn(input, "memo")) row.memo = input.memo === null ? "" : checkText(context, input.memo, `${p}memo`, 1024);
+  if (hasOwn(input, "externalId")) row.externalId = input.externalId === null || input.externalId === "" ? null : checkText(context, input.externalId, `${p}externalId`, 100);
+  if (hasOwn(input, "coverFees")) {
+    if (typeof input.coverFees !== "boolean") invalid(context, `${p}coverFees`);
+    row.coverFees = input.coverFees;
+  }
+  if (hasOwn(input, "category")) {
+    if (input.category !== null && !CATEGORIES.includes(input.category)) invalid(context, `${p}category`);
+    row.category = input.category;
+  }
+  if (hasOwn(input, "tags")) row.tags = checkTags(context, input.tags, `${p}tags`);
+}
+
+export function assertExternalIdFree(context, payments, externalId, selfId, field) {
+  if (typeof externalId !== "string") return;
+  if (payments.some((payment) => payment.id !== selfId && payment.externalId === externalId)) invalid(context, field, "External ID already exists in this batch");
+}
+
+/** Validates and stores one pending payment in `batch`; returns `{ row, recipient }`. */
+export function createPayment(context, batch, input, p, now, existing) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) invalid(context, p.replace(/\.$/, ""));
+  if (existing.length >= MAX_PAYMENTS) invalid(context, `${p}amount`, "Batch has the maximum number of payments");
+  if (!hasOwn(input, "recipient")) empty(context, `${p}recipient`);
+  const recipient = resolveRecipient(context, input.recipient, `${p}recipient`);
+  if (BLOCKED.includes(recipient.status)) fieldError(context, "INVALID_STATUS", `${p}recipient`, `Recipient is ${recipient.status}`);
+  const account = primaryAccount(accountsOf(context, recipient.id));
+  if (account === null) fieldError(context, "INVALID_STATUS", `${p}recipient`, "Recipient has no primary payout method");
+  const choice = amountChoice(context, input, p, batch.currency, account);
+  const row = {
+    id: nextId(context, "P"), batchId: batch.id, recipientId: recipient.id, accountId: account.id, status: "pending",
+    amountSide: choice.side, sourceAmount: choice.side === "source" ? choice.amount : "0.00", sourceCurrency: batch.currency,
+    targetAmount: choice.side === "target" ? choice.amount : "0.00", targetCurrency: batch.currency, exchangeRate: "1.000000",
+    fees: "0.00", recipientFees: "0.00", merchantFees: "0.00", coverFees: false, payoutMethod: account.type, memo: "",
+    externalId: null, category: null, tags: [], failureMessage: null, initiatedAt: null, processedAt: null, createdAt: now, updatedAt: now,
+  };
+  applyPaymentDetails(context, input, p, row);
+  assertExternalIdFree(context, existing, row.externalId, row.id, `${p}externalId`);
+  const priced = pricePayment(context, row, account);
+  context.state.put("payments", paymentRowId(batch.id, priced.id), priced);
+  context.state.put("payment_index", priced.id, { batchId: batch.id });
+  return { row: priced, recipient };
+}

package/firedrill/tools/trolley/ops/payments.mjs

@@ -0,0 +1,112 @@
+// Payments inside batches: create, list, get (two paths), update, delete.
+import { requireKey } from "../lib/access.mjs";
+import { isId } from "../lib/ids.mjs";
+import { filterText, pageArgs, pageOf, sortItems } from "../lib/paging.mjs";
+import { pricePayment } from "../lib/pricing.mjs";
+import { accountsOf, batchOrFail, merchantId, notFound, paymentOrFail, paymentsOf } from "../lib/records.mjs";
+import { paymentOut, primaryAccount } from "../lib/serialize.mjs";
+import { accountRowId, paymentRowId } from "../lib/store.mjs";
+import { nowIso } from "../lib/time.mjs";
+import { checkEnum, empty, hasOwn, invalid, rejectReservedKeys } from "../lib/validate.mjs";
+import { amountChoice, applyPaymentDetails, assertExternalIdFree, createPayment } from "./payment-build.mjs";
+
+const STATUSES = ["pending", "processing", "processed", "failed"];
+
+function openBatch(context, id) {
+  const batch = batchOrFail(context, id);
+  if (batch.status !== "open") context.fail({ code: "INVALID_STATUS", message: "Batch is not open" });
+  return batch;
+}
+
+/** A changed batch needs a new quote. */
+function clearQuote(context, batch, now) {
+  const next = { ...batch, quoteExpiredAt: null, updatedAt: now };
+  context.state.put("batches", batch.id, next);
+  return next;
+}
+
+const out = (context, row, batch) => paymentOut(row, context.state.get("recipients", row.recipientId), batch, merchantId(context));
+
+export function paymentsCreate(input, context) {
+  requireKey(context, true);
+  rejectReservedKeys(context, input);
+  const batch = openBatch(context, input.batchId);
+  const now = nowIso(context);
+  const { batchId, ...payload } = input;
+  const { row } = createPayment(context, batch, payload, "", now, paymentsOf(context, batch.id));
+  return { ok: true, payment: out(context, row, clearQuote(context, batch, now)) };
+}
+
+export function paymentsList(input, context) {
+  requireKey(context, false);
+  const batch = batchOrFail(context, input.batchId);
+  const paging = pageArgs(context, input);
+  const status = hasOwn(input, "status") ? checkEnum(context, input.status, STATUSES, "status") : undefined;
+  const search = filterText(context, input, "search");
+  const needle = search?.toLowerCase();
+  const recipients = new Map();
+  const recipientOf = (id) => {
+    if (!recipients.has(id)) recipients.set(id, context.state.get("recipients", id));
+    return recipients.get(id);
+  };
+  const rows = paymentsOf(context, batch.id).filter((row) => {
+    if (status !== undefined && row.status !== status) return false;
+    if (needle === undefined) return true;
+    const recipient = recipientOf(row.recipientId);
+    return [recipient?.name, recipient?.email, recipient?.referenceId, row.memo, row.externalId]
+      .some((field) => typeof field === "string" && field.toLowerCase().includes(needle));
+  });
+  sortItems(rows, (row) => row.createdAt, "asc");
+  const merchant = merchantId(context);
+  return pageOf(context, rows, paging, "payments", (row) => paymentOut(row, recipientOf(row.recipientId), batch, merchant));
+}
+
+export function paymentsGet(input, context) {
+  requireKey(context, false);
+  let batchId = input.batchId;
+  if (batchId === undefined) {
+    const index = isId("P", input.paymentId) ? context.state.get("payment_index", input.paymentId) : null;
+    if (index === null) notFound(context, "Payment");
+    batchId = index.batchId;
+  }
+  const row = paymentOrFail(context, batchId, input.paymentId);
+  return { ok: true, payment: out(context, row, context.state.get("batches", row.batchId)) };
+}
+
+export function paymentsUpdate(input, context) {
+  requireKey(context, true);
+  rejectReservedKeys(context, input);
+  const batch = batchOrFail(context, input.batchId);
+  const current = paymentOrFail(context, batch.id, input.paymentId);
+  const { batchId, paymentId, ...changes } = input;
+  if (Object.keys(changes).length === 0) empty(context, "body");
+  if (hasOwn(changes, "recipient")) invalid(context, "recipient", "Create a new payment to change the recipient");
+  if (hasOwn(changes, "status")) invalid(context, "status", "Field is read-only");
+  if (batch.status !== "open" || current.status !== "pending") context.fail({ code: "INVALID_STATUS", message: "Only pending payments in an open batch can be changed" });
+  const now = nowIso(context);
+  let row = { ...current, updatedAt: now };
+  const stored = context.state.get("recipient_accounts", accountRowId(current.recipientId, current.accountId));
+  const account = stored !== null && stored.status !== "disabled" ? stored : primaryAccount(accountsOf(context, current.recipientId));
+  if (account === null) context.fail({ code: "INVALID_STATUS", message: "Recipient has no primary payout method" });
+  const amountKeys = ["amount", "currency", "sourceAmount", "sourceCurrency", "targetAmount", "targetCurrency"];
+  if (amountKeys.some((key) => hasOwn(changes, key))) {
+    const choice = amountChoice(context, changes, "", batch.currency, account);
+    row = { ...row, amountSide: choice.side, sourceAmount: choice.side === "source" ? choice.amount : row.sourceAmount, targetAmount: choice.side === "target" ? choice.amount : row.targetAmount };
+  }
+  applyPaymentDetails(context, changes, "", row);
+  if (hasOwn(changes, "externalId")) assertExternalIdFree(context, paymentsOf(context, batch.id), row.externalId, row.id, "externalId");
+  row = pricePayment(context, row, account);
+  context.state.put("payments", paymentRowId(batch.id, row.id), row);
+  return { ok: true, payment: out(context, row, clearQuote(context, batch, now)) };
+}
+
+export function paymentsDelete(input, context) {
+  requireKey(context, true);
+  const batch = batchOrFail(context, input.batchId);
+  const row = paymentOrFail(context, batch.id, input.paymentId);
+  if (batch.status !== "open" || row.status !== "pending") context.fail({ code: "INVALID_STATUS", message: "Only pending payments in an open batch can be deleted" });
+  context.state.delete("payments", paymentRowId(batch.id, row.id));
+  context.state.delete("payment_index", row.id);
+  clearQuote(context, batch, nowIso(context));
+  return { ok: true };
+}