@firedrill-tools/quickbooks 0.1.2

package/firedrill/tools/quickbooks/app/site/views/payments.js

@@ -0,0 +1,63 @@
+// Sales & Get paid > Payments: received payments with paging, customer filter, void and delete.
+import { app, go, query, queryAll, register } from "../store.js";
+import { call, confirmDialog, describe, el, errorBanner, icon, isAccessDenied, loadingRows, mdY, money, newKey, openMenu, quote, toast } from "../ui.js";
+import { emptyRow, pageShell, pager, salesTabs, select } from "./common.js";
+import { openReceivePayment } from "./receive-payment.js";
+
+const SIZE = 25;
+const isVoidedPayment = (p) => typeof p.PrivateNote === "string" && p.PrivateNote.startsWith("Voided");
+
+register("payments", async (host, route) => {
+  const p = route.params;
+  const customer = p.get("customer") ?? "";
+  const start = Math.max(1, Number(p.get("start")) || 1);
+  const nav = (patch) => { const n = new URLSearchParams(p); for (const [k, v] of Object.entries(patch)) v ? n.set(k, v) : n.delete(k); go(`#/payments?${n}`); };
+  const refresh = () => { if (host.isConnected) app.pages.payments(host, route); };
+  const { root, body } = pageShell("Payments", {
+    crumb: "Sales & Get paid",
+    actions: [el("button", { type: "button", class: "btn primary", text: "Receive payment", onclick: () => openReceivePayment({ onSaved: refresh }) })],
+    tabs: salesTabs("payments"),
+  });
+  const custSel = select([["", "All customers"]], "");
+  custSel.setAttribute("aria-label", "Customer");
+  custSel.addEventListener("change", () => nav({ customer: custSel.value, start: "" }));
+  const tbody = el("tbody", {}, loadingRows(8));
+  const foot = el("div");
+  const card = el("div", { class: "card" }, [
+    el("div", { class: "toolbar" }, [el("label", { class: "filter-label" }, ["Customer", custSel]), el("div", { class: "grow" })]),
+    el("div", { class: "table-wrap" }, el("table", { class: "grid" }, [el("thead", {}, el("tr", {}, ["Date", "Type", "No.", "Customer", "Method", "Deposit to", "Amount", "Status", "Action"].map((h, i) => el("th", { class: i === 6 ? "num" : i === 8 ? "act" : "", text: h })))), tbody])),
+    foot,
+  ]);
+  body.append(card);
+  host.replaceChildren(root);
+  queryAll("select * from Customer where Active IN (true, false) orderby DisplayName").then((cs) => { for (const c of cs) custSel.append(el("option", { value: c.Id, text: c.DisplayName })); custSel.value = customer; }).catch((error) => { if (!isAccessDenied(error)) toast(`Customer filter: ${describe(error)}`, { error: true }); });
+  try {
+    const clause = customer ? ` where CustomerRef = ${quote(customer)}` : "";
+    const total = (await call("query.run", { query: `select count(*) from Payment${clause}` })).QueryResponse.totalCount ?? 0;
+    const rows = await query(`select * from Payment${clause} orderby TxnDate desc STARTPOSITION ${start} MAXRESULTS ${SIZE}`);
+    tbody.replaceChildren(...(rows.length ? rows.map((pay) => {
+      const voided = isVoidedPayment(pay);
+      const unapplied = Number(pay.UnappliedAmt ?? 0);
+      const caret = el("button", { type: "button", class: "caret", "aria-label": `More actions for payment ${pay.Id}`, "aria-haspopup": "menu" }, icon("chevronDown"));
+      caret.addEventListener("click", () => openMenu(caret, [
+        { label: "Void", disabled: voided, run: async () => {
+          if (!(await confirmDialog("Void payment?", `Voiding sets this ${money(pay.TotalAmt)} payment to zero and reopens the invoices it paid.`, "Yes, void"))) return;
+          try { await call("payments.post", { operation: "void", body: { Id: pay.Id, SyncToken: pay.SyncToken } }, newKey()); toast("Payment voided"); refresh(); } catch (error) { toast(describe(error), { error: true }); }
+        } },
+        { label: "Delete", run: async () => {
+          if (!(await confirmDialog("Delete payment?", "Deleting this payment reopens the invoices it paid. This can't be undone.", "Yes, delete", "danger"))) return;
+          try { await call("payments.post", { operation: "delete", body: { Id: pay.Id, SyncToken: pay.SyncToken } }, newKey()); toast("Payment deleted"); refresh(); } catch (error) { toast(describe(error), { error: true }); }
+        } },
+      ]));
+      const status = voided ? "Voided" : unapplied > 0 ? `Unapplied ${money(unapplied)}` : "Closed";
+      return el("tr", {}, [el("td", { text: mdY(pay.TxnDate) }), el("td", { text: "Payment" }), el("td", { text: pay.PaymentRefNum ?? "" }),
+        el("td", {}, el("a", { href: `#/customers/${encodeURIComponent(pay.CustomerRef?.value ?? "")}`, text: pay.CustomerRef?.name ?? "" })),
+        el("td", { text: pay.PaymentMethodRef?.name ?? "" }), el("td", { text: pay.DepositToAccountRef?.name ?? "" }),
+        el("td", { class: "num", text: money(pay.TotalAmt) }), el("td", { class: voided ? "muted" : "", text: status }),
+        el("td", { class: "act" }, el("div", { class: "row-actions" }, [el("span", { class: "muted", text: "" }), caret]))]);
+    }) : [emptyRow(9, "No payments yet", "Record a payment when a customer pays an invoice.")]));
+    foot.replaceChildren(pager({ start, size: SIZE, total, onChange: (s) => nav({ start: String(s) }) }));
+  } catch (error) {
+    card.replaceWith(errorBanner(error, isAccessDenied(error) ? "You don't have access to payments" : "We couldn't load payments"));
+  }
+});

