@firedrill-tools/trolley 0.1.1

package/firedrill/tools/trolley/app/site/view-recipient.js

@@ -0,0 +1,124 @@
+// Recipient profile: header, profile details (edit), payout methods, archive/restore.
+import { app, go, setTitle } from "./app.js";
+import { errorBlock, stateBlock } from "./list.js";
+import { btn, call, confirmDialog, date, describe, el, field, human, initials, input, newKey, openModal, pill, showFieldError, toast } from "./ui.js";
+import { openAddMethod, methodIcon, methodLine } from "./view-methods.js";
+
+export async function renderRecipient(host, route, view) {
+  setTitle("Recipients");
+  host.replaceChildren(el("div", { class: "card card-body" }, el("div", { class: "skeleton" })));
+  let recipient;
+  let accounts;
+  try {
+    [recipient, accounts] = await Promise.all([
+      call("recipients.get", { recipientId: route.id }).then((v) => v.recipient),
+      call("recipient_accounts.list", { recipientId: route.id }).then((v) => v.accounts),
+    ]);
+  } catch (error) {
+    if (!view.isCurrent()) return;
+    host.replaceChildren(crumbs(route.id), el("section", { class: "card" }, error.is?.("NOT_FOUND") ? stateBlock("user", "Recipient not found", "It may have been removed or the ID is wrong.") : errorBlock(error, () => go("recipients", route.id))));
+    return;
+  }
+  if (!view.isCurrent()) return;
+  const archived = recipient.status === "archived";
+
+  const actions = archived
+    ? btn("Restore recipient", "secondary", { onClick: () => mutate("recipients.update", { recipientId: recipient.id, status: "active" }, "Recipient restored.") })
+    : btn("Archive", "secondary", { onClick: archive });
+  const head = el("div", { class: "profile-head" }, [
+    el("span", { class: `face${recipient.type === "business" ? " biz" : ""}`, text: initials(recipient.name), attrs: { "aria-hidden": "true" } }),
+    el("div", {}, [el("h2", { text: recipient.name || "(no name)" }), el("div", { class: "method-sub", text: `${human(recipient.type)} · ${recipient.email ?? ""}` })]),
+    pill(recipient.status), pill(recipient.complianceStatus),
+    el("span", { class: "spacer" }), actions,
+  ]);
+
+  const address = recipient.address ?? {};
+  const addressText = [address.street1, address.street2, address.city, address.region, address.postalCode, address.country].filter(Boolean).join(", ");
+  const details = el("section", { class: "card" }, [
+    el("div", { class: "card-head" }, [el("h2", { text: "Profile" }), el("span", { class: "spacer" }), btn("Edit", "secondary", { small: true, disabled: archived, onClick: openEdit })]),
+    el("div", { class: "card-body" }, el("dl", { class: "dl" }, [
+      ["Recipient ID", recipient.id], ["Reference ID", recipient.referenceId ?? "—"], ["Email", recipient.email ?? "—"],
+      ["Phone", recipient.phone ?? "—"], ["Date of birth", recipient.dob ?? "—"], ["Address", addressText || "Missing (profile incomplete)"],
+      ["Tags", (recipient.tags ?? []).join(", ") || "—"], ["Created", date(recipient.createdAt, true)], ["Last updated", date(recipient.updatedAt, true)],
+    ].flatMap(([k, v]) => [el("dt", { text: k }), el("dd", { text: v })]))),
+  ]);
+
+  const methodsBody = el("div", { class: "card-body" });
+  if (accounts.length === 0) methodsBody.append(stateBlock("bank", "No payout method", "Add a payout method so this recipient can be paid."));
+  for (const account of accounts) {
+    const row = el("div", { class: "method" }, [
+      el("div", { class: "method-icon" }, methodIcon(account.type)),
+      el("div", { class: "method-main" }, [el("div", { class: "method-title" }, [el("span", { text: `${human(account.type)} · ${account.currency ?? ""} ` }), account.primary ? pill("primary") : null]), el("div", { class: "method-sub", text: methodLine(account) })]),
+    ]);
+    if (!account.primary && !archived) row.append(btn("Make primary", "link", { small: true, onClick: () => mutate("recipient_accounts.update", { recipientId: recipient.id, accountId: account.id, primary: true }, "Primary payout method updated.") }));
+    if (!archived) row.append(btn("Remove", "link", { small: true, onClick: () => removeAccount(account) }));
+    methodsBody.append(row);
+  }
+  const route_ = recipient.payoutMethod ? el("div", { class: "method-sub", text: `Route: ${human(recipient.routeType ?? "")} · minimum ${recipient.routeMinimum ?? "—"} · estimated fees ${recipient.estimatedFees ?? "—"}` }) : null;
+  const methods = el("section", { class: "card" }, [
+    el("div", { class: "card-head" }, [el("h2", { text: "Payout methods" }), el("span", { class: "spacer" }), btn("Add payout method", "dark", { disabled: archived, onClick: () => openAddMethod(recipient, () => go("recipients", recipient.id)) })]),
+    methodsBody, route_ ? el("div", { class: "card-body" }, route_) : null,
+  ]);
+
+  host.replaceChildren(crumbs(recipient.name || recipient.id),
+    archived ? el("div", { class: "banner banner-warn", attrs: { role: "status" } }, el("span", { text: "This recipient is archived. Restore it to edit details or add payments." })) : "",
+    head, el("div", { class: "grid-2" }, [details, methods]));
+
+  async function mutate(operation, args, message) {
+    try {
+      await call(operation, args, newKey());
+      toast(message);
+    } catch (error) {
+      toast(describe(error), { error: true });
+    }
+    go("recipients", recipient.id);
+  }
+  async function archive() {
+    if (await confirmDialog("Archive recipient?", `${recipient.name} will be hidden from the recipient list and cannot be added to new payments.`, "Archive", { danger: true })) {
+      await mutate("recipients.delete", { recipientId: recipient.id }, "Recipient archived.");
+    }
+  }
+  async function removeAccount(account) {
+    if (await confirmDialog("Remove payout method?", `${human(account.type)} ${methodLine(account)} will be disabled.`, "Remove", { danger: true })) {
+      await mutate("recipient_accounts.delete", { recipientId: recipient.id, accountId: account.id }, "Payout method removed.");
+    }
+  }
+  function openEdit() {
+    const form = el("form", { class: "form-grid", attrs: { novalidate: true } });
+    const individual = recipient.type === "individual";
+    form.append(
+      ...(individual ? [field("First name", input("firstName", recipient.firstName)), field("Last name", input("lastName", recipient.lastName))] : [field("Business name", input("name", recipient.name), { full: true })]),
+      field("Email", input("email", recipient.email)), field("Phone", input("phone", recipient.phone)),
+      field("Reference ID", input("referenceId", recipient.referenceId)), field("Tags", input("tags", (recipient.tags ?? []).join(", ")), { hint: "Comma separated" }),
+      field("Street address", input("street1", address.street1), { full: true }), field("City", input("city", address.city)),
+      field("Region / state", input("region", address.region)), field("Postal code", input("postalCode", address.postalCode)), field("Country code", input("country", address.country, { maxlength: 2 })),
+    );
+    const formError = el("div", { class: "form-error", attrs: { role: "alert" } });
+    const save = btn("Save changes", "primary");
+    const key = newKey();
+    app.editing += 1;
+    const modal = openModal({ title: "Edit profile", body: [form, formError], wide: true, actions: [btn("Cancel", "secondary", { onClick: () => modal.close() }), save], onClose: () => { app.editing -= 1; } });
+    save.addEventListener("click", async () => {
+      const d = Object.fromEntries(new FormData(form).entries());
+      const args = { recipientId: recipient.id, email: d.email.trim(), tags: d.tags.split(",").map((t) => t.trim()).filter(Boolean) };
+      if (individual) { args.firstName = d.firstName.trim(); args.lastName = d.lastName.trim(); } else args.name = d.name.trim();
+      if (d.phone.trim()) args.phone = d.phone.trim();
+      if (d.referenceId.trim()) args.referenceId = d.referenceId.trim();
+      args.address = { street1: d.street1.trim() || null, city: d.city.trim() || null, region: d.region.trim() || null, postalCode: d.postalCode.trim() || null, country: d.country.trim().toUpperCase() || null };
+      save.disabled = true;
+      try {
+        await call("recipients.update", args, key);
+        modal.close();
+        toast("Profile saved.");
+        go("recipients", recipient.id);
+      } catch (error) {
+        if (!showFieldError(form, error)) formError.textContent = describe(error);
+        save.disabled = false;
+      }
+    });
+  }
+}
+
+function crumbs(label) {
+  return el("nav", { class: "crumbs", attrs: { "aria-label": "Breadcrumb" } }, [el("a", { text: "Recipients", attrs: { href: "#/recipients" } }), el("span", { text: "›" }), el("span", { text: label })]);
+}

