@firedrill-tools/netsuite 0.1.2

package/firedrill/tools/netsuite/app/site/views/pickers.js

@@ -0,0 +1,117 @@
+// Record pickers used by the transaction entry forms. Each pages through its collection as the user types,
+// so nothing past the first page is silently hidden.
+import { listIds, expand } from "../store.js";
+import { el, errorBanner, lit, money, qty } from "../ui.js";
+import { dialog } from "../overlay.js";
+
+const PAGE = 10;
+
+function pickerDialog({ title, label, placeholder, search, columns, renderRow }) {
+  return new Promise((resolve) => {
+    let answered = false;
+    let offset = 0;
+    let term = "";
+    const body = el("tbody", {});
+    const status = el("div", { class: "muted", text: "Loading…" });
+    const inputId = `${title.replace(/\W+/g, "-").toLowerCase()}-search`;
+    const input = el("input", { type: "search", id: inputId, placeholder });
+    const previous = el("button", { type: "button", class: "btn", text: "Previous", disabled: true });
+    const next = el("button", { type: "button", class: "btn", text: "Next", disabled: true });
+
+    const choose = (record) => { answered = true; resolve(record); box.close(); };
+
+    async function load() {
+      status.textContent = "Loading…";
+      try {
+        const { rows, page } = await search(term, offset, PAGE);
+        body.replaceChildren(...(rows.length === 0
+          ? [el("tr", {}, el("td", { colspan: String(columns.length), class: "muted", text: "No matching records." }))]
+          : rows.map((record) => {
+              const row = renderRow(record);
+              row.tabIndex = 0;
+              row.addEventListener("click", () => choose(record));
+              row.addEventListener("keydown", (event) => { if (event.key === "Enter" || event.key === " ") { event.preventDefault(); choose(record); } });
+              return row;
+            })));
+        status.textContent = page.totalResults === 0
+          ? "No records"
+          : `${page.offset + 1} to ${page.offset + rows.length} of ${page.totalResults}`;
+        previous.disabled = offset === 0;
+        next.disabled = page.hasMore !== true;
+      } catch (error) {
+        body.replaceChildren(el("tr", {}, el("td", { colspan: String(columns.length) }, errorBanner(error, "This list could not be loaded"))));
+        status.textContent = "";
+      }
+    }
+    let timer;
+    input.addEventListener("input", () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => { term = input.value.trim(); offset = 0; load(); }, 200);
+    });
+    previous.addEventListener("click", () => { offset = Math.max(0, offset - PAGE); load(); });
+    next.addEventListener("click", () => { offset += PAGE; load(); });
+
+    const box = dialog({
+      title,
+      wide: true,
+      body: [
+        el("div", { class: "field" }, [el("label", { class: "fl", for: inputId, text: label }), input]),
+        el("div", { class: "tablewrap" }, el("table", { class: "grid" }, [
+          el("thead", {}, el("tr", {}, columns.map((column) => el("th", { scope: "col", class: column.numeric ? "num" : "", text: column.label })))),
+          body,
+        ])),
+        el("div", { class: "pager" }, [status, el("span", { class: "grow" }), previous, next]),
+      ],
+      actions: [{ label: "Cancel", run: (close) => close() }],
+      onClose: () => { if (!answered) resolve(null); },
+    });
+    load();
+  });
+}
+
+export function pickCustomer() {
+  return pickerDialog({
+    title: "Choose a Customer",
+    label: "Search customers",
+    placeholder: "Name, company or e-mail",
+    columns: [{ label: "Name" }, { label: "Subsidiary" }, { label: "Balance", numeric: true }],
+    search: async (term, offset, limit) => {
+      const parts = ["isInactive IS false"];
+      if (term !== "") {
+        const value = lit(term);
+        parts.push(`(entityId CONTAIN ${value} OR companyName CONTAIN ${value} OR email CONTAIN ${value})`);
+      }
+      const page = await listIds("customer.list", { q: parts.join(" AND "), limit, offset });
+      return { rows: await expand("customer.get", page.ids), page };
+    },
+    renderRow: (record) => el("tr", {}, [
+      el("td", { text: record.entityId ?? record.id }),
+      el("td", { text: record.subsidiary?.refName ?? "" }),
+      el("td", { class: "num", text: money(record.balance, record.currency?.refName ?? "") }),
+    ]),
+  });
+}
+
+export function pickItem() {
+  return pickerDialog({
+    title: "Choose an Item",
+    label: "Search items",
+    placeholder: "Item name or display name",
+    columns: [{ label: "Item" }, { label: "Display Name" }, { label: "Base Price", numeric: true }, { label: "On Hand", numeric: true }],
+    search: async (term, offset, limit) => {
+      const parts = ["isInactive IS false"];
+      if (term !== "") {
+        const value = lit(term);
+        parts.push(`(itemId CONTAIN ${value} OR displayName CONTAIN ${value})`);
+      }
+      const page = await listIds("inventory-item.list", { q: parts.join(" AND "), limit, offset });
+      return { rows: await expand("inventory-item.get", page.ids), page };
+    },
+    renderRow: (record) => el("tr", {}, [
+      el("td", { text: record.itemId }),
+      el("td", { text: record.displayName ?? "" }),
+      el("td", { class: "num", text: money(record.basePrice) }),
+      el("td", { class: "num", text: qty(record.quantityOnHand) }),
+    ]),
+  });
+}