package/firedrill/tools/quickbooks/app/site/views/receive-payment.js

@@ -0,0 +1,102 @@
+// Receive payment form: customer, outstanding invoices with per-line payment amounts, deposit account → payments.post.
+import { app, queryAll } from "../store.js";
+import { ToolError, amount, call, confirmDialog, describe, el, errorBanner, mdY, money, newKey, quote, toast } from "../ui.js";
+import { field, input, select } from "./common.js";
+import { txnFrame } from "./txn-frame.js";
+
+const METHODS = [["", ""], ["1", "Cash"], ["2", "Check"], ["3", "Credit card"], ["4", "ACH / bank transfer"]];
+
+export async function openReceivePayment({ customerId = "", invoiceId = "", onSaved } = {}) {
+  let touched = false;
+  const t = txnFrame("Receive payment", { onClose: async (close) => { if (!touched || (await confirmDialog("Leave without saving?", "Do you want to leave without saving? Your changes will be lost.", "Yes, leave"))) close(); } });
+  t.canvas.append(el("div", { class: "loading" }, [el("span", { class: "spinner" }), el("span", { text: "Loading…" })]));
+  let customers; let deposit;
+  try {
+    [customers, deposit] = await Promise.all([
+      queryAll("select * from Customer orderby DisplayName"),
+      queryAll("select * from Account").then((a) => a.filter((x) => x.AccountType === "Bank" || x.AccountSubType === "UndepositedFunds")),
+    ]);
+  } catch (error) { t.canvas.replaceChildren(errorBanner(error, "We couldn't open Receive payment")); return; }
+  const undeposited = deposit.find((a) => a.AccountSubType === "UndepositedFunds");
+  const cust = field("Customer", select([["", "Choose a customer"], ...customers.map((c) => [c.Id, c.DisplayName])], customerId));
+  const email = field("Email", input({ type: "email", readonly: true, value: "" }));
+  const date = field("Payment date", input({ type: "date", value: app.today }));
+  const method = field("Payment method", select(METHODS, ""));
+  const ref = field("Reference no.", input({ maxlength: "21" }));
+  const dep = field("Deposit to", select(deposit.map((a) => [a.Id, a.Name]), undeposited?.Id ?? deposit[0]?.Id ?? ""));
+  const received = field("Amount received", input({ type: "number", step: "0.01", min: "0", class: "num" }));
+  const memo = field("Memo", el("textarea"));
+  const big = el("div", { class: "val", text: money(0) });
+  const formError = el("div");
+  const tbody = el("tbody");
+  let rows = [];
+  const sum = () => rows.reduce((s, r) => s + (r.check.checked ? Math.round(Number(r.pay.value || 0) * 100) : 0), 0);
+  const syncTotal = () => { const c = sum(); received.input.value = (c / 100).toFixed(2); big.textContent = money(c / 100); };
+  received.input.addEventListener("input", () => { touched = true; big.textContent = money(Number(received.input.value || 0)); });
+
+  async function loadOpen() {
+    rows = [];
+    const c = customers.find((x) => x.Id === cust.input.value);
+    email.input.value = c?.PrimaryEmailAddr?.Address ?? "";
+    if (!c) { tbody.replaceChildren(el("tr", {}, el("td", { class: "empty", colspan: 6, text: "Select a customer to see outstanding transactions." }))); syncTotal(); return; }
+    tbody.replaceChildren(el("tr", {}, el("td", { colspan: 6, class: "empty", text: "Loading outstanding transactions…" })));
+    try {
+      const open = await queryAll(`select * from Invoice where CustomerRef = ${quote(c.Id)} AND Balance > '0'`);
+      open.sort((a, b) => (a.DueDate < b.DueDate ? -1 : 1));
+      rows = open.map((inv) => {
+        const check = el("input", { type: "checkbox", "aria-label": `Apply payment to invoice ${inv.DocNumber}`, checked: invoiceId ? inv.Id === invoiceId : false });
+        const pay = el("input", { class: "cell-input num", type: "number", step: "0.01", min: "0", "aria-label": `Payment for invoice ${inv.DocNumber}`, value: check.checked ? String(inv.Balance) : "" });
+        check.addEventListener("change", () => { touched = true; pay.value = check.checked ? String(inv.Balance) : ""; pay.classList.remove("invalid"); syncTotal(); });
+        pay.addEventListener("input", () => { touched = true; check.checked = Number(pay.value) > 0; syncTotal(); });
+        const tr = el("tr", {}, [el("td", {}, check), el("td", { text: `Invoice # ${inv.DocNumber ?? inv.Id} (${mdY(inv.TxnDate)})` }), el("td", { text: mdY(inv.DueDate) }), el("td", { class: "amt", text: amount(inv.TotalAmt) }), el("td", { class: "amt", text: amount(inv.Balance) }), el("td", {}, pay)]);
+        return { inv, check, pay, tr };
+      });
+      tbody.replaceChildren(...(rows.length ? rows.map((r) => r.tr) : [el("tr", {}, el("td", { class: "empty", colspan: 6, text: "There are no outstanding transactions for this customer." }))]));
+      syncTotal();
+    } catch (error) { tbody.replaceChildren(el("tr", {}, el("td", { colspan: 6 }, errorBanner(error)))); }
+  }
+  cust.input.addEventListener("change", () => { touched = true; invoiceId = ""; loadOpen(); });
+
+  t.canvas.replaceChildren(el("div", { class: "sheet" }, [formError,
+    el("div", { class: "sheet-top" }, [el("div", { class: "row2" }, [cust.wrap, email.wrap]), el("div", { class: "sheet-balance" }, [el("div", { class: "lbl", text: "Amount received" }), big])]),
+    el("div", { class: "row3" }, [date.wrap, method.wrap, ref.wrap]),
+    el("div", { class: "row3" }, [dep.wrap, el("div"), received.wrap]),
+    el("div", { class: "section-title", text: "Outstanding transactions" }),
+    el("div", { class: "table-wrap" }, el("table", { class: "lines outstanding" }, [el("thead", {}, el("tr", {}, [el("th", {}, el("span", { class: "visually-hidden", text: "Apply" })), el("th", { text: "Description" }), el("th", { text: "Due date" }), el("th", { class: "amt", text: "Original amount" }), el("th", { class: "amt", text: "Open balance" }), el("th", { class: "amt", text: "Payment" })])), tbody])),
+    el("div", { class: "sheet-bottom" }, [el("div", { class: "notes" }, memo.wrap)]),
+  ]));
+  await loadOpen();
+
+  let key = newKey();
+  const save = el("button", { type: "button", class: "btn primary", text: "Save and close" });
+  save.addEventListener("click", async () => {
+    formError.replaceChildren(); for (const f of [cust, received, dep]) f.setError("");
+    if (!cust.input.value) { cust.setError("Choose a customer."); return cust.input.focus(); }
+    const total = Math.round(Number(received.input.value || 0) * 100);
+    const applied = sum();
+    if (total <= 0) { received.setError("Enter the amount received."); return received.input.focus(); }
+    if (applied > total) { received.setError("The amount received is less than the payments applied."); return; }
+    const body = { CustomerRef: { value: cust.input.value }, TotalAmt: total / 100, TxnDate: date.input.value || app.today, DepositToAccountRef: { value: dep.input.value },
+      Line: rows.filter((r) => r.check.checked && Number(r.pay.value) > 0).map((r) => ({ Amount: Math.round(Number(r.pay.value) * 100) / 100, LinkedTxn: [{ TxnId: r.inv.Id, TxnType: "Invoice" }] })) };
+    if (method.input.value) body.PaymentMethodRef = { value: method.input.value, name: METHODS.find((m) => m[0] === method.input.value)[1] };
+    if (ref.input.value.trim()) body.PaymentRefNum = ref.input.value.trim();
+    if (memo.input.value.trim()) body.PrivateNote = memo.input.value.trim();
+    save.disabled = true;
+    try {
+      const out = await call("payments.post", { body }, key);
+      key = newKey();
+      t.close();
+      toast(`Payment of ${money(out.Payment.TotalAmt)} saved${Number(out.Payment.UnappliedAmt) > 0 ? ` (${money(out.Payment.UnappliedAmt)} unapplied)` : ""}`);
+      onSaved?.();
+    } catch (error) {
+      save.disabled = false;
+      if (error instanceof ToolError && /Line|LinkedTxn|Amount/.test(error.element)) rows.forEach((r) => { if (r.check.checked) r.pay.classList.add("invalid"); });
+      if (error instanceof ToolError && error.element === "DepositToAccountRef") dep.setError(describe(error));
+      formError.replaceChildren(errorBanner(error, "We couldn't save this payment"));
+      if (!(error instanceof ToolError && error.is("THROTTLE_EXCEEDED"))) key = newKey();
+    }
+  });
+  t.foot.append(el("button", { type: "button", class: "btn", text: "Cancel", onclick: t.requestClose }),
+    el("button", { type: "button", class: "foot-link", text: "Clear payment", onclick: () => { rows.forEach((r) => { r.check.checked = false; r.pay.value = ""; }); syncTotal(); } }),
+    el("div", { class: "grow" }), save);
+}