package/firedrill/tools/trolley/app/site/view-recipients.js

@@ -0,0 +1,115 @@
+// Recipients list: search, status/payout-method/country filters, sortable columns, paging, Add recipient.
+import { app, go, setParams, setTitle } from "./app.js";
+import { dataTable, pager, searchBox, stateBlock, tabs } from "./list.js";
+import { btn, call, date, describe, el, field, human, initials, input, newKey, openModal, pill, select, showFieldError, toast } from "./ui.js";
+
+const STATUS_TABS = [["", "All"], ["active", "Active"], ["incomplete", "Incomplete"], ["disabled", "Disabled"], ["blocked", "Blocked"], ["archived", "Archived"]];
+const METHODS = [["", "Any payout method"], ["bank-transfer", "Bank transfer"], ["paypal", "PayPal"], ["check", "Check"], ["venmo", "Venmo"]];
+
+export function recipientCell(r) {
+  return el("div", { class: "who" }, [
+    el("span", { class: `face${r.type === "business" ? " biz" : ""}`, text: initials(r.name), attrs: { "aria-hidden": "true" } }),
+    el("div", {}, [el("div", { text: r.name || "(no name)" }), el("div", { class: "sub", text: r.email ?? "" })]),
+  ]);
+}
+
+export async function renderRecipients(host, route, view) {
+  setTitle("Recipients");
+  const state = {
+    page: Number(route.params.page) || 1, pageSize: Number(route.params.pageSize) || 10, search: route.params.search ?? "",
+    status: route.params.status ?? "", payoutMethod: route.params.payoutMethod ?? "", country: route.params.country ?? "",
+    orderBy: route.params.orderBy ?? "createdAt", sortBy: route.params.sortBy ?? "desc",
+  };
+  const table = dataTable([
+    { label: "Name", key: "name", cell: recipientCell },
+    { label: "Reference ID", key: "referenceId", cell: (r) => el("span", { class: "mono", text: r.referenceId ?? "—" }) },
+    { label: "Payout method", key: "payoutMethod", cell: (r) => (r.payoutMethod ? human(r.payoutMethod) : "—") },
+    { label: "Country", cell: (r) => (r.address?.country ? el("span", { class: "flag", text: r.address.country }) : "—") },
+    { label: "Status", cell: (r) => pill(r.status) },
+    { label: "Created", key: "createdAt", cell: (r) => date(r.createdAt) },
+  ], {
+    onRowClick: (r) => go("recipients", r.id),
+    sort: state,
+    onSort: (key) => { state.sortBy = state.orderBy === key && state.sortBy === "asc" ? "desc" : "asc"; state.orderBy = key; state.page = 1; void load(); },
+  });
+  const pagerHost = el("div");
+  const tabHost = el("div");
+  const countryInput = el("input", { class: "input", attrs: { placeholder: "Country (US, CA)", "aria-label": "Country filter", value: state.country, size: 20 } });
+  countryInput.addEventListener("change", () => { state.country = countryInput.value.trim().toUpperCase(); state.page = 1; void load(); });
+  const methodSelect = select("payoutMethod", METHODS, state.payoutMethod);
+  methodSelect.setAttribute("aria-label", "Payout method filter");
+  methodSelect.addEventListener("change", () => { state.payoutMethod = methodSelect.value; state.page = 1; void load(); });
+  const toolbar = el("div", { class: "toolbar" }, [
+    searchBox("Search name, email or reference ID", state.search, (value) => { state.search = value; state.page = 1; void load(); }),
+    methodSelect, countryInput, el("span", { class: "spacer" }),
+    btn("Add recipient", "primary", { icon: "plus", onClick: () => openCreate() }),
+  ]);
+  host.replaceChildren(el("div", {}, [tabHost, toolbar, el("section", { class: "card" }, [table.node, pagerHost])]));
+
+  function drawTabs() {
+    tabHost.replaceChildren(tabs(STATUS_TABS, state.status, (value) => { state.status = value; state.page = 1; drawTabs(); void load(); }));
+  }
+  drawTabs();
+
+  async function load() {
+    setParams("recipients", { ...state, page: state.page === 1 ? "" : state.page, pageSize: state.pageSize === 10 ? "" : state.pageSize, orderBy: state.orderBy === "createdAt" ? "" : state.orderBy, sortBy: state.sortBy === "desc" ? "" : state.sortBy });
+    table.setLoading();
+    const args = { page: state.page, pageSize: state.pageSize, orderBy: state.orderBy, sortBy: state.sortBy };
+    for (const key of ["search", "status", "payoutMethod", "country"]) if (state[key]) args[key] = state[key];
+    try {
+      const value = await call("recipients.list", args);
+      if (!view.isCurrent()) return;
+      const filtered = state.search || state.status || state.payoutMethod || state.country;
+      table.setRows(value.recipients, filtered ? stateBlock("search", "No recipients match these filters", "Try a different search or clear the filters.") : stateBlock("user", "No recipients yet", "Add a recipient to start paying them."));
+      pagerHost.replaceChildren(pager(value.meta, state.pageSize, (next) => { Object.assign(state, next); void load(); }));
+    } catch (error) {
+      if (!view.isCurrent()) return;
+      pagerHost.replaceChildren();
+      table.setError(error, () => void load());
+    }
+  }
+  await load();
+}
+
+export function openCreate() {
+  let type = "individual";
+  const form = el("form", { class: "form-grid", attrs: { novalidate: true } });
+  const typeSelect = select("type", [["individual", "Individual"], ["business", "Business"]], type);
+  const names = el("div", { class: "field-full form-grid" });
+  const drawNames = () => names.replaceChildren(...(type === "individual"
+    ? [field("First name", input("firstName", "", { autocomplete: "off" })), field("Last name", input("lastName", "", { autocomplete: "off" }))]
+    : [field("Business name", input("name", "", { autocomplete: "off" }), { full: true })]));
+  typeSelect.addEventListener("change", () => { type = typeSelect.value; drawNames(); });
+  drawNames();
+  form.append(
+    field("Recipient type", typeSelect, { full: true }), names,
+    field("Email", input("email", "", { type: "email", autocomplete: "off" })), field("Reference ID", input("referenceId"), { hint: "Your own identifier (optional)" }),
+    field("Street address", input("street1"), { full: true }), field("City", input("city")), field("Region / state", input("region")),
+    field("Postal code", input("postalCode")), field("Country code", input("country", "US", { maxlength: 2 })),
+  );
+  const formError = el("div", { class: "form-error", attrs: { role: "alert" } });
+  const submit = btn("Create recipient", "primary");
+  const key = newKey();
+  app.editing += 1;
+  const modal = openModal({ title: "Add recipient", body: [el("p", { text: "Recipients receive payouts. Address and a payout method complete their profile." }), form, formError], actions: [btn("Cancel", "secondary", { onClick: () => modal.close() }), submit], onClose: () => { app.editing -= 1; }, wide: true });
+  submit.addEventListener("click", async () => {
+    const data = Object.fromEntries(new FormData(form).entries());
+    const args = { type, email: data.email.trim() };
+    if (type === "individual") { args.firstName = data.firstName.trim(); args.lastName = data.lastName.trim(); } else args.name = data.name.trim();
+    if (data.referenceId.trim()) args.referenceId = data.referenceId.trim();
+    const address = {};
+    for (const k of ["street1", "city", "region", "postalCode", "country"]) if (data[k].trim()) address[k] = k === "country" ? data[k].trim().toUpperCase() : data[k].trim();
+    if (Object.keys(address).length) args.address = address;
+    submit.disabled = true;
+    formError.textContent = "";
+    try {
+      const value = await call("recipients.create", args, key);
+      modal.close();
+      toast(`Recipient ${value.recipient.name} was created.`);
+      go("recipients", value.recipient.id);
+    } catch (error) {
+      if (!showFieldError(form, error)) formError.textContent = describe(error);
+      submit.disabled = false;
+    }
+  });
+}