package/firedrill/tools/netsuite/app/site/views/subsidiaries.js

@@ -0,0 +1,40 @@
+// Setup → Company → Subsidiaries: the read-only subsidiary hierarchy of this OneWorld account.
+import { register } from "../store.js";
+import { call, el, errorBanner, emptyState, mdy, skeletonRows } from "../ui.js";
+import { listShell, setPageTitle, nsButton } from "./common.js";
+
+const COLUMNS = [
+  { label: "Name" }, { label: "Internal ID" }, { label: "Parent" },
+  { label: "Country" }, { label: "Currency" }, { label: "Elimination" }, { label: "Inactive" },
+];
+
+register("subsidiaries", async (main) => {
+  setPageTitle("Subsidiaries");
+  const body = el("tbody", {}, skeletonRows(COLUMNS.length, 3));
+  main.replaceChildren(listShell({
+    title: "Subsidiaries",
+    subtitle: "Read-only in this Tool: the subsidiary tree is seeded by the world.",
+    actions: [nsButton("New Subsidiary"), nsButton("Customize View")],
+    columns: COLUMNS,
+    body,
+  }));
+  try {
+    const page = await call("subsidiary.list", { limit: 50, offset: 0 });
+    const rows = page.items ?? [];
+    if (rows.length === 0) {
+      body.replaceChildren(el("tr", {}, el("td", { colspan: String(COLUMNS.length) }, emptyState("No subsidiaries are visible to this role."))));
+      return;
+    }
+    body.replaceChildren(...rows.map((record) => el("tr", {}, [
+      el("td", {}, el("span", { text: `${record.parent ? "— " : ""}${record.name}` })),
+      el("td", { class: "tight mono", text: record.id }),
+      el("td", { text: record.parent?.refName ?? "" }),
+      el("td", { text: record.country?.refName ?? "" }),
+      el("td", { text: record.currency?.refName ?? "" }),
+      el("td", { text: record.isElimination ? "Yes" : "No" }),
+      el("td", { text: record.isInactive ? "Yes" : "No" }),
+    ])));
+  } catch (error) {
+    body.replaceChildren(el("tr", {}, el("td", { colspan: String(COLUMNS.length) }, errorBanner(error, "Subsidiaries could not be loaded"))));
+  }
+});

package/firedrill/tools/netsuite/app/site/views/suiteql.js

