@firedrill-tools/trolley 0.1.1

package/firedrill/tools/trolley/app/site/ui.js

@@ -0,0 +1,181 @@
+// DOM helpers, operation calls, toasts, modals and formatting. All record text goes through textContent.
+import { getContext, invoke } from "/_firedrill/client.js";
+import { icon } from "./icons.js";
+
+export const $ = (selector, root = document) => root.querySelector(selector);
+
+export function el(tag, options = {}, children = []) {
+  const node = document.createElement(tag);
+  if (options.class) node.className = options.class;
+  if (options.text !== undefined && options.text !== null) node.textContent = String(options.text);
+  if (options.title) node.title = options.title;
+  if (options.attrs) for (const [name, value] of Object.entries(options.attrs)) if (value !== undefined && value !== null && value !== false) node.setAttribute(name, value === true ? "" : String(value));
+  if (options.on) for (const [event, handler] of Object.entries(options.on)) node.addEventListener(event, handler);
+  for (const child of Array.isArray(children) ? children : [children]) if (child !== undefined && child !== null && child !== false) node.append(child);
+  return node;
+}
+
+export function btn(label, kind = "secondary", options = {}) {
+  const children = [];
+  if (options.icon) children.push(icon(options.icon));
+  if (label) children.push(el("span", { text: label }));
+  return el("button", { class: `btn btn-${kind}${options.small ? " btn-sm" : ""}`, title: options.title, attrs: { type: "button", disabled: options.disabled, "aria-label": options.label }, on: options.onClick ? { click: options.onClick } : {} }, children);
+}
+
+export class ToolError extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details ?? {};
+  }
+  is(code) {
+    return this.code === code || this.code === `tool.${code}` || String(this.code).endsWith(`.${code}`);
+  }
+  get field() {
+    return typeof this.details.field === "string" ? this.details.field : undefined;
+  }
+  get denied() {
+    return this.status === "denied" || this.is("NOT_AUTHORIZED");
+  }
+}
+
+let pending = 0;
+export async function call(operationId, args = {}, idempotencyKey) {
+  pending += 1;
+  try {
+    const result = await invoke(operationId, args, idempotencyKey ? { idempotencyKey } : {});
+    const outcome = result.outcome;
+    if (outcome.status !== "ok") {
+      const error = outcome.error ?? {};
+      throw new ToolError(outcome.status, error.code ?? outcome.status, error.message ?? `The request was ${outcome.status}.`, error.details);
+    }
+    return outcome.value;
+  } finally {
+    pending -= 1;
+  }
+}
+export const newKey = () => crypto.randomUUID();
+
+export function describe(error) {
+  if (!(error instanceof ToolError)) return error?.message ?? "Something went wrong.";
+  if (error.status === "denied") return "Your API key is not permitted to do this (not_authorized).";
+  if (error.is("NOT_AUTHORIZED")) return "This key has read-only access. Ask an administrator for full access.";
+  if (error.is("INVALID_API_KEY")) return "API key is invalid for this merchant.";
+  if (error.is("RATE_LIMIT_EXCEEDED")) return "Too many requests. Wait a moment, then try again.";
+  if (error.is("INTERNAL_SERVER_ERROR")) return `${error.message} The result may be unknown: refresh before retrying.`;
+  return error.field ? `${error.message} (${error.field})` : error.message;
+}
+
+export function toast(message, { error = false, timeout = 5000, actionLabel, onAction } = {}) {
+  const host = $("#toasts");
+  const node = el("div", { class: `toast${error ? " toast-error" : ""}`, attrs: { role: error ? "alert" : "status" } }, [
+    el("span", { class: "toast-icon" }, icon(error ? "info" : "check")),
+    el("span", { class: "toast-text", text: message }),
+  ]);
+  if (actionLabel) node.append(btn(actionLabel, "link", { onClick: () => { node.remove(); onAction?.(); } }));
+  node.append(el("button", { class: "toast-close", attrs: { type: "button", "aria-label": "Dismiss" }, on: { click: () => node.remove() } }, icon("close")));
+  host.append(node);
+  if (timeout) setTimeout(() => node.remove(), timeout);
+}
+
+export function openModal({ title, body, actions = [], wide = false, onClose }) {
+  const previous = document.activeElement;
+  const titleId = `m-${Math.random().toString(36).slice(2)}`;
+  const close = () => { overlay.remove(); document.removeEventListener("keydown", onKey); previous?.focus?.(); onClose?.(); };
+  const onKey = (event) => { if (event.key === "Escape") close(); };
+  const dialog = el("div", { class: `modal${wide ? " modal-wide" : ""}`, attrs: { role: "dialog", "aria-modal": "true", "aria-labelledby": titleId } }, [
+    el("div", { class: "modal-head" }, [el("h2", { text: title, attrs: { id: titleId } }), el("button", { class: "icon-btn", attrs: { type: "button", "aria-label": "Close" }, on: { click: close } }, icon("close"))]),
+    el("div", { class: "modal-body" }, body),
+    actions.length ? el("div", { class: "modal-foot" }, actions) : null,
+  ]);
+  const overlay = el("div", { class: "overlay", on: { mousedown: (event) => { if (event.target === overlay) close(); } } }, dialog);
+  document.body.append(overlay);
+  document.addEventListener("keydown", onKey);
+  queueMicrotask(() => (dialog.querySelector("input, select, textarea, .btn-primary") ?? dialog).focus?.());
+  return { close, dialog };
+}
+
+export function confirmDialog(title, message, okLabel = "Confirm", { danger = false } = {}) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (value) => { if (!done) { done = true; resolve(value); } };
+    const cancel = btn("Cancel", "secondary", { onClick: () => { modal.close(); } });
+    const ok = btn(okLabel, danger ? "danger" : "primary", { onClick: () => { finish(true); modal.close(); } });
+    const modal = openModal({ title, body: typeof message === "string" ? el("p", { text: message }) : message, actions: [cancel, ok], onClose: () => finish(false) });
+  });
+}
+
+let fieldSeq = 0;
+export function field(label, control, { hint, full = false } = {}) {
+  fieldSeq += 1;
+  const id = `fld-${fieldSeq}`;
+  control.id = id;
+  return el("div", { class: `field${full ? " field-full" : ""}`, attrs: { "data-field": control.name || undefined } }, [
+    el("label", { text: label, attrs: { for: id } }),
+    control,
+    hint ? el("div", { class: "field-hint", text: hint }) : null,
+    el("div", { class: "field-error", attrs: { "aria-live": "polite" } }),
+  ]);
+}
+export function input(name, value = "", attrs = {}) {
+  return el("input", { class: "input", attrs: { name, value: value ?? "", type: "text", ...attrs } });
+}
+export function select(name, options, value) {
+  const node = el("select", { class: "input", attrs: { name } }, options.map(([v, label]) => el("option", { text: label, attrs: { value: v, selected: v === value } })));
+  return node;
+}
+export function showFieldError(form, error) {
+  for (const slot of form.querySelectorAll(".field-error")) slot.textContent = "";
+  const name = error instanceof ToolError ? error.field : undefined;
+  const leaf = name?.split(/[.[\]]/).filter(Boolean).pop();
+  const target = name && (form.querySelector(`[data-field="${CSS.escape(name)}"] .field-error`) ?? (leaf && form.querySelector(`[data-field="${CSS.escape(leaf)}"] .field-error`)));
+  if (target) target.textContent = error.message;
+  return Boolean(target);
+}
+
+const SYMBOL = { USD: "$", CAD: "CA$", EUR: "€", GBP: "£", AUD: "A$", MXN: "MX$" };
+export function money(amount, currency = "USD") {
+  if (amount === "" || amount === null || amount === undefined) return "—";
+  const [whole, frac = "00"] = String(amount).replace("-", "").split(".");
+  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  const sign = String(amount).startsWith("-") ? "-" : "";
+  return `${sign}${Object.hasOwn(SYMBOL, currency) ? SYMBOL[currency] : ""}${grouped}.${frac.padEnd(2, "0").slice(0, 2)}`;
+}
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export function date(iso, withTime = false) {
+  if (!iso) return "—";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "—";
+  const base = `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
+  return withTime ? `${base} ${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")} UTC` : base;
+}
+const LABELS = { paypal: "PayPal", ach: "ACH", sepa: "SEPA", "bank-transfer": "Bank transfer", paymentrails: "Trolley" };
+export const human = (value) => (Object.hasOwn(LABELS, String(value)) ? LABELS[value] : String(value ?? "").replace(/[-_]/g, " ").replace(/^\w/, (c) => c.toUpperCase()));
+
+const TONES = { active: "green", processed: "green", complete: "green", verified: "green", primary: "blue", open: "blue", pending: "amber", processing: "amber", incomplete: "amber", review: "amber", failed: "red", blocked: "red", suspended: "red", disabled: "grey", archived: "grey" };
+export function pill(status) {
+  const tone = Object.hasOwn(TONES, status) ? TONES[status] : "grey";
+  return el("span", { class: `pill pill-${tone}`, text: human(status) });
+}
+export function initials(name) {
+  return String(name ?? "?").split(/\s+/).filter(Boolean).slice(0, 2).map((part) => part[0].toUpperCase()).join("") || "?";
+}
+
+export function watchWorld(refresh, mayRefresh) {
+  let revision;
+  const check = async () => {
+    if (pending > 0 || document.visibilityState !== "visible") return;
+    try {
+      const context = await getContext();
+      const stamp = JSON.stringify(context.revision);
+      if (revision !== undefined && stamp !== revision && mayRefresh()) { revision = stamp; await refresh(); }
+      revision = stamp;
+    } catch (error) {
+      toast(error?.message ?? "The local environment is unavailable.", { error: true });
+    }
+  };
+  setInterval(() => void check(), 2000);
+  void check();
+}
+export { getContext };

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

@@ -0,0 +1,30 @@
+// Balances: funding balances by kind (Trolley and PayPal).
+import { go, setTitle } from "./app.js";
+import { dataTable, stateBlock, tabs } from "./list.js";
+import { el, human, money } from "./ui.js";
+import { call } from "./ui.js";
+
+export async function renderBalances(host, route, view) {
+  setTitle("Balances");
+  const kind = route.params.kind ?? "";
+  const table = dataTable([
+    { label: "Account", cell: (b) => el("div", {}, [el("div", { text: b.type === "paymentrails" ? "Trolley balance" : "PayPal balance" }), el("div", { class: "sub mono", text: b.accountNumber })]) },
+    { label: "Currency", cell: (b) => b.currency },
+    { label: "Primary", cell: (b) => (b.primary ? "Yes" : "—") },
+    { label: "Pending", num: true, cell: (b) => money(b.pendingAmount, b.currency) },
+    { label: "Available", num: true, cell: (b) => el("strong", { text: money(b.amount, b.currency) }) },
+  ]);
+  host.replaceChildren(el("div", {}, [
+    tabs([["", "All balances"], ["paymentrails", "Trolley"], ["paypal", "PayPal"]], kind, (value) => go("balances", undefined, { kind: value })),
+    el("div", { class: "banner banner-info" }, el("span", { text: "Deposits and funding transfers are not simulated. Processing a batch debits the Trolley balance in the batch currency." })),
+    el("section", { class: "card" }, table.node),
+  ]));
+  try {
+    const value = await call("balances.list", kind ? { kind } : {});
+    if (!view.isCurrent()) return;
+    table.setRows(value.balances, stateBlock("coins", "No balances", `There are no ${kind ? human(kind) : ""} balances for this merchant.`));
+  } catch (error) {
+    if (!view.isCurrent()) return;
+    table.setError(error, () => go("balances", undefined, { kind }));
+  }
+}

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

@@ -0,0 +1,86 @@
+// Batch detail: summary strip, quote expiry (virtual time), payments table with search and paging, batch actions.
+import { app, go, setTitle } from "./app.js";
+import { deleteBatch, generateQuote, openPaymentForm, processBatch, removePayment, reviewSummary } from "./batch-actions.js";
+import { dataTable, errorBlock, pager, searchBox, stateBlock } from "./list.js";
+import { btn, call, date, el, human, initials, money, pill } from "./ui.js";
+
+function quoteText(batch) {
+  if (!batch.quoteExpiredAt) return "No quote";
+  const ms = Date.parse(batch.quoteExpiredAt) - Date.parse(app.now ?? "");
+  if (Number.isNaN(ms)) return `Expires ${date(batch.quoteExpiredAt, true)}`;
+  if (ms <= 0) return "Quote expired";
+  const minutes = Math.floor(ms / 60000);
+  return minutes >= 60 ? `Expires in ${Math.floor(minutes / 60)}h ${minutes % 60}m` : `Expires in ${minutes}m`;
+}
+
+export async function renderBatch(host, route, view) {
+  setTitle("Payments");
+  host.replaceChildren(el("div", { class: "card card-body" }, el("div", { class: "skeleton" })));
+  let batch;
+  try {
+    batch = (await call("batches.get", { batchId: route.id })).batch;
+  } catch (error) {
+    if (!view.isCurrent()) return;
+    host.replaceChildren(crumbs(route.id), el("section", { class: "card" }, error.is?.("NOT_FOUND") ? stateBlock("money", "Batch not found", "It may have been deleted.") : errorBlock(error, () => go("payments", route.id))));
+    return;
+  }
+  if (!view.isCurrent()) return;
+  const open = batch.status === "open";
+  const reload = () => go("payments", batch.id);
+  const state = { page: 1, pageSize: 10, search: "" };
+
+  const strip = el("section", { class: "card summary-strip" }, [
+    ["Status", pill(batch.status)], ["Total amount", money(batch.amount, batch.currency)], ["Payments", String(batch.totalPayments)], ["Quote", quoteText(batch)],
+  ].map(([label, value]) => el("div", {}, [el("div", { class: "label", text: label }), el("div", { class: "value" }, value)])));
+
+  const actions = el("div", { class: "toolbar" }, [
+    searchBox("Search recipient, email or memo", "", (value) => { state.search = value; state.page = 1; void load(); }),
+    el("span", { class: "spacer" }),
+    open ? btn("Add payment", "secondary", { icon: "plus", onClick: () => openPaymentForm(batch, undefined, reload) }) : null,
+    open ? btn("Generate quote", "secondary", { onClick: () => generateQuote(batch, reload) }) : null,
+    btn("Review", "secondary", { onClick: () => reviewSummary(batch) }),
+    open ? btn("Process batch", "primary", { disabled: batch.totalPayments === 0, onClick: () => processBatch(batch, reload) }) : null,
+    open ? btn("", "secondary", { icon: "close", label: "Delete batch", title: "Delete batch", onClick: () => deleteBatch(batch) }) : null,
+  ]);
+
+  const table = dataTable([
+    { label: "Recipient", cell: (p) => el("div", { class: "who" }, [el("span", { class: "face", text: initials(p.recipient?.name), attrs: { "aria-hidden": "true" } }), el("div", {}, [el("a", { text: p.recipient?.name || p.recipient?.id, attrs: { href: `#/recipients/${encodeURIComponent(p.recipient?.id ?? "")}` } }), el("div", { class: "sub", text: p.recipient?.email ?? "" })])]) },
+    { label: "Amount", num: true, cell: (p) => money(p.sourceAmount, p.sourceCurrency) },
+    { label: "Recipient gets", num: true, cell: (p) => el("div", {}, [el("div", { text: p.targetAmount ? `${money(p.targetAmount, p.targetCurrency)} ${p.targetCurrency}` : "Quote required" }), p.sourceCurrency !== p.targetCurrency ? el("div", { class: "sub", text: `rate ${p.exchangeRate}` }) : null]) },
+    { label: "Fees", num: true, cell: (p) => money(p.fees, p.sourceCurrency) },
+    { label: "Method", cell: (p) => (p.payoutMethod ? human(p.payoutMethod) : "—") },
+    { label: "Status", cell: (p) => el("div", {}, [pill(p.status), p.failureMessage ? el("div", { class: "sub", text: p.failureMessage }) : null]) },
+    { label: "", cell: (p) => (open && p.status === "pending" ? el("div", { class: "row-actions" }, [
+      btn("Edit", "link", { small: true, onClick: () => openPaymentForm(batch, p, reload) }),
+      btn("Remove", "link", { small: true, onClick: () => removePayment(batch, p, reload) }),
+    ]) : "") },
+  ]);
+  const pagerHost = el("div");
+  const meta = el("div", { class: "method-sub", text: `${batch.id} · ${batch.currency} · created ${date(batch.createdAt, true)}${batch.sentAt ? ` · sent ${date(batch.sentAt, true)}` : ""}${batch.completedAt ? ` · completed ${date(batch.completedAt, true)}` : ""}` });
+  const heading = el("div", { class: "profile-head" }, [el("div", {}, [el("h2", { text: batch.description || "Untitled batch" }), meta])]);
+  const banner = batch.status === "failed" ? el("div", { class: "banner banner-error", attrs: { role: "status" } }, el("span", { text: "This batch failed to process. Payment rows show each failure message." }))
+    : !open ? el("div", { class: "banner banner-info" }, el("span", { text: "This batch has been sent. Payments can no longer be edited." })) : "";
+
+  host.replaceChildren(crumbs(batch.description || batch.id), heading, banner, strip, el("div", { class: "spacer-16" }), actions, el("section", { class: "card" }, [table.node, pagerHost]));
+
+  async function load() {
+    table.setLoading();
+    const args = { batchId: batch.id, page: state.page, pageSize: state.pageSize };
+    if (state.search) args.search = state.search;
+    try {
+      const value = await call("payments.list", args);
+      if (!view.isCurrent()) return;
+      table.setRows(value.payments, state.search ? stateBlock("search", "No payments match", "Try a different search.") : stateBlock("money", "No payments in this batch", open ? "Add a payment to get started." : ""));
+      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();
+}
+
+function crumbs(label) {
+  return el("nav", { class: "crumbs", attrs: { "aria-label": "Breadcrumb" } }, [el("a", { text: "Payments", attrs: { href: "#/payments" } }), el("span", { text: "›" }), el("span", { text: label })]);
+}

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

@@ -0,0 +1,78 @@
+// Payments: batch list with status tabs, search, sorting, paging and Create batch.
+import { app, go, setParams, setTitle } from "./app.js";
+import { dataTable, pager, searchBox, stateBlock, tabs } from "./list.js";
+import { btn, call, date, describe, el, field, input, money, newKey, openModal, pill, select, showFieldError, toast } from "./ui.js";
+
+const STATUS_TABS = [["", "All"], ["open", "Open"], ["processing", "Processing"], ["complete", "Complete"], ["failed", "Failed"]];
+
+export async function renderBatches(host, route, view) {
+  setTitle("Payments");
+  const state = { page: Number(route.params.page) || 1, pageSize: Number(route.params.pageSize) || 10, status: route.params.status ?? "", search: route.params.search ?? "", orderBy: route.params.orderBy ?? "createdAt", sortBy: route.params.sortBy ?? "desc" };
+  const table = dataTable([
+    { label: "Batch", cell: (b) => el("div", {}, [el("div", { text: b.description || "Untitled batch" }), el("div", { class: "sub mono", text: b.id })]) },
+    { label: "Payments", num: true, cell: (b) => String(b.totalPayments) },
+    { label: "Amount", key: "amount", num: true, cell: (b) => money(b.amount, b.currency) },
+    { label: "Currency", cell: (b) => b.currency },
+    { label: "Status", cell: (b) => pill(b.status) },
+    { label: "Created", key: "createdAt", cell: (b) => date(b.createdAt) },
+    { label: "Sent", key: "sentAt", cell: (b) => date(b.sentAt) },
+  ], { onRowClick: (b) => go("payments", b.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");
+  host.replaceChildren(el("div", {}, [
+    tabHost,
+    el("div", { class: "toolbar" }, [searchBox("Search batches", state.search, (value) => { state.search = value; state.page = 1; void load(); }), el("span", { class: "spacer" }), btn("Create batch", "primary", { icon: "plus", onClick: openCreateBatch })]),
+    el("section", { class: "card" }, [table.node, pagerHost]),
+  ]));
+  const drawTabs = () => tabHost.replaceChildren(tabs(STATUS_TABS, state.status, (value) => { state.status = value; state.page = 1; drawTabs(); void load(); }));
+  drawTabs();
+
+  async function load() {
+    setParams("payments", { status: state.status, search: state.search, 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 };
+    if (state.status) args.status = state.status;
+    if (state.search) args.search = state.search;
+    try {
+      const value = await call("batches.list", args);
+      if (!view.isCurrent()) return;
+      table.setRows(value.batches, state.search || state.status ? stateBlock("search", "No batches match", "Try another tab or search.") : stateBlock("money", "No payment batches yet", "Create a batch to pay recipients."));
+      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();
+}
+
+function openCreateBatch() {
+  const form = el("form", { class: "form-grid", attrs: { novalidate: true } }, [
+    field("Description", input("description", "", { autocomplete: "off" }), { full: true }),
+    field("Source currency", select("currency", ["USD", "CAD", "EUR", "GBP", "AUD", "MXN"].map((c) => [c, c]), "USD")),
+    field("Tags", input("tags"), { hint: "Comma separated (optional)" }),
+  ]);
+  const formError = el("div", { class: "form-error", attrs: { role: "alert" } });
+  const save = btn("Create batch", "primary");
+  const key = newKey();
+  app.editing += 1;
+  const modal = openModal({ title: "Create payment batch", body: [el("p", { text: "A batch groups payments that are quoted and processed together." }), form, formError], 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 = { currency: d.currency };
+    if (d.description.trim()) args.description = d.description.trim();
+    const tags = d.tags.split(",").map((t) => t.trim()).filter(Boolean);
+    if (tags.length) args.tags = tags;
+    save.disabled = true;
+    try {
+      const value = await call("batches.create", args, key);
+      modal.close();
+      toast("Batch created. Add payments to it.");
+      go("payments", value.batch.id);
+    } catch (error) {
+      if (!showFieldError(form, error)) formError.textContent = describe(error);
+      save.disabled = false;
+    }
+  });
+}

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

@@ -0,0 +1,79 @@
+// Overview: balance, sent value, recipients needing attention, batches awaiting processing.
+import { app, go, setTitle } from "./app.js";
+import { dataTable, errorBlock, stateBlock } from "./list.js";
+import { icon } from "./icons.js";
+import { btn, call, date, el, money, pill } from "./ui.js";
+
+function kpiCard(label) {
+  const value = el("div", { class: "kpi-value" }, el("div", { class: "skeleton" }));
+  const sub = el("div", { class: "kpi-sub" });
+  const node = el("section", { class: "card kpi" }, [el("div", { class: "kpi-label", text: label }), value, sub]);
+  return { node, set(v, s) { value.textContent = v; sub.textContent = s ?? ""; }, fail(error) { node.replaceChildren(errorBlock(error)); } };
+}
+
+export async function renderDashboard(host, route, view) {
+  setTitle("Overview");
+  const balanceCard = kpiCard("Available balance");
+  const sentCard = kpiCard("Payments Sent (Value)");
+  const attentionCard = kpiCard("Recipients");
+  const table = dataTable([
+    { label: "Amount", cell: (b) => money(b.amount, b.currency) },
+    { label: "Batch", cell: (b) => el("div", {}, [el("div", { text: b.description || "Untitled batch" }), el("div", { class: "sub mono", text: b.id })]) },
+    { label: "Payments", num: true, cell: (b) => String(b.totalPayments) },
+    { label: "Status", cell: (b) => pill(b.status) },
+    { label: "Created", cell: (b) => date(b.createdAt) },
+  ], { onRowClick: (b) => go("payments", b.id) });
+  const openCard = el("section", { class: "card" }, [
+    el("div", { class: "card-head" }, [el("h2", { text: "Batches awaiting processing" }), el("span", { class: "spacer" }), btn("View all payments", "link", { onClick: () => go("payments", undefined, { status: "open" }) })]),
+    table.node,
+  ]);
+  const recentCard = el("section", { class: "card" }, [el("div", { class: "card-head" }, el("h2", { text: "Recently completed" })), el("div", { class: "card-body" }, el("div", { class: "skeleton" }))]);
+  host.replaceChildren(el("div", { class: "stack" }, [
+    el("div", { class: "grid-3" }, [balanceCard.node, sentCard.node, attentionCard.node]),
+    el("div", { class: "grid-2" }, [openCard, recentCard]),
+  ]));
+
+  const [balances, open, complete, total, attention] = await Promise.allSettled([
+    call("balances.list", { kind: "paymentrails" }),
+    call("batches.list", { status: "open", pageSize: 10, orderBy: "createdAt", sortBy: "desc" }),
+    call("batches.list", { status: "complete", pageSize: 1000, orderBy: "createdAt", sortBy: "desc" }),
+    call("recipients.list", { pageSize: 1 }),
+    call("recipients.list", { status: "incomplete", pageSize: 1 }),
+  ]);
+  if (!view.isCurrent()) return;
+
+  if (balances.status === "fulfilled") {
+    const primary = balances.value.balances.find((b) => b.primary) ?? balances.value.balances[0];
+    app.now = balances.value.serverTime;
+    if (primary) balanceCard.set(money(primary.amount, primary.currency), `${primary.currency} · pending ${money(primary.pendingAmount, primary.currency)}`);
+    else balanceCard.set("—", "No balances");
+  } else balanceCard.fail(balances.reason);
+
+  if (complete.status === "fulfilled") {
+    const batches = complete.value.batches;
+    const byCurrency = new Map();
+    for (const batch of batches) byCurrency.set(batch.currency, (byCurrency.get(batch.currency) ?? 0) + Math.round(Number(batch.amount) * 100));
+    const [currency, cents] = [...byCurrency.entries()].sort((a, b) => b[1] - a[1])[0] ?? ["USD", 0];
+    const count = batches.reduce((sum, b) => sum + b.totalPayments, 0);
+    const capped = complete.value.meta.records > batches.length ? ` (first ${batches.length} batches)` : "";
+    sentCard.set(money((cents / 100).toFixed(2), currency), `${count} payments in ${batches.length} completed batches${capped}`);
+    const body = recentCard.querySelector(".card-body");
+    body.replaceChildren(batches.length === 0 ? stateBlock("money", "No completed batches yet", "Processed batches appear here.") :
+      el("div", {}, batches.slice(0, 5).map((b) => el("div", { class: "method" }, [
+        el("div", { class: "method-icon done" }, icon("check")),
+        el("div", { class: "method-main" }, [el("div", { class: "method-title", text: b.description || b.id }), el("div", { class: "method-sub", text: `${b.totalPayments} payments · ${date(b.completedAt ?? b.updatedAt)}` })]),
+        el("strong", { text: money(b.amount, b.currency) }),
+      ]))));
+  } else {
+    sentCard.fail(complete.reason);
+    recentCard.querySelector(".card-body").replaceChildren(errorBlock(complete.reason));
+  }
+
+  if (total.status === "fulfilled" && attention.status === "fulfilled") {
+    attentionCard.set(String(total.value.meta.records), `${attention.value.meta.records} incomplete profiles need attention`);
+  } else attentionCard.fail(total.reason ?? attention.reason);
+
+  if (open.status === "fulfilled") {
+    table.setRows(open.value.batches, stateBlock("check", "Nothing waiting", "All batches have been processed."));
+  } else table.setError(open.reason, () => go("dashboard"));
+}

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

@@ -0,0 +1,80 @@
+// "Select payout method" form, modelled on the dashboard's payout method picker (Bank transfer / Venmo / PayPal / Check).
+import { app } from "./app.js";
+import { icon } from "./icons.js";
+import { btn, call, describe, el, field, input, newKey, openModal, select, showFieldError, toast } from "./ui.js";
+
+const TYPES = [["bank-transfer", "Bank transfer", "bank"], ["venmo", "Venmo", "phone"], ["paypal", "PayPal", "paypal"], ["check", "Check", "mail"]];
+const CURRENCIES = ["USD", "CAD", "EUR", "GBP", "AUD", "MXN"].map((c) => [c, c]);
+
+export function methodIcon(type) {
+  const found = TYPES.find(([t]) => t === type);
+  return icon(found ? found[2] : "bank");
+}
+export function methodLine(account) {
+  if (account.type === "bank-transfer") return [account.bankName, account.accountNum ?? account.iban, account.country].filter(Boolean).join(" · ");
+  if (account.type === "paypal") return account.emailAddress ?? "";
+  if (account.type === "venmo") return account.phoneNumber ?? "";
+  if (account.type === "check") return [account.mailing?.name, account.mailing?.city, account.mailing?.country].filter(Boolean).join(" · ");
+  return "";
+}
+
+export function openAddMethod(recipient, done) {
+  let type = "bank-transfer";
+  const form = el("form", { class: "form-grid", attrs: { novalidate: true } });
+  const choices = el("div", { class: "choice-row field-full", attrs: { role: "group", "aria-label": "Payout method" } });
+  const draw = () => {
+    choices.replaceChildren(...TYPES.map(([value, label, glyph]) => el("button", { class: "choice", attrs: { type: "button", "aria-pressed": String(value === type) }, on: { click: () => { type = value; draw(); } } }, [icon(glyph), el("span", { text: label })])));
+    const fields = [];
+    if (type === "bank-transfer") {
+      fields.push(field("Bank account currency", select("currency", CURRENCIES, recipient.primaryCurrency ?? "USD")), field("Bank country", input("country", recipient.address?.country ?? "US", { maxlength: 2 })),
+        field("Account holder name", input("accountHolderName", recipient.name), { full: true }), field("Routing / branch number", input("branchId")), field("Account number", input("accountNum", "", { inputmode: "numeric" })),
+        field("Bank ID (Canada)", input("bankId")), field("IBAN (instead of account number)", input("iban")));
+    } else if (type === "paypal") {
+      fields.push(field("PayPal email", input("emailAddress", recipient.email, { type: "email" }), { full: true }), field("Currency", select("currency", CURRENCIES, "USD")));
+    } else if (type === "venmo") {
+      fields.push(field("Venmo phone number", input("phoneNumber", recipient.phone ?? ""), { full: true, hint: "US numbers only" }));
+    } else {
+      const a = recipient.address ?? {};
+      fields.push(field("Name on check", input("mailing.name", recipient.name), { full: true }), field("Street", input("mailing.street1", a.street1), { full: true }),
+        field("City", input("mailing.city", a.city)), field("State", input("mailing.region", a.region)), field("ZIP", input("mailing.postal", a.postalCode)), field("Country", input("mailing.country", "US", { maxlength: 2 })));
+    }
+    form.replaceChildren(choices, ...fields);
+  };
+  draw();
+  const formError = el("div", { class: "form-error", attrs: { role: "alert" } });
+  const save = btn("Add payout method", "dark");
+  let key = newKey();
+  let keyType = type;
+  app.editing += 1;
+  const modal = openModal({
+    title: "Select payout method",
+    body: [el("p", { text: "Processing time and fees follow this synthetic merchant's schedule. No bank, PayPal, Venmo or mail network is contacted." }), 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, type };
+    const mailing = {};
+    for (const [name, raw] of Object.entries(d)) {
+      const value = String(raw).trim();
+      if (!value) continue;
+      if (name.startsWith("mailing.")) mailing[name.slice(8)] = name.endsWith("country") ? value.toUpperCase() : value;
+      else args[name] = name === "country" ? value.toUpperCase() : value;
+    }
+    if (type === "check") args.mailing = mailing;
+    if (keyType !== type) { key = newKey(); keyType = type; }
+    save.disabled = true;
+    formError.textContent = "";
+    try {
+      await call("recipient_accounts.create", args, key);
+      modal.close();
+      toast("Payout method added.");
+      done();
+    } catch (error) {
+      if (!showFieldError(form, error)) formError.textContent = describe(error);
+      save.disabled = false;
+    }
+  });
+}