package/firedrill/tools/trolley/behavior.mjs

@@ -0,0 +1,78 @@
+// Synthetic Trolley merchant account (sandbox) for Firedrill. Every operation computes from `context.state`: ids come
+// from the `meta/counters` row, timestamps from virtual time, FX and fees from the synthetic `meta/fx` and `meta/fees`
+// rows. Nothing here contacts Trolley, a bank, PayPal, Venmo or a check printer; no money moves.
+import { route } from "./lib/wire.mjs";
+import { accountsCreate, accountsGet, accountsList } from "./ops/accounts.mjs";
+import { accountsDelete, accountsUpdate } from "./ops/accounts-write.mjs";
+import { balancesList } from "./ops/balances.mjs";
+import { batchesCreate, batchesDelete, batchesGet, batchesList, batchesSummary, batchesUpdate } from "./ops/batches.mjs";
+import { paymentsCreate, paymentsDelete, paymentsGet, paymentsList, paymentsUpdate } from "./ops/payments.mjs";
+import { batchesGenerateQuote, batchesStartProcessing } from "./ops/processing.mjs";
+import { recipientsCreate, recipientsDelete, recipientsGet, recipientsUpdate } from "./ops/recipients.mjs";
+import { recipientsList } from "./ops/recipients-list.mjs";
+
+const operations = {
+  "recipients.create": recipientsCreate,
+  "recipients.get": recipientsGet,
+  "recipients.update": recipientsUpdate,
+  "recipients.delete": recipientsDelete,
+  "recipients.list": recipientsList,
+  "recipient_accounts.create": accountsCreate,
+  "recipient_accounts.list": accountsList,
+  "recipient_accounts.get": accountsGet,
+  "recipient_accounts.update": accountsUpdate,
+  "recipient_accounts.delete": accountsDelete,
+  "batches.create": batchesCreate,
+  "batches.get": batchesGet,
+  "batches.update": batchesUpdate,
+  "batches.delete": batchesDelete,
+  "batches.list": batchesList,
+  "batches.generate_quote": batchesGenerateQuote,
+  "batches.start_processing": batchesStartProcessing,
+  "batches.summary": batchesSummary,
+  "payments.create": paymentsCreate,
+  "payments.list": paymentsList,
+  "payments.get": paymentsGet,
+  "payments.update": paymentsUpdate,
+  "payments.delete": paymentsDelete,
+  "balances.list": balancesList,
+};
+
+const PAGE = { page: "integer", pageSize: "integer" };
+const RECIPIENT_QUERY = {
+  ...PAGE, search: "string", name: "string", email: "string", referenceId: "string", status: "string", complianceStatus: "string",
+  country: "string", payoutMethod: "string", currency: "string", tags: "string", orderBy: "string", sortBy: "string",
+};
+const BATCH_QUERY = { ...PAGE, search: "string", status: "string", currency: "string", tags: "string", orderBy: "string", sortBy: "string" };
+const PAYMENT_QUERY = { ...PAGE, status: "string", search: "string" };
+
+const http = {
+  "create-recipient": route({ body: "json" }),
+  "get-recipient": route(),
+  "update-recipient": route({ body: "json" }),
+  "delete-recipient": route(),
+  "list-recipients": route({ query: RECIPIENT_QUERY }),
+  "create-recipient-account": route({ body: "json" }),
+  "list-recipient-accounts": route(),
+  "get-recipient-account": route(),
+  "update-recipient-account": route({ body: "json" }),
+  "delete-recipient-account": route(),
+  "create-batch": route({ body: "json" }),
+  "get-batch": route(),
+  "update-batch": route({ body: "json" }),
+  "delete-batch": route(),
+  "list-batches": route({ query: BATCH_QUERY }),
+  "generate-batch-quote": route({ body: "empty" }),
+  "start-batch-processing": route({ body: "empty" }),
+  "get-batch-summary": route(),
+  "create-payment": route({ body: "json" }),
+  "list-batch-payments": route({ query: PAYMENT_QUERY }),
+  "get-batch-payment": route(),
+  "get-payment": route(),
+  "update-payment": route({ body: "json" }),
+  "delete-payment": route(),
+  "list-balances": route(),
+  "list-balances-by-kind": route(),
+};
+
+export default { operations, http };

