@firedrill-tools/trolley 0.1.1

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

@@ -0,0 +1,104 @@
+// POST /v1/batches/{id}/generate-quote and /start-processing. Every check runs before any write; processing then
+// settles in the same invocation (each payment processed or failed, balance debited, batch complete or failed).
+import { requireKey } from "../lib/access.mjs";
+import { fromCents, toCents } from "../lib/money.mjs";
+import { minimumCents, pricePayment } from "../lib/pricing.mjs";
+import { accountsOf, batchOrFail, merchantId, paymentsOf } from "../lib/records.mjs";
+import { batchOut, paymentOut, primaryAccount } from "../lib/serialize.mjs";
+import { paymentRowId } from "../lib/store.mjs";
+import { isoFromMs, msFromIso, nowIso, nowMs } from "../lib/time.mjs";
+import { fieldError } from "../lib/validate.mjs";
+
+const QUOTE_MS = 90 * 60 * 1000;
+
+function currentAccount(context, payment) {
+  return primaryAccount(accountsOf(context, payment.recipientId));
+}
+
+export function batchesGenerateQuote(input, context) {
+  requireKey(context, true);
+  const batch = batchOrFail(context, input.batchId);
+  if (batch.status !== "open") context.fail({ code: "INVALID_STATUS", message: "Quotes can only be generated for open batches" });
+  const now = nowIso(context);
+  const payments = [];
+  for (const payment of paymentsOf(context, batch.id)) {
+    const account = payment.status === "pending" ? currentAccount(context, payment) : null;
+    const next = account === null ? payment : { ...pricePayment(context, payment, account), updatedAt: now };
+    if (next !== payment) context.state.put("payments", paymentRowId(batch.id, next.id), next);
+    payments.push(next);
+  }
+  const quoted = { ...batch, quoteExpiredAt: isoFromMs(nowMs(context) + QUOTE_MS), updatedAt: now };
+  context.state.put("batches", batch.id, quoted);
+  return { ok: true, batch: batchOut(quoted, payments) };
+}
+
+function event(context, model, action, key, value) {
+  context.events.emit(`${model}.${action}`, { model, action, body: { [key]: value } });
+}
+
+export function batchesStartProcessing(input, context) {
+  requireKey(context, true);
+  const batch = batchOrFail(context, input.batchId);
+  if (batch.status !== "open") context.fail({ code: "INVALID_STATUS", message: "Batch is not open" });
+  const payments = paymentsOf(context, batch.id);
+  if (payments.length === 0) context.fail({ code: "INVALID_STATUS", message: "Batch has no payments" });
+
+  // Plan: which payments are attempted, with their payout account; which fail and why.
+  const plan = payments.map((payment) => {
+    const recipient = context.state.get("recipients", payment.recipientId);
+    if (payment.status !== "pending") return { payment, recipient, skip: true };
+    if (recipient === null || recipient.status !== "active") return { payment, recipient, failure: "Recipient is not active" };
+    const account = currentAccount(context, payment);
+    if (account === null) return { payment, recipient, failure: "Recipient has no primary payout method" };
+    const priced = account.id === payment.accountId && account.type === payment.payoutMethod ? payment : pricePayment(context, payment, account);
+    return { payment: priced, recipient };
+  });
+  const attempted = plan.filter((entry) => !entry.skip && entry.failure === undefined);
+  const nowAt = nowMs(context);
+  if (attempted.some((entry) => entry.payment.sourceCurrency !== entry.payment.targetCurrency)) {
+    const expires = msFromIso(batch.quoteExpiredAt);
+    if (expires === null || expires <= nowAt) context.fail({ code: "EXPIRED_QUOTE", message: "Quote is expired" });
+  }
+  let debit = 0n;
+  for (const { payment } of attempted) {
+    if (toCents(payment.sourceAmount) < minimumCents(context, payment.payoutMethod, payment.sourceCurrency)) {
+      fieldError(context, "INVALID_FIELD", "amount", "Payment amount is below the minimum for this payout method");
+    }
+    debit += toCents(payment.sourceAmount) + toCents(payment.merchantFees);
+  }
+  const balanceId = `paymentrails:${batch.currency}`;
+  const balance = context.state.get("balances", balanceId);
+  const available = balance === null ? 0n : toCents(balance.amount);
+  if (debit > available) context.fail({ code: "NON_SUFFICIENT_FUNDS", message: "Insufficient funds" });
+
+  // Settle.
+  const now = nowIso(context);
+  const merchant = merchantId(context);
+  const sending = { ...batch, status: "processing", sentAt: now, updatedAt: now };
+  event(context, "batch", "processing", "batch", batchOut(sending, plan.map((entry) => entry.payment)));
+  const settled = [];
+  let processed = 0;
+  for (const entry of plan) {
+    if (entry.skip) {
+      settled.push(entry.payment);
+      continue;
+    }
+    const ok = entry.failure === undefined;
+    const row = {
+      ...entry.payment,
+      status: ok ? "processed" : "failed",
+      failureMessage: ok ? null : entry.failure,
+      initiatedAt: now,
+      processedAt: ok ? now : null,
+      updatedAt: now,
+    };
+    context.state.put("payments", paymentRowId(batch.id, row.id), row);
+    settled.push(row);
+    if (ok) processed += 1;
+    event(context, "payment", ok ? "processed" : "failed", "payment", paymentOut(row, entry.recipient, sending, merchant));
+  }
+  if (balance !== null && debit > 0n) context.state.put("balances", balanceId, { ...balance, amount: fromCents(available - debit) });
+  const final = { ...sending, status: processed > 0 ? "complete" : "failed", completedAt: now };
+  context.state.put("batches", batch.id, final);
+  return { ok: true, batch: batchOut(final, settled) };
+}