@@ -0,0 +1,81 @@
+// Analytics → SuiteQL Query Tool: a query box, a results grid with paging and the raw response body.
+// This screen mirrors the widely used community SuiteQL Query Tool SuiteApp rather than a core NetSuite page.
+import { can, register } from "../store.js";
+import { call, el, errorBanner, emptyState, describe } from "../ui.js";
+import { recordShell, setPageTitle, toolbarButton, nsButton } from "./common.js";
+
+const SAMPLES = [
+  ["Invoiced total by customer",
+    "SELECT c.entityid AS customer, COUNT(t.id) AS invoices, SUM(t.foreigntotal) AS invoiced\nFROM transaction t JOIN customer c ON c.id = t.entity\nWHERE t.type = 'CustInvc'\nGROUP BY c.entityid\nORDER BY invoiced DESC"],
+  ["Customers by subsidiary", "SELECT id, entityid, BUILTIN.DF(subsidiary) AS subsidiary FROM customer ORDER BY id"],
+  ["Recent transactions", "SELECT id, tranid, trandate, type, status, foreigntotal FROM transaction ORDER BY trandate DESC"],
+];
+const PAGE = 25;
+
+register("suiteql", async (main) => {
+  setPageTitle("SuiteQL Query Tool");
+  if (!can("REPO_ANALYTICS")) {
+    main.replaceChildren(recordShell({
+      title: "SuiteQL Query Tool",
+      subtitle: "SuiteAnalytics Workbook permission required",
+      body: errorBanner(new Error("Your role does not have the SuiteAnalytics Workbook permission, so SuiteQL queries are refused."), "Permission Violation"),
+    }));
+    return;
+  }
+  const editor = el("textarea", { id: "sql-text", class: "sql-editor", spellcheck: "false", value: SAMPLES[0][1] });
+  const resultHost = el("div", {}, el("p", { class: "muted", text: "Run a query to see results." }));
+  const rawHost = el("div", {});
+  let offset = 0;
+
+  async function run(nextOffset = 0) {
+    offset = nextOffset;
+    resultHost.replaceChildren(el("p", { class: "muted", text: "Running query…" }));
+    rawHost.replaceChildren();
+    try {
+      const value = await call("suiteql.query", { q: editor.value, prefer: "transient", limit: PAGE, offset });
+      const rows = value.items ?? [];
+      if (rows.length === 0) {
+        resultHost.replaceChildren(emptyState("The query returned no rows.", "SuiteQL returns every scalar as a string, as NetSuite does."));
+      } else {
+        const columns = [...new Set(rows.flatMap((row) => Object.keys(row).filter((key) => key !== "links")))];
+        resultHost.replaceChildren(
+          el("div", { class: "tablewrap" }, el("table", { class: "grid" }, [
+            el("thead", {}, el("tr", {}, columns.map((name) => el("th", { scope: "col", text: name })))),
+            el("tbody", {}, rows.map((row) => el("tr", {}, columns.map((name) => el("td", { text: row[name] === undefined || row[name] === null ? "" : String(row[name]) }))))),
+          ])),
+          el("div", { class: "pager" }, [
+            el("span", { text: `${value.offset + 1} to ${value.offset + rows.length} of ${value.totalResults}` }),
+            el("span", { class: "grow" }),
+            el("button", { type: "button", class: "btn", text: "Previous", disabled: offset === 0, onclick: () => run(Math.max(0, offset - PAGE)) }),
+            el("button", { type: "button", class: "btn", text: "Next", disabled: value.hasMore !== true, onclick: () => run(offset + PAGE) }),
+          ]),
+        );
+      }
+      rawHost.replaceChildren(el("div", { class: "sql-out" }, el("pre", { text: JSON.stringify(value, null, 2).slice(0, 20000) })));
+    } catch (error) {
+      resultHost.replaceChildren(errorBanner(error, "The query could not be run"));
+      rawHost.replaceChildren(el("div", { class: "sql-out" }, el("pre", { text: describe(error) })));
+    }
+  }
+
+  main.replaceChildren(recordShell({
+    title: "SuiteQL Query Tool",
+    subtitle: "POST /services/rest/query/v1/suiteql · Prefer: transient",
+    actions: [
+      toolbarButton("Run Query", () => run(0), { kind: "primary" }),
+      toolbarButton("Clear", () => { editor.value = ""; resultHost.replaceChildren(el("p", { class: "muted", text: "Run a query to see results." })); rawHost.replaceChildren(); }),
+      nsButton("Save Query"),
+      nsButton("Query History"),
+    ],
+    body: [
+      el("div", { class: "field" }, [el("label", { class: "fl", for: "sql-text", text: "SuiteQL" }), editor]),
+      el("div", { class: "btn-row" }, [
+        el("span", { class: "muted", text: "Samples:" }),
+        ...SAMPLES.map(([label, text]) => el("button", { type: "button", class: "btn link", text: label, onclick: () => { editor.value = text; } })),
+      ]),
+      el("section", { class: "sublist" }, [el("header", {}, el("h3", { text: "Results" })), el("div", { class: "fg-body" }, resultHost)]),
+      el("section", { class: "sublist" }, [el("header", {}, el("h3", { text: "Response body" })), rawHost]),
+    ],
+  }));
+  await run(0);
+});