package/firedrill/tools/trolley/lib/access.mjs

@@ -0,0 +1,21 @@
+// API-key checks from actor attributes. A Trolley key belongs to one merchant and is account-wide; what varies is
+// the merchant it belongs to and whether it may write. Fresh actors (no attributes) are the seeded merchant, full access.
+export const DEFAULT_MERCHANT_ID = "M-4Lk9Qx2Rb7Tn3Vw8Yz1Ca6";
+
+export function merchant(context) {
+  const row = context.state.get("meta", "merchant");
+  return row === null ? { id: DEFAULT_MERCHANT_ID, name: "Merchant", country: "US", defaultCurrency: "USD", sandbox: true } : row;
+}
+
+/** Key check for every operation: merchant mismatch or an unknown access level → INVALID_API_KEY; writes need full access. */
+export function requireKey(context, write) {
+  const attributes = context.actor.attributes ?? {};
+  const claimed = Object.hasOwn(attributes, "merchantId") ? attributes.merchantId : undefined;
+  const level = Object.hasOwn(attributes, "accessLevel") ? attributes.accessLevel : "full";
+  if ((claimed !== undefined && claimed !== merchant(context).id) || (level !== "full" && level !== "read_only")) {
+    context.fail({ code: "INVALID_API_KEY", message: "API key is invalid" });
+  }
+  if (write && level === "read_only") {
+    context.fail({ code: "NOT_AUTHORIZED", message: "Authentication not permitted to access resource" });
+  }
+}