package/firedrill/tools/quickbooks/app/site/views/txn-frame.js

@@ -0,0 +1,25 @@
+// Full-screen transaction frame shared by the invoice and receive-payment forms (header, grey canvas, dark footer).
+import { app } from "../store.js";
+import { el, icon, notSimulated } from "../ui.js";
+
+export function txnFrame(title, { onClose }) {
+  const previous = document.activeElement;
+  const titleNode = el("span", { text: title });
+  const canvas = el("div", { class: "txn-body" });
+  const foot = el("div", { class: "txn-foot" });
+  const close = () => { frame.remove(); document.removeEventListener("keydown", onKey); app.dirty = false; previous?.focus?.(); };
+  const requestClose = () => onClose(close);
+  const onKey = (e) => { if (e.key === "Escape" && !document.querySelector(".scrim, .menu-pop")) requestClose(); };
+  const head = el("div", { class: "txn-head" }, [
+    el("h1", {}, [el("img", { src: "./assets/quickbooks.svg", alt: "" }), titleNode]),
+    el("button", { type: "button", class: "icon-btn", "aria-label": "Recent transactions", title: "Recent transactions", onclick: () => notSimulated("Recent transactions") }, icon("history")),
+    el("button", { type: "button", class: "icon-btn", "aria-label": "Form settings", title: "Settings", onclick: () => notSimulated("Form settings") }, icon("gear")),
+    el("button", { type: "button", class: "icon-btn", "aria-label": "Help", title: "Help", onclick: () => notSimulated("Help") }, icon("help")),
+    el("button", { type: "button", class: "icon-btn", "aria-label": "Close", title: "Close", onclick: requestClose }, icon("close")),
+  ]);
+  const frame = el("div", { class: "txn", role: "dialog", "aria-modal": "true", "aria-label": title }, [head, canvas, foot]);
+  document.getElementById("overlay-root").append(frame);
+  document.addEventListener("keydown", onKey);
+  app.dirty = true;
+  return { frame, canvas, foot, close, requestClose, setTitle: (t) => { titleNode.textContent = t; frame.setAttribute("aria-label", t); } };
+}