package/firedrill/tools/trolley/ops/recipients-list.mjs

@@ -0,0 +1,58 @@
+// GET /v1/recipients: search, filters, ordering and page-number paging over one bounded scan per namespace.
+import { requireKey } from "../lib/access.mjs";
+import { filterList, filterText, pageArgs, pageOf, sortArgs, sortItems } from "../lib/paging.mjs";
+import { primaryAccount, recipientOut } from "../lib/serialize.mjs";
+import { scanAll } from "../lib/store.mjs";
+import { CURRENCIES, PAYOUT_METHODS, checkEnum, hasOwn, invalid } from "../lib/validate.mjs";
+
+const STATUSES = ["active", "incomplete", "disabled", "archived", "suspended", "blocked"];
+const COMPLIANCE = ["pending", "review", "verified", "blocked"];
+const ORDER = ["name", "email", "referenceId", "payoutMethod", "createdAt", "updatedAt"];
+
+const lower = (value) => (typeof value === "string" ? value.toLowerCase() : "");
+
+export function recipientsList(input, context) {
+  requireKey(context, false);
+  const paging = pageArgs(context, input);
+  const search = filterText(context, input, "search");
+  const name = filterText(context, input, "name");
+  const email = filterText(context, input, "email", 254);
+  const referenceId = filterText(context, input, "referenceId", 100);
+  const status = hasOwn(input, "status") ? checkEnum(context, input.status, STATUSES, "status") : undefined;
+  const compliance = hasOwn(input, "complianceStatus") ? checkEnum(context, input.complianceStatus, COMPLIANCE, "complianceStatus") : undefined;
+  const countries = filterList(context, input, "country")?.map((code) => code.toUpperCase());
+  const method = hasOwn(input, "payoutMethod") ? checkEnum(context, input.payoutMethod, PAYOUT_METHODS, "payoutMethod") : undefined;
+  const currency = hasOwn(input, "currency") ? checkEnum(context, lower(input.currency).toUpperCase(), CURRENCIES, "currency") : undefined;
+  const tags = filterList(context, input, "tags");
+  const { orderBy, sortBy } = sortArgs(context, input, ORDER, "createdAt");
+  if (countries !== undefined && countries.some((code) => !/^[A-Z]{2}$/.test(code))) invalid(context, "country");
+
+  const byRecipient = new Map();
+  for (const account of scanAll(context, "recipient_accounts")) {
+    if (!byRecipient.has(account.recipientId)) byRecipient.set(account.recipientId, []);
+    byRecipient.get(account.recipientId).push(account);
+  }
+  const accountsFor = (id) => byRecipient.get(id) ?? [];
+  const needle = search === undefined ? undefined : search.toLowerCase();
+  const nameNeedle = name === undefined ? undefined : name.toLowerCase();
+
+  const matched = scanAll(context, "recipients").filter((row) => {
+    if (status === undefined ? row.status === "archived" : row.status !== status) return false;
+    if (compliance !== undefined && row.complianceStatus !== compliance) return false;
+    if (needle !== undefined && ![row.name, row.email, row.referenceId].some((field) => lower(field).includes(needle))) return false;
+    if (nameNeedle !== undefined && ![row.name, row.firstName, row.lastName].some((field) => lower(field).includes(nameNeedle))) return false;
+    if (email !== undefined && lower(row.email) !== email.toLowerCase()) return false;
+    if (referenceId !== undefined && row.referenceId !== referenceId) return false;
+    if (countries !== undefined && !countries.includes(row.address?.country)) return false;
+    if (tags !== undefined && !tags.every((tag) => (row.tags ?? []).includes(tag))) return false;
+    if (method !== undefined || currency !== undefined) {
+      const primary = primaryAccount(accountsFor(row.id));
+      if (method !== undefined && primary?.type !== method) return false;
+      if (currency !== undefined && primary?.currency !== currency) return false;
+    }
+    return true;
+  });
+  const key = orderBy === "payoutMethod" ? (row) => primaryAccount(accountsFor(row.id))?.type ?? null : (row) => row[orderBy] ?? null;
+  sortItems(matched, key, sortBy);
+  return pageOf(context, matched, paging, "recipients", (row) => recipientOut(context, row, accountsFor(row.id)));
+}

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