package/firedrill/tools/trolley/lib/ids.mjs

@@ -0,0 +1,28 @@
+// Trolley-format ids: `<prefix>-<22 base-62 characters>`. The characters are the zero-padded base-62 rendering of
+// one shared counter (`meta/counters.next`), alphabet `0-9A-Za-z`, so lexical order equals creation order.
+const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const WIDTH = 22;
+const ID_PATTERN = /^[RABPM]-[0-9A-Za-z]{22}$/;
+
+export function renderId(prefix, sequence) {
+  let n = sequence;
+  let out = "";
+  while (n > 0) {
+    out = ALPHABET[n % 62] + out;
+    n = Math.floor(n / 62);
+  }
+  return `${prefix}-${out.padStart(WIDTH, "0")}`;
+}
+
+/** True when `value` has the exact id shape for `prefix`. Never throws. */
+export function isId(prefix, value) {
+  return typeof value === "string" && value.length === WIDTH + 2 && value[0] === prefix && ID_PATTERN.test(value);
+}
+
+/** Next id for `prefix`, advancing the shared counter row. */
+export function nextId(context, prefix) {
+  const row = context.state.get("meta", "counters");
+  const next = row !== null && Number.isSafeInteger(row.next) && row.next >= 1 ? row.next : 1000;
+  context.state.put("meta", "counters", { next: next + 1 });
+  return renderId(prefix, next);
+}