package/firedrill/tools/quickbooks/behavior.mjs

@@ -0,0 +1,10 @@
+// QuickBooks Online (Accounting API v3 subset) Tool behavior: synchronous handlers over context.state plus pure
+// provider-shaped wire codecs. Read handlers live in lib/handlers-read.mjs, write handlers in lib/handlers-write.mjs.
+import { readOperations } from "./lib/handlers-read.mjs";
+import { writeOperations } from "./lib/handlers-write.mjs";
+import { routes } from "./lib/wire.mjs";
+
+export default {
+  operations: { ...readOperations, ...writeOperations },
+  http: routes,
+};

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

@@ -0,0 +1,167 @@
+// Caller identity, QuickBooks user-role model and the per-operation session (clock, caches, id counters, events).
+import { DEFAULT_OFFSET_MINUTES, clockOf, fail, isId, padId, scanAll, scanBound, toCents } from "./common.mjs";
+
+const ROLES = new Set(["company_admin", "standard_limited_customers", "reports_only"]);
+const LIMITED = new Set([
+  "company.read",
+  "query",
+  "customers.read",
+  "customers.write",
+  "invoices.read",
+  "invoices.write",
+  "payments.read",
+  "payments.write",
+  "items.read",
+]);
+
+export const NOT_FOUND_DETAIL =
+  "Object Not Found : Something you're trying to use has been made inactive or deleted. Check the fields with accounts, customers, items, vendors or employees.";
+
+/**
+ * Open a session for one operation call. Order: company present → actor realm claim → actor role → path/argument
+ * realm → role capability. Actors without attributes act as the company admin of the seeded realm.
+ */
+export function open(context, input, capability) {
+  const company = context.state.get("company", "company");
+  const offset = company !== null && Number.isInteger(company.utcOffsetMinutes) ? company.utcOffsetMinutes : DEFAULT_OFFSET_MINUTES;
+  const clock = clockOf(context, offset);
+  if (company === null) {
+    return fail(context, "AUTHENTICATION_FAILED", "This Firedrill world has no QuickBooks company, so no token can be valid for it.", "", clock);
+  }
+  const attributes = context.actor.attributes ?? {};
+  if (Object.hasOwn(attributes, "realmId") && attributes.realmId !== company.realmId) {
+    return fail(context, "AUTHENTICATION_FAILED", "Token is not valid for this company: the realmId it was issued for does not match.", "", clock);
+  }
+  let role = "company_admin";
+  if (Object.hasOwn(attributes, "role")) {
+    if (typeof attributes.role !== "string" || !ROLES.has(attributes.role)) {
+      return fail(context, "AUTHENTICATION_FAILED", "Token carries an unknown QuickBooks user role.", "", clock);
+    }
+    role = attributes.role;
+  }
+  if (input.realmId !== undefined && input.realmId !== company.realmId) {
+    return fail(context, "AUTHORIZATION_FAILED", "The application is not authorized to access the requested company (realmId).", "", clock);
+  }
+  const session = createSession(context, company, clock, role);
+  session.permit(capability);
+  return session;
+}
+
+function createSession(context, company, clock, role) {
+  const cache = new Map();
+  const bound = scanBound(context);
+  const s = {
+    context,
+    memo: new Map(),
+    company,
+    clock,
+    role,
+    realmId: company.realmId,
+    fail: (code, detail, element = "") => fail(context, code, detail, element, clock),
+    permit(capability) {
+      if (role === "company_admin") return;
+      if (role === "standard_limited_customers" && LIMITED.has(capability)) return;
+      if (role === "reports_only" && capability === "company.read") return;
+      s.fail("AUTHORIZATION_FAILED", `Your QuickBooks user role (${role}) does not allow this request (${capability}).`);
+    },
+    get(namespace, id) {
+      return isId(id) ? context.state.get(namespace, padId(id)) : null;
+    },
+    rows(namespace) {
+      if (!cache.has(namespace)) cache.set(namespace, scanAll(context, namespace, bound, clock));
+      return cache.get(namespace);
+    },
+    put(namespace, row) {
+      context.state.put(namespace, padId(row.Id), row);
+      invalidate(namespace);
+    },
+    remove(namespace, id) {
+      context.state.delete(namespace, padId(id));
+      invalidate(namespace);
+    },
+    emit(eventId, name, id, operation) {
+      context.events.emit(eventId, { realmId: company.realmId, name, id, operation, lastUpdated: clock.meta });
+    },
+    /** Next free id for an entity counter; skips ids already present (consumer-authored rows). */
+    nextId(key, namespace) {
+      const counters = context.state.get("meta", "counters") ?? {};
+      let next = Number.isInteger(counters[key]) && counters[key] >= 1 ? counters[key] : 1;
+      for (let guard = 0; context.state.get(namespace, padId(next)) !== null; guard += 1) {
+        if (guard >= bound) s.fail("STATE_BOUND_EXCEEDED", `No free ${key} id within the supported bound of ${bound} rows.`);
+        next += 1;
+      }
+      if (next > 9_999_999_999) s.fail("BUSINESS_VALIDATION", `The ${key} id space is exhausted.`);
+      context.state.put("meta", "counters", { ...defaultCounters(), ...counters, [key]: next + 1 });
+      return String(next);
+    },
+    setCounter(key, value) {
+      const counters = context.state.get("meta", "counters") ?? {};
+      context.state.put("meta", "counters", { ...defaultCounters(), ...counters, [key]: value });
+    },
+    counter(key) {
+      const counters = context.state.get("meta", "counters") ?? {};
+      return Number.isInteger(counters[key]) && counters[key] >= 1 ? counters[key] : 1;
+    },
+    /** Map invoice id → { cents, paymentIds[] } from non-voided payment lines. */
+    applied() {
+      if (!cache.has("#applied")) {
+        const map = new Map();
+        for (const payment of s.rows("payments")) {
+          for (const line of payment.Line) {
+            const invoiceId = line.LinkedTxn[0].TxnId;
+            const entry = map.get(invoiceId) ?? { cents: 0, paymentIds: [] };
+            entry.cents += toCents(line.Amount) ?? 0;
+            if (!entry.paymentIds.includes(payment.Id)) entry.paymentIds.push(payment.Id);
+            map.set(invoiceId, entry);
+          }
+        }
+        cache.set("#applied", map);
+      }
+      return cache.get("#applied");
+    },
+    /** Map customer id → open balance cents (Σ invoice Balance). */
+    balances() {
+      if (!cache.has("#balances")) {
+        const map = new Map();
+        for (const invoice of s.rows("invoices")) {
+          const id = invoice.CustomerRef.value;
+          map.set(id, (map.get(id) ?? 0) + (toCents(invoice.Balance) ?? 0));
+        }
+        cache.set("#balances", map);
+      }
+      return cache.get("#balances");
+    },
+  };
+  function invalidate(namespace) {
+    cache.delete(namespace);
+    if (namespace === "payments") cache.delete("#applied");
+    if (namespace === "invoices") cache.delete("#balances");
+  }
+  return s;
+}
+
+export function defaultCounters() {
+  return { customer: 1, item: 1, invoice: 1, payment: 1, docNumber: 1001 };
+}
+
+/** Load an entity row by caller id, or fail OBJECT_NOT_FOUND (ids are validated before any lookup). */
+export function load(s, namespace, id, element = "Id") {
+  const row = s.get(namespace, id);
+  if (row === null) s.fail("OBJECT_NOT_FOUND", NOT_FOUND_DETAIL, element);
+  return row;
+}
+
+export function staleCheck(s, row, syncToken) {
+  if (syncToken !== row.SyncToken) {
+    s.fail(
+      "STALE_OBJECT",
+      "Stale Object Error : You and another user were working on this at the same time. The other user finished before you did, so your work was not saved.",
+      "SyncToken",
+    );
+  }
+}
+
+export function bumpToken(row) {
+  const n = Number(row.SyncToken);
+  return String(Number.isSafeInteger(n) ? n + 1 : 1);
+}