package/firedrill/tools/netsuite/behavior.mjs

@@ -0,0 +1,13 @@
+// NetSuite (SuiteTalk REST Web Services subset) Tool behavior: synchronous handlers over context.state plus
+// pure provider-shaped wire codecs. Reads live in lib/handlers-read.mjs, the MCP-shaped reads, metadata and
+// SuiteQL in lib/handlers-meta.mjs, and the nine writes in lib/handlers-write.mjs.
+import { readOperations } from "./lib/handlers-read.mjs";
+import { metaOperations } from "./lib/handlers-meta.mjs";
+import { writeOperations } from "./lib/handlers-write.mjs";
+import { sessionOperations } from "./lib/handlers-session.mjs";
+import { routes } from "./lib/wire.mjs";
+
+export default {
+  operations: { ...readOperations, ...metaOperations, ...writeOperations, ...sessionOperations },
+  http: routes,
+};

package/firedrill/tools/netsuite/lib/body.mjs

@@ -0,0 +1,185 @@
+// Wire-body validation for the write operations: typed field readers that raise NetSuite's INVALID_CONTENT,
+// INVALID_KEY_OR_REF and INVALID_REQUEST rather than any incidental JavaScript message.
+import { quote } from "./errors.mjs";
+import { isInternalId, isUnsafeKey, parseDate, round4 } from "./primitives.mjs";
+
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+/** Turn a decoder's body-shape flag into the documented INVALID_REQUEST failure. */
+export function checkBodyError(session, input) {
+  if (input.bodyError === undefined) return;
+  const reasons = {
+    depth: "The request body nests deeper than the supported maximum of 512 levels.",
+    prototype: "The request body carries a reserved property name (__proto__, constructor or prototype).",
+    "not-json": "The request body could not be parsed as JSON.",
+  };
+  session.fail("INVALID_REQUEST", reasons[input.bodyError] ?? reasons["not-json"]);
+}
+
+export function requestBody(session, input) {
+  checkBodyError(session, input);
+  const body = input.body;
+  if (body === undefined) return {};
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    session.fail("INVALID_CONTENT", "The request body must be a JSON object.");
+  }
+  for (const key of Object.keys(body)) {
+    if (isUnsafeKey(key)) {
+      session.fail("INVALID_REQUEST", "The request body carries a reserved property name.");
+    }
+  }
+  return body;
+}
+
+export function idempotencyKey(session, input) {
+  const key = input.idempotencyKeyHeader;
+  if (key === undefined) return;
+  if (typeof key !== "string" || !UUID.test(key)) {
+    session.fail("INVALID_PARAMETER", "The X-NetSuite-Idempotency-Key header must be an RFC 4122 UUID.", {
+      errorHeader: "X-NetSuite-Idempotency-Key",
+    });
+  }
+}
+
+/** `propertyNameValidation: error` rejects any body property the record does not define. */
+export function checkPropertyNames(session, input, body, known, prefix = "") {
+  const mode = input.propertyNameValidation ?? "warning";
+  if (mode !== "error") return;
+  for (const key of Object.keys(body)) {
+    if (!known.has(key)) {
+      session.fail("INVALID_CONTENT", `Unknown property ${quote(`${prefix}${key}`)} for this record type.`, {
+        errorPath: `${prefix}${key}`,
+      });
+    }
+  }
+}
+
+export function checkVersion(session, input, row) {
+  if (input.ifMatchVersion === undefined) return;
+  const claimed = String(input.ifMatchVersion).replaceAll('"', "").replace(/^W\//, "");
+  if (claimed !== String(row.version)) {
+    session.fail(
+      "RCRD_HAS_BEEN_CHANGED",
+      "Record has been changed. Please refresh the record and try again.",
+    );
+  }
+}
+
+export function field(session, body, name, prefix = "") {
+  return Object.hasOwn(body, name) ? body[name] : undefined;
+}
+
+export function stringField(session, body, name, maxLength, prefix = "") {
+  const value = field(session, body, name);
+  if (value === undefined || value === null) return value === null ? null : undefined;
+  if (typeof value !== "string" || value.length > maxLength) {
+    session.fail("INVALID_CONTENT", `Invalid value for ${quote(`${prefix}${name}`)}. Expected a string of at most ${maxLength} characters.`, {
+      errorPath: `${prefix}${name}`,
+    });
+  }
+  return value;
+}
+
+export function numberField(session, body, name, { min = -1e12, max = 1e12, prefix = "" } = {}) {
+  const value = field(session, body, name);
+  if (value === undefined || value === null) return value === null ? null : undefined;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+    session.fail("INVALID_CONTENT", `Invalid value for ${quote(`${prefix}${name}`)}. Expected a number between ${min} and ${max}.`, {
+      errorPath: `${prefix}${name}`,
+    });
+  }
+  return round4(value);
+}
+
+export function booleanField(session, body, name, prefix = "") {
+  const value = field(session, body, name);
+  if (value === undefined || value === null) return value === null ? null : undefined;
+  if (typeof value !== "boolean") {
+    session.fail("INVALID_CONTENT", `Invalid value for ${quote(`${prefix}${name}`)}. Expected true or false.`, {
+      errorPath: `${prefix}${name}`,
+    });
+  }
+  return value;
+}
+
+export function dateField(session, body, name, prefix = "") {
+  const value = field(session, body, name);
+  if (value === undefined || value === null) return value === null ? null : undefined;
+  if (typeof value !== "string") {
+    session.fail("INVALID_CONTENT", `Invalid value for ${quote(`${prefix}${name}`)}. Expected a date.`, { errorPath: `${prefix}${name}` });
+  }
+  const parsed = parseDate(value);
+  if (parsed === null) {
+    session.fail("INVALID_CONTENT", `Invalid value ${quote(value)} for ${quote(`${prefix}${name}`)}. Expected M/D/YYYY or YYYY-MM-DD.`, {
+      errorPath: `${prefix}${name}`,
+    });
+  }
+  return parsed;
+}
+
+/** Read a `{ id }` reference; the id must be syntactically valid before any state lookup. */
+export function referenceField(session, body, name, prefix = "") {
+  const value = field(session, body, name);
+  if (value === undefined || value === null) return value === null ? null : undefined;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    session.fail("INVALID_CONTENT", `Invalid value for ${quote(`${prefix}${name}`)}. Expected an object carrying an id.`, {
+      errorPath: `${prefix}${name}`,
+    });
+  }
+  const id = Object.hasOwn(value, "id") ? value.id : undefined;
+  if (id === undefined) {
+    session.fail("INVALID_KEY_OR_REF", `The reference ${quote(`${prefix}${name}`)} must carry an id.`, { errorPath: `${prefix}${name}` });
+  }
+  const text = typeof id === "number" && Number.isSafeInteger(id) ? String(id) : id;
+  if (!isInternalId(text)) {
+    session.fail("INVALID_KEY_OR_REF", `Invalid reference key ${quote(String(id))} for ${quote(`${prefix}${name}`)}.`, {
+      errorPath: `${prefix}${name}`,
+    });
+  }
+  return text;
+}
+
+/** Read `item.items` (or `apply.items`) as a bounded array of objects. */
+export function sublistItems(session, body, name, maxItems, prefix = "") {
+  const container = field(session, body, name);
+  if (container === undefined || container === null) return undefined;
+  if (typeof container !== "object" || Array.isArray(container)) {
+    session.fail("INVALID_CONTENT", `Invalid value for ${quote(`${prefix}${name}`)}. Expected an object carrying items.`, {
+      errorPath: `${prefix}${name}`,
+    });
+  }
+  const items = Object.hasOwn(container, "items") ? container.items : undefined;
+  if (items === undefined) return [];
+  if (!Array.isArray(items) || items.length > maxItems) {
+    session.fail("INVALID_CONTENT", `Invalid value for ${quote(`${prefix}${name}.items`)}. Expected at most ${maxItems} entries.`, {
+      errorPath: `${prefix}${name}.items`,
+    });
+  }
+  for (const [index, entry] of items.entries()) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      session.fail("INVALID_CONTENT", `Invalid entry at ${quote(`${prefix}${name}.items[${index}]`)}. Expected an object.`, {
+        errorPath: `${prefix}${name}.items[${index}]`,
+      });
+    }
+    for (const key of Object.keys(entry)) {
+      if (isUnsafeKey(key)) session.fail("INVALID_REQUEST", "The request body carries a reserved property name.");
+    }
+  }
+  return items;
+}
+
+/** Bounded list of field names for the `replace` parameter. */
+export function replaceList(session, input, allowed) {
+  if (input.replace === undefined) return new Set();
+  if (!Array.isArray(input.replace)) {
+    session.fail("INVALID_PARAMETER", "The replace parameter must be a comma-separated list of field names.", { errorQueryParam: "replace" });
+  }
+  const names = new Set();
+  for (const name of input.replace) {
+    if (typeof name !== "string" || !allowed.has(name)) {
+      session.fail("INVALID_PARAMETER", `Field ${quote(String(name))} cannot be replaced on this record.`, { errorQueryParam: "replace" });
+    }
+    names.add(name);
+  }
+  return names;
+}