package/firedrill/tools/trolley/lib/money.mjs

@@ -0,0 +1,55 @@
+// Decimal-string money in integer minor units (BigInt), two decimals for every supported currency.
+// FX rates are 6-decimal strings held as integer micro-units. No floating point anywhere.
+const AMOUNT = /^(0|[1-9][0-9]{0,9})(\.[0-9]{2})?$/;
+const RATE = /^(0|[1-9][0-9]{0,5})\.[0-9]{6}$/;
+
+export function isAmount(value) {
+  return typeof value === "string" && AMOUNT.test(value);
+}
+
+/** "150" or "150.00" → 15000n. Caller checks `isAmount` first. */
+export function toCents(value) {
+  const [whole, fraction = "00"] = value.split(".");
+  return BigInt(whole) * 100n + BigInt(fraction);
+}
+
+export function fromCents(cents) {
+  const negative = cents < 0n;
+  const abs = negative ? -cents : cents;
+  const whole = abs / 100n;
+  const fraction = (abs % 100n).toString().padStart(2, "0");
+  return `${negative ? "-" : ""}${whole}.${fraction}`;
+}
+
+/** Canonical two-decimal rendering of a valid amount string. */
+export function normalizeAmount(value) {
+  return fromCents(toCents(value));
+}
+
+export function isRate(value) {
+  return typeof value === "string" && RATE.test(value);
+}
+
+export function toMicros(rate) {
+  const [whole, fraction] = rate.split(".");
+  return BigInt(whole) * 1000000n + BigInt(fraction);
+}
+
+export function fromMicros(micros) {
+  return `${micros / 1000000n}.${(micros % 1000000n).toString().padStart(6, "0")}`;
+}
+
+/** Integer division rounding half up (non-negative operands). */
+export function divRound(numerator, denominator) {
+  return (numerator * 2n + denominator) / (denominator * 2n);
+}
+
+/** amount (cents) × rate (micros) → cents, half up. */
+export function convert(cents, rateMicros) {
+  return divRound(cents * rateMicros, 1000000n);
+}
+
+/** Inverse conversion: target cents ÷ rate → source cents, half up. */
+export function convertBack(cents, rateMicros) {
+  return rateMicros === 0n ? 0n : divRound(cents * 1000000n, rateMicros);
+}