@@ -0,0 +1,127 @@
+// Recipients: create, get, update, delete (archive). Status is derived on every write (lib/serialize.mjs).
+import { requireKey } from "../lib/access.mjs";
+import { nextId } from "../lib/ids.mjs";
+import { accountsOf, assertUnique, hasPendingOpenPayment, recipientOrFail, refreshRecipient } from "../lib/records.mjs";
+import { deriveStatus, primaryAccount, recipientOut } from "../lib/serialize.mjs";
+import { isDate, nowIso } from "../lib/time.mjs";
+import { checkCountry, checkEmail, checkEnum, checkTags, checkText, empty, hasOwn, invalid, optionalText, rejectReservedKeys, requireText } from "../lib/validate.mjs";
+import { attachAccount, buildAccount } from "./accounts.mjs";
+
+const ADDRESS_KEYS = ["street1", "street2", "city", "region", "postalCode", "country", "phone"];
+
+function checkAddress(context, value, base) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) invalid(context, "address");
+  const out = { ...base };
+  for (const key of Object.keys(value)) {
+    if (!ADDRESS_KEYS.includes(key)) invalid(context, `address.${key}`, "Field is not allowed");
+    const entry = value[key];
+    if (entry === null || entry === "") out[key] = null;
+    else out[key] = key === "country" ? checkCountry(context, entry, "address.country") : checkText(context, entry, `address.${key}`, 200);
+  }
+  return out;
+}
+
+const EMPTY_ADDRESS = { street1: null, street2: null, city: null, region: null, postalCode: null, country: null, phone: null };
+
+/** Optional profile fields shared by create and update, validated into `row`. */
+function applyProfile(context, input, row) {
+  const referenceId = optionalText(context, input, "referenceId", 100);
+  if (referenceId !== undefined) row.referenceId = referenceId === "" ? null : referenceId;
+  if (hasOwn(input, "dob")) {
+    if (input.dob !== null && input.dob !== "" && !isDate(input.dob)) invalid(context, "dob", "Date of birth must be YYYY-MM-DD");
+    row.dob = input.dob === "" ? null : input.dob;
+  }
+  const phone = optionalText(context, input, "phone", 32);
+  if (phone !== undefined) row.phone = phone === "" ? null : phone;
+  const language = optionalText(context, input, "language", 10);
+  if (language !== undefined) row.language = language === null || language === "" ? "en" : language;
+  if (hasOwn(input, "tags")) row.tags = checkTags(context, input.tags);
+  if (hasOwn(input, "address")) row.address = checkAddress(context, input.address, row.address);
+}
+
+function applyNames(context, input, row) {
+  if (row.type === "individual") {
+    for (const key of ["firstName", "lastName"]) {
+      if (hasOwn(input, key) || row[key] === null) row[key] = requireText(context, { [key]: hasOwn(input, key) ? input[key] : row[key] }, key, 100);
+    }
+    row.name = hasOwn(input, "name") ? requireText(context, input, "name", 200) : `${row.firstName} ${row.lastName}`;
+  } else {
+    if (hasOwn(input, "name") || row.name === null) row.name = requireText(context, { name: hasOwn(input, "name") ? input.name : row.name }, "name", 200);
+    for (const key of ["firstName", "lastName"]) {
+      const value = optionalText(context, input, key, 100);
+      if (value !== undefined) row[key] = value === "" ? null : value;
+    }
+  }
+}
+
+export function recipientsCreate(input, context) {
+  requireKey(context, true);
+  rejectReservedKeys(context, input);
+  const type = requireText(context, input, "type", 20);
+  checkEnum(context, type, ["individual", "business"], "type");
+  const email = checkEmail(context, hasOwn(input, "email") ? input.email : undefined);
+  const now = nowIso(context);
+  const row = {
+    id: "", referenceId: null, email, type, firstName: null, lastName: null, name: null, status: "incomplete",
+    complianceStatus: "pending", holdStatus: "none", dob: null, phone: null, language: "en", tags: [],
+    address: { ...EMPTY_ADDRESS }, createdAt: now, updatedAt: now,
+  };
+  applyNames(context, input, row);
+  applyProfile(context, input, row);
+  if (hasOwn(input, "accounts") && (!Array.isArray(input.accounts) || input.accounts.length > 5)) invalid(context, "accounts");
+  assertUnique(context, { email, referenceId: row.referenceId }, null);
+  row.id = nextId(context, "R");
+  const accounts = [];
+  for (const [index, account] of (input.accounts ?? []).entries()) {
+    accounts.push(attachAccount(context, buildAccount(context, row, account, `accounts[${index}].`, now), accounts));
+  }
+  row.status = deriveStatus(row, primaryAccount(accounts) !== null);
+  context.state.put("recipients", row.id, row);
+  return { ok: true, recipient: recipientOut(context, row, accountsOf(context, row.id)) };
+}
+
+export function recipientsGet(input, context) {
+  requireKey(context, false);
+  const row = recipientOrFail(context, input.recipientId);
+  return { ok: true, recipient: recipientOut(context, row, accountsOf(context, row.id)) };
+}
+
+export function recipientsUpdate(input, context) {
+  requireKey(context, true);
+  rejectReservedKeys(context, input);
+  const current = recipientOrFail(context, input.recipientId);
+  const { recipientId, ...changes } = input;
+  if (Object.keys(changes).length === 0) empty(context, "body");
+  const now = nowIso(context);
+  const row = { ...current, address: { ...EMPTY_ADDRESS, ...current.address }, tags: [...(current.tags ?? [])] };
+  if (hasOwn(changes, "type") && changes.type !== current.type) invalid(context, "type", "Recipient type cannot be changed");
+  if (hasOwn(changes, "email")) row.email = checkEmail(context, changes.email);
+  applyNames(context, changes, row);
+  applyProfile(context, changes, row);
+  if (hasOwn(changes, "status")) {
+    if (current.status !== "archived") context.fail({ code: "INVALID_STATUS", message: "Only an archived recipient can be restored" });
+    if (current.holdStatus !== "none") context.fail({ code: "INVALID_STATUS", message: "Recipient is on hold and cannot be restored" });
+    row.status = "incomplete";
+  }
+  if (hasOwn(changes, "email") || hasOwn(changes, "referenceId") || hasOwn(changes, "status")) {
+    assertUnique(context, { email: row.email, referenceId: row.referenceId }, row.id);
+  }
+  const accounts = accountsOf(context, row.id);
+  row.status = deriveStatus(row, primaryAccount(accounts) !== null);
+  row.updatedAt = now;
+  context.state.put("recipients", row.id, row);
+  return { ok: true, recipient: recipientOut(context, row, accounts) };
+}
+
+export function recipientsDelete(input, context) {
+  requireKey(context, true);
+  const row = recipientOrFail(context, input.recipientId);
+  if (row.status === "archived") return { ok: true };
+  if (hasPendingOpenPayment(context, (payment) => payment.recipientId === row.id)) {
+    context.fail({ code: "INVALID_STATUS", message: "Recipient has pending payments" });
+  }
+  context.state.put("recipients", row.id, { ...row, status: "archived", updatedAt: nowIso(context) });
+  return { ok: true };
+}
+
+export { refreshRecipient };