package/firedrill/tools/netsuite/lib/collections.mjs

@@ -0,0 +1,202 @@
+// Paging, the record-collection envelope and the filterable-field tables the `q` grammar checks against.
+import { quote } from "./errors.mjs";
+import { jsonBytes } from "./primitives.mjs";
+import { evaluate, parseQ, QError } from "./q.mjs";
+import { indexById } from "./project.mjs";
+
+export const DEFAULT_LIMIT = 1000;
+const MAX_LIMIT = 1000;
+
+const integerOf = (value) => {
+  if (typeof value === "number") return Number.isSafeInteger(value) ? value : null;
+  if (typeof value !== "string" || value.trim() === "") return null;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+};
+
+export function booleanOf(session, value, name) {
+  if (value === undefined) return false;
+  if (typeof value === "boolean") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  session.fail("INVALID_PARAMETER", `Invalid value ${quote(String(value))} for the ${name} parameter. Use true or false.`, {
+    errorQueryParam: name,
+  });
+  return false;
+}
+
+/** NetSuite paging: limit 1–1000 (default 1000) and an offset that is a multiple of limit. */
+export function paging(session, input, defaultLimit = DEFAULT_LIMIT) {
+  let limit = defaultLimit;
+  if (input.limit !== undefined) {
+    const parsed = integerOf(input.limit);
+    if (parsed === null || parsed < 1 || parsed > MAX_LIMIT) {
+      session.fail("INVALID_PARAMETER", `Invalid value ${quote(String(input.limit))} for the limit parameter. Use an integer between 1 and ${MAX_LIMIT}.`, {
+        errorQueryParam: "limit",
+      });
+    }
+    limit = parsed;
+  }
+  let offset = 0;
+  if (input.offset !== undefined) {
+    const parsed = integerOf(input.offset);
+    if (parsed === null || parsed < 0) {
+      session.fail("INVALID_PARAMETER", `Invalid value ${quote(String(input.offset))} for the offset parameter. Use an integer of 0 or more.`, {
+        errorQueryParam: "offset",
+      });
+    }
+    offset = parsed;
+  }
+  if (offset % limit !== 0) {
+    session.fail("INVALID_PARAMETER", `Invalid value ${quote(String(offset))} for the offset parameter. The offset must be a multiple of the limit (${limit}).`, {
+      errorQueryParam: "offset",
+    });
+  }
+  return { limit, offset };
+}
+
+const day = (value) => (typeof value === "string" ? value.slice(0, 10) : null);
+
+export const FILTER_FIELDS = {
+  customer: {
+    id: { type: "numeric", read: (row) => Number(row.id) },
+    entityId: { type: "string", read: (row) => row.entityId },
+    companyName: { type: "string", read: (row) => row.companyName },
+    firstName: { type: "string", read: (row) => row.firstName },
+    lastName: { type: "string", read: (row) => row.lastName },
+    email: { type: "string", read: (row) => row.email },
+    phone: { type: "string", read: (row) => row.phone },
+    isPerson: { type: "boolean", read: (row) => row.isPerson },
+    isInactive: { type: "boolean", read: (row) => row.isInactive },
+    subsidiary: { type: "numeric", read: (row) => Number(row.subsidiaryId) },
+    dateCreated: { type: "date", read: (row) => day(row.dateCreated) },
+    lastModifiedDate: { type: "date", read: (row) => day(row.lastModifiedDate) },
+  },
+  salesOrder: {
+    id: { type: "numeric", read: (row) => Number(row.id) },
+    tranId: { type: "string", read: (row) => row.tranId },
+    tranDate: { type: "date", read: (row) => row.tranDate },
+    entity: { type: "numeric", read: (row) => Number(row.entityId) },
+    subsidiary: { type: "numeric", read: (row) => Number(row.subsidiaryId) },
+    status: { type: "string", read: (row) => row.status },
+    total: { type: "numeric", read: (row) => row.total },
+    memo: { type: "string", read: (row) => row.memo },
+    otherRefNum: { type: "string", read: (row) => row.otherRefNum },
+    lastModifiedDate: { type: "date", read: (row) => day(row.lastModifiedDate) },
+  },
+  invoice: {
+    id: { type: "numeric", read: (row) => Number(row.id) },
+    tranId: { type: "string", read: (row) => row.tranId },
+    tranDate: { type: "date", read: (row) => row.tranDate },
+    dueDate: { type: "date", read: (row) => row.dueDate },
+    entity: { type: "numeric", read: (row) => Number(row.entityId) },
+    subsidiary: { type: "numeric", read: (row) => Number(row.subsidiaryId) },
+    status: { type: "string", read: (row) => row.status },
+    total: { type: "numeric", read: (row) => row.total },
+    amountRemaining: { type: "numeric", read: (row) => Math.round((row.total - row.amountPaid) * 100) / 100 },
+    createdFrom: { type: "numeric", read: (row) => (row.createdFromId === null ? null : Number(row.createdFromId)) },
+    memo: { type: "string", read: (row) => row.memo },
+    otherRefNum: { type: "string", read: (row) => row.otherRefNum },
+    lastModifiedDate: { type: "date", read: (row) => day(row.lastModifiedDate) },
+  },
+  customerPayment: {
+    id: { type: "numeric", read: (row) => Number(row.id) },
+    tranId: { type: "string", read: (row) => row.tranId },
+    tranDate: { type: "date", read: (row) => row.tranDate },
+    customer: { type: "numeric", read: (row) => Number(row.entityId) },
+    payment: { type: "numeric", read: (row) => row.payment },
+    status: { type: "string", read: (row) => row.status },
+  },
+  inventoryItem: {
+    id: { type: "numeric", read: (row) => Number(row.id) },
+    itemId: { type: "string", read: (row) => row.itemId },
+    displayName: { type: "string", read: (row) => row.displayName },
+    isInactive: { type: "boolean", read: (row) => row.isInactive },
+    basePrice: { type: "numeric", read: (row) => row.basePrice },
+  },
+};
+
+/** Apply a `q` filter to state rows; an unparsable or unsupported filter is INVALID_REQUEST. */
+export function applyFilter(session, resource, rows, q) {
+  if (q === undefined || q === null) return rows;
+  if (typeof q !== "string") {
+    session.fail("INVALID_REQUEST", "The q parameter must be a string.", { errorQueryParam: "q" });
+  }
+  const fields = FILTER_FIELDS[resource];
+  let tree;
+  try {
+    tree = parseQ(q, fields);
+  } catch (error) {
+    if (error instanceof QError) {
+      session.fail("INVALID_REQUEST", `Invalid search query: ${error.message}.`, { errorQueryParam: "q" });
+    }
+    throw error;
+  }
+  try {
+    return rows.filter((row) => {
+      const flat = {};
+      for (const [name, field] of Object.entries(fields)) flat[name] = field.read(row);
+      return evaluate(tree, flat);
+    });
+  } catch (error) {
+    if (error instanceof QError) {
+      session.fail("INVALID_REQUEST", `Invalid search query: ${error.message}.`, { errorQueryParam: "q" });
+    }
+    throw error;
+  }
+}
+
+const pageHref = (path, limit, offset, q) =>
+  `${path}?${q === undefined || q === null ? "" : `q=${encodeURIComponent(q)}&`}limit=${limit}&offset=${offset}`;
+
+/**
+ * Build a NetSuite record collection. Entries are admitted one at a time and the assembled body's UTF-8 size is
+ * checked against maxPageBytes before it is returned, so an oversized single row fails rather than producing a
+ * body the framework would reject opaquely.
+ */
+export function collection(session, path, entries, { limit, offset, total, q }) {
+  const items = [];
+  let bytes = 220;
+  for (const entry of entries) {
+    const size = jsonBytes(entry);
+    if (bytes + size > session.maxPageBytes) {
+      if (items.length === 0) {
+        session.fail(
+          "RESULT_SET_TOO_LARGE",
+          `Search error occurred: one result row is ${size} bytes, larger than the supported page size of ${session.maxPageBytes} bytes.`,
+        );
+      }
+      break;
+    }
+    bytes += size + 1;
+    items.push(entry);
+  }
+  const returned = items.length;
+  const hasMore = offset + returned < total;
+  const links = [{ rel: "self", href: pageHref(path, limit, offset, q) }];
+  if (hasMore) links.push({ rel: "next", href: pageHref(path, limit, offset + returned, q) });
+  if (offset > 0) {
+    links.push({ rel: "previous", href: pageHref(path, limit, Math.max(0, offset - limit), q) });
+    links.push({ rel: "first", href: pageHref(path, limit, 0, q) });
+  }
+  if (total > 0) {
+    const lastOffset = Math.floor(Math.max(0, total - 1) / limit) * limit;
+    if (lastOffset !== offset) links.push({ rel: "last", href: pageHref(path, limit, lastOffset, q) });
+  }
+  return { links, items, count: returned, offset, hasMore, totalResults: total };
+}
+
+/** Shared lookup maps every projection needs, built from bounded scans. */
+export function projectionContext(session, expand = false) {
+  return {
+    expand,
+    today: session.today,
+    customers: indexById(session.rows("customers")),
+    items: indexById(session.rows("items")),
+    subsidiaries: indexById(session.rows("subsidiaries")),
+    invoices: indexById(session.rows("invoices")),
+    orders: indexById(session.rows("sales-orders")),
+    invoiceRows: session.rows("invoices"),
+    orderRows: session.rows("sales-orders"),
+  };
+}