package/firedrill/tools/trolley/lib/paging.mjs

@@ -0,0 +1,65 @@
+// Trolley page-number paging: `page` (≥ 1), `pageSize` (1–1000, default 10), `meta { page, pages, records }`.
+import { jsonBytes } from "./store.mjs";
+import { checkEnum, checkText, hasOwn, invalid } from "./validate.mjs";
+
+const BYTE_BUDGET = 900000;
+
+export function pageArgs(context, input) {
+  const page = hasOwn(input, "page") ? input.page : 1;
+  const pageSize = hasOwn(input, "pageSize") ? input.pageSize : 10;
+  if (!Number.isSafeInteger(page) || page < 1 || page > 1000000) invalid(context, "page", "Value must be a positive integer");
+  if (!Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 1000) invalid(context, "pageSize", "Value must be between 1 and 1000");
+  return { page, pageSize };
+}
+
+/** Optional filter string: checked for invalid characters and length. */
+export function filterText(context, input, key, max = 200) {
+  if (!hasOwn(input, key)) return undefined;
+  return checkText(context, input[key], key, max);
+}
+
+/** Comma list filter (`country=CA,GB`), trimmed, empty entries dropped. */
+export function filterList(context, input, key) {
+  const text = filterText(context, input, key, 1000);
+  if (text === undefined) return undefined;
+  const values = text.split(",").map((part) => part.trim()).filter((part) => part !== "");
+  if (values.length === 0) invalid(context, key);
+  return values;
+}
+
+export function sortArgs(context, input, allowed, fallback) {
+  const orderBy = hasOwn(input, "orderBy") ? checkEnum(context, input.orderBy, allowed, "orderBy") : fallback;
+  const sortBy = hasOwn(input, "sortBy") ? checkEnum(context, input.sortBy, ["asc", "desc"], "sortBy") : "desc";
+  return { orderBy, sortBy };
+}
+
+function compareValues(a, b) {
+  if (a === b) return 0;
+  if (a === null || a === undefined) return 1;
+  if (b === null || b === undefined) return -1;
+  if (typeof a === "bigint" || typeof a === "number") return a < b ? -1 : 1;
+  const x = String(a).toLowerCase();
+  const y = String(b).toLowerCase();
+  if (x === y) return String(a) < String(b) ? -1 : 1;
+  return x < y ? -1 : 1;
+}
+
+/** Sorts in place by `key(item)`; nulls last in both directions; ties broken by id ascending. */
+export function sortItems(items, key, direction) {
+  return items.sort((left, right) => {
+    const primary = compareValues(key(left), key(right));
+    if (primary !== 0) return direction === "asc" ? primary : -primary;
+    return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+  });
+}
+
+/** One page of `items` as `{ [listKey]: mapped, meta }`, refusing bodies over the byte budget. */
+export function pageOf(context, items, { page, pageSize }, listKey, map = (item) => item) {
+  const records = items.length;
+  const pages = Math.max(1, Math.ceil(records / pageSize));
+  const start = (page - 1) * pageSize;
+  const slice = start >= records ? [] : items.slice(start, start + pageSize).map(map);
+  const body = { ok: true, [listKey]: slice, meta: { page, pages, records } };
+  if (jsonBytes(body) > BYTE_BUDGET) invalid(context, "pageSize", "Response too large, reduce pageSize");
+  return body;
+}