package/firedrill/tools/quickbooks/lib/common.mjs

@@ -0,0 +1,204 @@
+// Shared pure helpers: QuickBooks fault codes, company-local time, ids, money in integer cents and bounded scans.
+// No module state, no wall clock: every time value derives from context.clock.nowUs().
+
+const FAULTS = new Map([
+  ["OBJECT_NOT_FOUND", ["610", "Object Not Found", "ValidationFault"]],
+  ["REQUIRED_PARAM_MISSING", ["2020", "Required param missing, need to supply the required value for the API", "ValidationFault"]],
+  ["INVALID_REFERENCE", ["2500", "Invalid Reference Id", "ValidationFault"]],
+  ["QUERY_PARSE_ERROR", ["4000", "Error parsing query", "ValidationFault"]],
+  ["QUERY_VALIDATION_ERROR", ["4001", "Invalid query", "ValidationFault"]],
+  ["STALE_OBJECT", ["5010", "Stale Object Error", "ValidationFault"]],
+  ["BUSINESS_VALIDATION", ["6000", "A business validation error has occurred while processing your request", "ValidationFault"]],
+  ["DUPLICATE_DOC_NUMBER", ["6140", "Duplicate Document Number Error", "ValidationFault"]],
+  ["DUPLICATE_NAME", ["6240", "Duplicate Name Exists Error", "ValidationFault"]],
+  ["AUTHENTICATION_FAILED", ["3200", "message=AuthenticationFailed; errorCode=003200; statusCode=401", "AuthenticationFault"]],
+  ["AUTHORIZATION_FAILED", ["3100", "message=ApplicationAuthorizationFailed; errorCode=003100; statusCode=403", "AuthorizationFault"]],
+  ["STATE_BOUND_EXCEEDED", ["10000", "An application error has occurred while processing your request", "SystemFault"]],
+  ["THROTTLE_EXCEEDED", ["3001", "message=ThrottleExceeded; errorCode=003001; statusCode=429", "SERVICE"]],
+  ["SERVICE_UNAVAILABLE", ["10000", "An application error has occurred while processing your request", "SystemFault"]],
+]);
+
+export function faultInfo(code) {
+  return FAULTS.get(code);
+}
+
+export const DEFAULT_OFFSET_MINUTES = -420;
+export const MAX_DETAIL = 2000;
+export const RESERVED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+export function clip(text, max = 200) {
+  const value = String(text);
+  return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+/** UTF-8 length of a string, counted per code point (1, 2, 3 or 4 bytes; lone surrogates count as 3). */
+export function utf8Bytes(text) {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const unit = text.charCodeAt(i);
+    if (unit < 0x80) bytes += 1;
+    else if (unit < 0x800) bytes += 2;
+    else if (unit >= 0xd800 && unit <= 0xdbff && i + 1 < text.length) { const next = text.charCodeAt(i + 1); if (next >= 0xdc00 && next <= 0xdfff) { bytes += 4; i += 1; } else bytes += 3; }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
+const pad2 = (n) => String(n).padStart(2, "0");
+
+function offsetText(minutes) {
+  const sign = minutes < 0 ? "-" : "+";
+  const abs = Math.abs(minutes);
+  return `${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`;
+}
+
+/** Company-local parts of an epoch-millisecond instant (fixed offset, host-independent). */
+function localParts(ms, offsetMinutes) {
+  const d = new Date(ms + offsetMinutes * 60000);
+  return {
+    date: `${String(d.getUTCFullYear()).padStart(4, "0")}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`,
+    clock: `${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}:${pad2(d.getUTCSeconds())}`,
+    millis: String(d.getUTCMilliseconds()).padStart(3, "0"),
+  };
+}
+
+export function clockOf(context, offsetMinutes = DEFAULT_OFFSET_MINUTES) {
+  const ms = Math.floor(context.clock.nowUs() / 1000);
+  const parts = localParts(ms, offsetMinutes);
+  const zone = offsetText(offsetMinutes);
+  return {
+    ms,
+    date: parts.date,
+    meta: `${parts.date}T${parts.clock}${zone}`,
+    time: `${parts.date}T${parts.clock}.${parts.millis}${zone}`,
+  };
+}
+
+/** Raise a declared error with the QuickBooks fault fields the wire encoder copies. */
+export function fail(context, code, detail, element = "", clock = clockOf(context)) {
+  const info = FAULTS.get(code);
+  return context.fail({
+    code,
+    message: info[1],
+    details: { qboCode: info[0], faultType: info[2], detail: clip(detail, MAX_DETAIL), element: clip(element, 200), time: clock.time },
+  });
+}
+
+export const ID_PATTERN = /^(0|[1-9][0-9]{0,9})$/;
+
+export function isId(value) {
+  return typeof value === "string" && ID_PATTERN.test(value);
+}
+
+export function padId(id) {
+  return String(id).padStart(10, "0");
+}
+
+const DATE_PATTERN = /^([0-9]{4})-([0-9]{2})-([0-9]{2})$/;
+
+/** Day number (days since 1970-01-01) of a strict YYYY-MM-DD calendar date, or null. */
+export function dayNumber(text) {
+  if (typeof text !== "string") return null;
+  const match = DATE_PATTERN.exec(text);
+  if (match === null) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (year < 1900 || month < 1 || month > 12 || day < 1) return null;
+  const ms = Date.UTC(year, month - 1, day);
+  const check = new Date(ms);
+  if (check.getUTCDate() !== day || check.getUTCMonth() !== month - 1) return null;
+  return Math.round(ms / 86400000);
+}
+
+export function dateFromDay(dayNum) {
+  const d = new Date(dayNum * 86400000);
+  return `${String(d.getUTCFullYear()).padStart(4, "0")}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+}
+
+const DATETIME_PATTERN = /^([0-9]{4}-[0-9]{2}-[0-9]{2})(?:T([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.([0-9]{1,6}))?)?(Z|[+-][0-9]{2}:[0-9]{2})?)?$/;
+
+/** Epoch milliseconds of a date or ISO date-time; zone-less values use the company offset. Null when invalid. */
+export function instantOf(text, offsetMinutes = DEFAULT_OFFSET_MINUTES) {
+  if (typeof text !== "string" || text.length > 40) return null;
+  const match = DATETIME_PATTERN.exec(text);
+  if (match === null) return null;
+  const day = dayNumber(match[1]);
+  if (day === null) return null;
+  const hours = match[2] === undefined ? 0 : Number(match[2]);
+  const minutes = match[3] === undefined ? 0 : Number(match[3]);
+  const seconds = match[4] === undefined ? 0 : Number(match[4]);
+  if (hours > 23 || minutes > 59 || seconds > 59) return null;
+  const millis = match[5] === undefined ? 0 : Math.floor(Number(`0.${match[5]}`) * 1000);
+  let zone = offsetMinutes;
+  if (match[6] === "Z") zone = 0;
+  else if (match[6] !== undefined) {
+    const zh = Number(match[6].slice(1, 3));
+    const zm = Number(match[6].slice(4, 6));
+    if (zh > 14 || zm > 59) return null;
+    zone = (match[6][0] === "-" ? -1 : 1) * (zh * 60 + zm);
+  }
+  return day * 86400000 + ((hours * 60 + minutes - zone) * 60 + seconds) * 1000 + millis;
+}
+
+/** Integer cents of a non-negative-or-any number with at most two decimals, or null. */
+export function toCents(value, { allowNegative = false, max = 99_999_999_999 } = {}) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const scaled = value * 100;
+  const cents = Math.round(scaled);
+  if (Math.abs(scaled - cents) > 1e-6) return null;
+  if (!allowNegative && cents < 0) return null;
+  if (Math.abs(cents) > max) return null;
+  return cents;
+}
+
+export function fromCents(cents) {
+  return cents / 100;
+}
+
+/** Value scaled by 10^4 when it has at most four decimals and lies within [0, max]; otherwise null. */
+export function toScaled4(value, max) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > max) return null;
+  const scaled = value * 10000;
+  const rounded = Math.round(scaled);
+  return Math.abs(scaled - rounded) > 1e-4 ? null : rounded;
+}
+
+/** Cents of qty x unitPrice (both scaled by 10^4), rounded half up, without floating error. */
+export function lineCents(qtyScaled, priceScaled) {
+  const product = BigInt(qtyScaled) * BigInt(priceScaled);
+  return Number((product + 500_000n) / 1_000_000n);
+}
+
+export const DEFAULT_SCAN_BOUND = 5000;
+
+export function scanBound(context) {
+  const limits = context.state.get("meta", "limits");
+  const value = limits === null ? undefined : limits.maxScanRows;
+  return Number.isInteger(value) && value >= 1 && value <= 10000 ? value : DEFAULT_SCAN_BOUND;
+}
+
+/** Every row of a namespace in row-id order; fails STATE_BOUND_EXCEEDED instead of truncating. */
+export function scanAll(context, namespace, bound, clock) {
+  const rows = [];
+  let after;
+  for (;;) {
+    const page = context.state.scan(namespace, after === undefined ? { limit: 1000 } : { afterRowId: after, limit: 1000 });
+    for (const record of page) {
+      rows.push(record.value);
+      if (rows.length > bound) {
+        return fail(context, "STATE_BOUND_EXCEEDED", `State exceeds the supported bound of ${bound} rows for ${namespace}.`, "", clock);
+      }
+    }
+    if (page.length < 1000) return rows;
+    after = page[page.length - 1].rowId;
+  }
+}
+
+export const TERMS = new Map([
+  ["1", { name: "Due on receipt", days: 0 }],
+  ["2", { name: "Net 15", days: 15 }],
+  ["3", { name: "Net 30", days: 30 }],
+]);
+
+export const USD = Object.freeze({ value: "USD", name: "United States Dollar" });