package/firedrill/tools/trolley/lib/pricing.mjs

@@ -0,0 +1,88 @@
+// Synthetic FX, fee and route-minimum schedule from `meta/fx` and `meta/fees`. Not Trolley's pricing or live rates.
+import { convert, convertBack, fromCents, fromMicros, isAmount, isRate, toCents, toMicros } from "./money.mjs";
+import { invalid } from "./validate.mjs";
+
+const EURO_ROUTE = ["DE", "FR", "ES", "NL", "IE", "IT", "PT", "BE", "AT", "FI"];
+
+function fxRow(context) {
+  const row = context.state.get("meta", "fx");
+  return row !== null && row.rates !== null && typeof row.rates === "object" ? row : { base: "USD", rates: { USD: "1.000000" } };
+}
+
+function baseRate(context, currency, field) {
+  const rates = fxRow(context).rates;
+  const value = Object.hasOwn(rates, currency) ? rates[currency] : undefined;
+  if (!isRate(value) || toMicros(value) === 0n) invalid(context, field, "Currency is not supported for conversion");
+  return toMicros(value);
+}
+
+/** Cross rate source → target in micro-units, half up to 6 decimals. */
+export function crossRate(context, source, target, field = "currency") {
+  if (source === target) return 1000000n;
+  const from = baseRate(context, source, field);
+  const to = baseRate(context, target, field);
+  return (to * 1000000n * 2n + from) / (from * 2n);
+}
+
+function feesRow(context) {
+  const row = context.state.get("meta", "fees");
+  return row !== null && typeof row === "object" ? row : { currency: "USD", fixed: {}, minimums: {} };
+}
+
+function scheduleCents(context, table, method, currency) {
+  const row = feesRow(context);
+  const entries = row[table] !== null && typeof row[table] === "object" ? row[table] : {};
+  const value = Object.hasOwn(entries, method) ? entries[method] : "0.00";
+  const cents = isAmount(value) ? toCents(value) : 0n;
+  const scheduleCurrency = typeof row.currency === "string" ? row.currency : "USD";
+  return convert(cents, crossRate(context, scheduleCurrency, currency));
+}
+
+export const feeCents = (context, method, currency) => scheduleCents(context, "fixed", method, currency);
+export const minimumCents = (context, method, currency) => scheduleCents(context, "minimums", method, currency);
+
+export function routeType(account) {
+  if (account === null || account === undefined) return null;
+  if (account.type !== "bank-transfer") return account.type;
+  if (account.country === "US") return "ach";
+  if (account.country === "CA") return "eft";
+  if (account.country === "GB") return "bacs";
+  if (EURO_ROUTE.includes(account.country)) return "sepa";
+  return "wire";
+}
+
+/**
+ * Recomputes a payment row's amounts for `account` from the side the caller fixed (`amountSide`).
+ * PayPal pays in the source currency (never converted). Fees are charged in the source currency;
+ * `coverFees` moves them from the recipient to the merchant.
+ */
+export function pricePayment(context, row, account) {
+  const method = account.type;
+  const sourceCurrency = row.sourceCurrency;
+  const targetCurrency = method === "paypal" ? sourceCurrency : account.currency;
+  const rate = crossRate(context, sourceCurrency, targetCurrency);
+  const fee = feeCents(context, method, sourceCurrency);
+  const recipientFee = row.coverFees ? 0n : fee;
+  let source;
+  let target;
+  if (row.amountSide === "target" && targetCurrency !== sourceCurrency) {
+    target = toCents(row.targetAmount);
+    source = convertBack(target, rate) + recipientFee;
+  } else {
+    source = toCents(row.sourceAmount);
+    const net = source > recipientFee ? source - recipientFee : 0n;
+    target = convert(net, rate);
+  }
+  return {
+    ...row,
+    accountId: account.id,
+    payoutMethod: method,
+    sourceAmount: fromCents(source),
+    targetAmount: fromCents(target),
+    targetCurrency,
+    exchangeRate: fromMicros(rate),
+    fees: fromCents(fee),
+    recipientFees: fromCents(recipientFee),
+    merchantFees: fromCents(row.coverFees ? fee : 0n),
+  };
+}