@firedrill-tools/netsuite 0.1.2

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

@@ -0,0 +1,91 @@
+// NetSuite problem-envelope helpers. Handlers raise declared Tool errors carrying the envelope fields in
+// `details`; the route codecs turn those into the documented `o:errorDetails` body.
+
+/** Longest piece of caller text ever quoted back in a `detail` string. */
+export const QUOTE_LIMIT = 200;
+
+export function quote(value) {
+  const text = typeof value === "string" ? value : String(value ?? "");
+  return text.length > QUOTE_LIMIT ? `${text.slice(0, QUOTE_LIMIT)}…` : text;
+}
+
+const TITLES = new Map([
+  [400, "Bad Request"],
+  [401, "Unauthorized"],
+  [403, "Forbidden"],
+  [404, "Not Found"],
+  [409, "Conflict"],
+  [429, "Bad Request"],
+  [500, "Internal Server Error"],
+]);
+
+const STATUS = new Map([
+  ["INVALID_LOGIN", 401],
+  ["INSUFFICIENT_PERMISSION", 403],
+  ["NONEXISTENT_ID", 404],
+  ["INVALID_ID", 400],
+  ["INVALID_CONTENT", 400],
+  ["INVALID_KEY_OR_REF", 400],
+  ["INVALID_PARAMETER", 400],
+  ["INVALID_REQUEST", 400],
+  ["USER_ERROR", 400],
+  ["RCRD_HAS_BEEN_CHANGED", 409],
+  ["CONCURRENCY_LIMIT_EXCEEDED", 429],
+  ["UNEXPECTED_ERROR", 500],
+  ["RESULT_SET_TOO_LARGE", 400],
+]);
+
+const TYPES = new Map([
+  [400, "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1"],
+  [401, "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.2"],
+  [403, "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.4"],
+  [404, "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.5"],
+  [409, "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.10"],
+  [429, "https://www.rfc-editor.org/rfc/rfc6585#section-4"],
+  [500, "https://www.rfc-editor.org/rfc/rfc9110#section-15.6.1"],
+]);
+
+export function statusFor(code) {
+  return STATUS.get(code) ?? 400;
+}
+
+/** Build the documented NetSuite problem body for one Tool error code. */
+export function problemBody(code, detail, extra = {}) {
+  const status = statusFor(code);
+  const entry = { detail, "o:errorCode": code };
+  for (const [key, value] of [
+    ["o:errorPath", extra.errorPath],
+    ["o:urlPath", extra.urlPath],
+    ["o:errorQueryParam", extra.errorQueryParam],
+    ["o:errorHeader", extra.errorHeader],
+  ]) {
+    if (typeof value === "string" && value.length > 0) entry[key] = value;
+  }
+  const body = {
+    type: TYPES.get(status) ?? TYPES.get(400),
+    title: TITLES.get(status) ?? "Bad Request",
+    status,
+    "o:errorDetails": [entry],
+  };
+  if (code === "CONCURRENCY_LIMIT_EXCEEDED") body["o:errorCode"] = "USER_ERROR";
+  return body;
+}
+
+/** Raise one of the declared errors with the envelope fields the codec needs. */
+export function fail(context, code, detail, extra = {}) {
+  context.fail({
+    code,
+    message: detail.length > 3900 ? `${detail.slice(0, 3900)}…` : detail,
+    retryable: code === "CONCURRENCY_LIMIT_EXCEEDED" || code === "UNEXPECTED_ERROR",
+    details: {
+      detail,
+      ...(typeof extra.errorPath === "string" ? { errorPath: extra.errorPath } : {}),
+      ...(typeof extra.urlPath === "string" ? { urlPath: extra.urlPath } : {}),
+      ...(typeof extra.errorQueryParam === "string" ? { errorQueryParam: extra.errorQueryParam } : {}),
+      ...(typeof extra.errorHeader === "string" ? { errorHeader: extra.errorHeader } : {}),
+    },
+  });
+}
+
+export const LOGIN_DETAIL =
+  "Invalid login attempt. For more details, see the Login Audit Trail in the NetSuite UI at Setup > Users/Roles > User Management > View Login Audit Trail.";

package/firedrill/tools/netsuite/lib/handlers-meta.mjs

@@ -0,0 +1,100 @@
+// The MCP-shaped record reads, the record-type metadata catalog and the two SuiteQL operations.
+import { quote } from "./errors.mjs";
+import { requireId } from "./primitives.mjs";
+import { open } from "./session.mjs";
+import { collection, paging } from "./collections.mjs";
+import { projectSubsidiary } from "./project-tran.mjs";
+import { KINDS, loadRecord, projectOne } from "./handlers-read.mjs";
+import { catalog, describe, RECORD_TYPES } from "./metadata.mjs";
+import { executeSql } from "./suiteql-select.mjs";
+import { SqlError } from "./suiteql-parse.mjs";
+
+const BY_RESOURCE = new Map(Object.entries(KINDS).map(([kind, definition]) => [definition.resource, kind]));
+const SQL_MAX_ROWS = 1000;
+const SUITEQL_PATH = "/services/rest/query/v1/suiteql";
+
+function runQuery(session, statement, params) {
+  if (typeof statement !== "string" || statement.trim().length === 0) {
+    session.fail("INVALID_REQUEST", "A SuiteQL request must carry a non-empty q value.");
+  }
+  try {
+    return executeSql(session, statement, params);
+  } catch (error) {
+    if (error instanceof SqlError) {
+      session.fail("INVALID_REQUEST", `Invalid SuiteQL statement: ${error.message}.`);
+    }
+    throw error;
+  }
+}
+
+function boundParams(session, params) {
+  if (params === undefined) return [];
+  if (!Array.isArray(params)) {
+    session.fail("INVALID_PARAMETER", "The params value must be an array of bind values.", { errorPath: "params" });
+  }
+  return params;
+}
+
+export const metaOperations = {
+  "record.get": (input, context) => {
+    const session = open(context);
+    const recordType = input.recordType;
+    if (typeof recordType !== "string" || !RECORD_TYPES.includes(recordType)) {
+      session.fail("INVALID_CONTENT", `Record type ${quote(String(recordType))} is not supported by this service.`, {
+        errorPath: "recordType",
+      });
+    }
+    if (recordType === "subsidiary") {
+      session.permit("LIST_SUBSIDIARY", "view");
+      requireId(context, input.recordId, "id");
+      const row = session.get("subsidiaries", input.recordId);
+      if (row === null || !session.inScope(row.id)) {
+        session.fail("NONEXISTENT_ID", `Invalid subsidiary reference key ${quote(String(input.recordId))}.`);
+      }
+      const index = new Map(session.rows("subsidiaries").map((entry) => [entry.id, entry]));
+      return projectSubsidiary(row, index);
+    }
+    const kind = BY_RESOURCE.get(recordType);
+    session.permit(KINDS[kind].permission, "view");
+    const row = loadRecord(session, kind, input.recordId);
+    return projectOne(session, kind, row, true);
+  },
+
+  "record.metadata": (input, context) => {
+    const session = open(context);
+    session.permit("SETUP_RECORD_METADATA", "view");
+    if (input.recordType === undefined) return catalog(session.now);
+    if (typeof input.recordType !== "string" || !RECORD_TYPES.includes(input.recordType)) {
+      session.fail("INVALID_CONTENT", `Record type ${quote(String(input.recordType))} is not supported by this service.`, {
+        errorPath: "recordType",
+      });
+    }
+    return describe(input.recordType, session.now);
+  },
+
+  "suiteql.query": (input, context) => {
+    const session = open(context);
+    session.permit("REPO_ANALYTICS", "view");
+    const prefer = typeof input.prefer === "string" ? input.prefer.toLowerCase() : "";
+    if (!prefer.split(",").map((entry) => entry.trim()).includes("transient")) {
+      session.fail("INVALID_REQUEST", "The Prefer: transient header is required for SuiteQL requests.", {
+        errorHeader: "Prefer",
+      });
+    }
+    const { limit, offset } = paging(session, input, 10);
+    const rows = runQuery(session, input.q, boundParams(session, input.params));
+    const entries = rows.slice(offset, offset + limit).map((row) => ({
+      links: [{ rel: "self", href: SUITEQL_PATH }],
+      ...row,
+    }));
+    return collection(session, SUITEQL_PATH, entries, { limit, offset, total: rows.length });
+  },
+
+  "suiteql.run": (input, context) => {
+    const session = open(context);
+    session.permit("REPO_ANALYTICS", "view");
+    const rows = runQuery(session, input.query, []);
+    const items = rows.slice(0, SQL_MAX_ROWS);
+    return { items, count: items.length, hasMore: rows.length > items.length, totalResults: rows.length };
+  },
+};

package/firedrill/tools/netsuite/lib/handlers-read.mjs

@@ -0,0 +1,141 @@
+// Read operations: the five record collections, their singular reads, the sales-order item sublist and subsidiaries.
+import { quote } from "./errors.mjs";
+import { requireId } from "./primitives.mjs";
+import { open } from "./session.mjs";
+import { applyFilter, booleanOf, collection, paging, projectionContext } from "./collections.mjs";
+import { projectCustomer, projectLine, selfLinks } from "./project.mjs";
+import { projectInvoice, projectItem, projectPayment, projectSalesOrder, projectSubsidiary } from "./project-tran.mjs";
+
+const REC = "/services/rest/record/v1";
+
+export const KINDS = {
+  customer: { namespace: "customers", resource: "customer", permission: "LIST_CUSTJOB", label: "customer" },
+  "sales-order": { namespace: "sales-orders", resource: "salesOrder", permission: "TRAN_SALESORD", label: "sales order" },
+  invoice: { namespace: "invoices", resource: "invoice", permission: "TRAN_CUSTINVC", label: "invoice" },
+  "customer-payment": { namespace: "customer-payments", resource: "customerPayment", permission: "TRAN_CUSTPYMT", label: "customer payment" },
+  "inventory-item": { namespace: "items", resource: "inventoryItem", permission: "LIST_ITEM", label: "inventory item" },
+};
+
+const visible = (session, kind, row) => (kind === "inventory-item"
+  ? row.subsidiaryIds.some((id) => session.inScope(id)) && row.itemType === "inventoryItem"
+  : session.inScope(row.subsidiaryId));
+
+export function loadRecord(session, kind, recordId) {
+  const definition = KINDS[kind];
+  requireId(session.context, recordId, "id");
+  const row = session.get(definition.namespace, recordId);
+  if (row === null || !visible(session, kind, row)) {
+    session.fail("NONEXISTENT_ID", `Invalid ${definition.resource} reference key ${quote(recordId)}.`, {
+      urlPath: `${REC}/${definition.resource}/${recordId}`,
+    });
+  }
+  return row;
+}
+
+/** Most field names one `fields` selection may name, matching the documented REST record-service bound. */
+const MAX_FIELDS = 40;
+/** Longest single field name accepted before it can only be an unknown field. */
+const MAX_FIELD_NAME = 120;
+
+/** Restrict a projected record to the caller's `fields` selection. */
+function selectFields(session, record, fields) {
+  if (fields === undefined) return record;
+  if (!Array.isArray(fields)) {
+    session.fail("INVALID_PARAMETER", "The fields parameter must be a comma-separated list of field names.", { errorQueryParam: "fields" });
+  }
+  if (fields.length > MAX_FIELDS) {
+    session.fail("INVALID_PARAMETER", `The fields parameter is limited to ${MAX_FIELDS} field names.`, { errorQueryParam: "fields" });
+  }
+  const picked = { links: record.links, id: record.id };
+  for (const name of fields) {
+    if (typeof name !== "string" || name.length === 0 || name.length > MAX_FIELD_NAME) {
+      session.fail("INVALID_PARAMETER", "The fields parameter must be a comma-separated list of field names.", { errorQueryParam: "fields" });
+    }
+    if (!Object.hasOwn(record, name)) {
+      session.fail("INVALID_PARAMETER", `Unknown field ${quote(name)} in the fields parameter.`, { errorQueryParam: "fields" });
+    }
+    picked[name] = record[name];
+  }
+  return picked;
+}
+
+export function projectOne(session, kind, row, expand) {
+  if (kind === "inventory-item") {
+    const subsidiaries = new Map();
+    for (const id of row.subsidiaryIds) {
+      const subsidiary = session.get("subsidiaries", id);
+      if (subsidiary !== null) subsidiaries.set(id, subsidiary);
+    }
+    return projectItem(row, subsidiaries);
+  }
+  const context = projectionContext(session, expand);
+  if (kind === "customer") return projectCustomer(row, context);
+  if (kind === "sales-order") return projectSalesOrder(row, context);
+  if (kind === "invoice") return projectInvoice(row, context);
+  return projectPayment(row, context);
+}
+
+function listHandler(kind) {
+  const definition = KINDS[kind];
+  return (input, context) => {
+    const session = open(context);
+    session.permit(definition.permission, "view");
+    const { limit, offset } = paging(session, input);
+    const rows = session.rows(definition.namespace).filter((row) => visible(session, kind, row));
+    const filtered = applyFilter(session, definition.resource, rows, input.q);
+    const page = filtered.slice(offset, offset + limit);
+    const entries = page.map((row) => ({ links: selfLinks(definition.resource, row.id), id: row.id }));
+    return collection(session, `${REC}/${definition.resource}`, entries, {
+      limit, offset, total: filtered.length, q: input.q,
+    });
+  };
+}
+
+function getHandler(kind) {
+  const definition = KINDS[kind];
+  return (input, context) => {
+    const session = open(context);
+    session.permit(definition.permission, "view");
+    const expand = booleanOf(session, input.expandSubResources, "expandSubResources");
+    booleanOf(session, input.simpleEnumFormat, "simpleEnumFormat");
+    const row = loadRecord(session, kind, input.recordId);
+    return selectFields(session, projectOne(session, kind, row, expand), input.fields);
+  };
+}
+
+export const readOperations = {
+  "customer.list": listHandler("customer"),
+  "customer.get": getHandler("customer"),
+  "sales-order.list": listHandler("sales-order"),
+  "sales-order.get": getHandler("sales-order"),
+  "invoice.list": listHandler("invoice"),
+  "invoice.get": getHandler("invoice"),
+  "customer-payment.list": listHandler("customer-payment"),
+  "customer-payment.get": getHandler("customer-payment"),
+  "inventory-item.list": listHandler("inventory-item"),
+  "inventory-item.get": getHandler("inventory-item"),
+
+  "sales-order.items.list": (input, context) => {
+    const session = open(context);
+    session.permit("TRAN_SALESORD", "view");
+    const { limit, offset } = paging(session, input);
+    const order = loadRecord(session, "sales-order", input.recordId);
+    const projection = projectionContext(session, true);
+    const entries = order.lines
+      .slice(offset, offset + limit)
+      .map((line) => projectLine("salesOrder", order.id, line, projection.items));
+    return collection(session, `${REC}/salesOrder/${order.id}/item`, entries, {
+      limit, offset, total: order.lines.length,
+    });
+  },
+
+  "subsidiary.list": (input, context) => {
+    const session = open(context);
+    session.permit("LIST_SUBSIDIARY", "view");
+    const { limit, offset } = paging(session, input);
+    const rows = session.rows("subsidiaries").filter((row) => session.inScope(row.id));
+    const index = new Map(rows.map((row) => [row.id, row]));
+    const entries = rows.slice(offset, offset + limit).map((row) => projectSubsidiary(row, index));
+    return collection(session, `${REC}/subsidiary`, entries, { limit, offset, total: rows.length });
+  },
+};

package/firedrill/tools/netsuite/lib/handlers-session.mjs

@@ -0,0 +1,52 @@
+// The signed-in context of one SuiteTalk session: account, employee, role, subsidiary scope and server time.
+// NetSuite exposes this to a browser session through the application shell rather than a REST resource, so this
+// operation carries no HTTP route; the browser app reads it to render the account/role chrome and the world clock.
+import { open, PERMISSION_LABELS } from "./session.mjs";
+
+const LEVELS = ["none", "view", "create", "edit", "full"];
+
+function permissionList(role) {
+  const entries = [];
+  for (const [name, label] of PERMISSION_LABELS) {
+    const granted = role.isAdmin === true
+      ? "full"
+      : (role.permissions !== undefined && Object.hasOwn(role.permissions, name) ? role.permissions[name] : "none");
+    entries.push({ name, label, level: LEVELS.includes(granted) ? granted : "none" });
+  }
+  return entries;
+}
+
+export const sessionOperations = {
+  "session.get": (input, context) => {
+    const session = open(context);
+    session.permit("SETUP_RECORD_METADATA", "view");
+    const account = session.account;
+    const employee = session.employee;
+    const scopeRow = session.scope === "0" ? null : session.get("subsidiaries", session.scope);
+    return {
+      account: {
+        accountId: account.accountId,
+        companyName: account.companyName,
+        baseCurrency: account.baseCurrency,
+        dateFormat: account.dateFormat,
+        isOneWorld: account.isOneWorld === true,
+      },
+      user: {
+        id: employee.id,
+        entityId: employee.entityId,
+        name: `${employee.firstName} ${employee.lastName}`,
+        email: employee.email,
+        title: employee.title,
+      },
+      role: {
+        id: session.role.id,
+        name: session.role.name,
+        isAdmin: session.role.isAdmin === true,
+        permissions: permissionList(session.role),
+      },
+      subsidiaryScope: session.scope === "0" ? { id: "0", refName: "All" } : { id: session.scope, refName: scopeRow === null ? session.scope : scopeRow.name },
+      serverTime: session.now,
+      accountDate: session.today,
+    };
+  },
+};

package/firedrill/tools/netsuite/lib/handlers-write.mjs

@@ -0,0 +1,6 @@
+// The nine write operations, grouped by record.
+import { customerWrites } from "./write-customer.mjs";
+import { orderWrites } from "./write-order.mjs";
+import { invoiceWrites } from "./write-invoice.mjs";
+
+export const writeOperations = { ...customerWrites, ...orderWrites, ...invoiceWrites };

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

@@ -0,0 +1,148 @@
+// Record-type metadata. The field table below mirrors this Tool's own state schemas and the `q` filter tables;
+// the response body is assembled from it on every call, never stored as a blob.
+import { FILTER_FIELDS } from "./collections.mjs";
+
+const string = (maxLength, extra = {}) => ({ type: "string", maxLength, ...extra });
+const number = (extra = {}) => ({ type: "number", ...extra });
+const boolean = () => ({ type: "boolean" });
+const reference = (recordType) => ({ type: "object", "x-ns-reference": recordType });
+const date = () => ({ type: "string", format: "date" });
+const timestamp = () => ({ type: "string", format: "date-time" });
+
+export const RECORD_TYPES = ["customer", "salesOrder", "invoice", "customerPayment", "inventoryItem", "subsidiary"];
+
+const FIELDS = {
+  customer: {
+    id: [string(15), "Internal ID", true],
+    entityId: [string(83), "Name", true],
+    companyName: [string(83), "Company Name", false],
+    isPerson: [boolean(), "Individual", true],
+    firstName: [string(32), "First Name", false],
+    middleName: [string(32), "Middle Name", false],
+    lastName: [string(32), "Last Name", false],
+    email: [string(254), "Email", false],
+    phone: [string(22), "Phone", false],
+    altPhone: [string(22), "Alt. Phone", false],
+    subsidiary: [reference("subsidiary"), "Subsidiary", true],
+    currency: [reference("currency"), "Primary Currency", false],
+    terms: [reference("term"), "Terms", false],
+    creditLimit: [number({ minimum: 0 }), "Credit Limit", false],
+    comments: [string(999), "Comments", false],
+    isInactive: [boolean(), "Inactive", true],
+    balance: [number(), "Balance", false],
+    unbilledOrders: [number(), "Unbilled Orders", false],
+    overdueBalance: [number(), "Overdue Balance", false],
+    dateCreated: [timestamp(), "Date Created", true],
+    lastModifiedDate: [timestamp(), "Last Modified", true],
+  },
+  salesOrder: {
+    id: [string(15), "Internal ID", true],
+    tranId: [string(45), "Document Number", true],
+    tranDate: [date(), "Date", true],
+    entity: [reference("customer"), "Customer", true],
+    subsidiary: [reference("subsidiary"), "Subsidiary", true],
+    status: [string(40, { enum: ["A", "B", "D", "E", "F", "G", "H"] }), "Status", true],
+    memo: [string(999), "Memo", false],
+    otherRefNum: [string(45), "PO/Check Number", false],
+    currency: [reference("currency"), "Currency", false],
+    terms: [reference("term"), "Terms", false],
+    subtotal: [number(), "Subtotal", false],
+    taxTotal: [number(), "Tax Total", false],
+    total: [number(), "Amount", true],
+    item: [{ type: "array", "x-ns-sublist": "item" }, "Items", false],
+  },
+  invoice: {
+    id: [string(15), "Internal ID", true],
+    tranId: [string(45), "Document Number", true],
+    tranDate: [date(), "Date", true],
+    dueDate: [date(), "Due Date", true],
+    entity: [reference("customer"), "Customer", true],
+    subsidiary: [reference("subsidiary"), "Subsidiary", true],
+    createdFrom: [reference("salesOrder"), "Created From", true],
+    status: [string(40, { enum: ["A", "B", "C", "V"] }), "Status", true],
+    memo: [string(999), "Memo", false],
+    currency: [reference("currency"), "Currency", false],
+    terms: [reference("term"), "Terms", false],
+    subtotal: [number(), "Subtotal", false],
+    taxTotal: [number(), "Tax Total", false],
+    total: [number(), "Amount", true],
+    amountPaid: [number(), "Amount Paid", false],
+    amountRemaining: [number(), "Amount Remaining", true],
+    item: [{ type: "array", "x-ns-sublist": "item" }, "Items", false],
+  },
+  customerPayment: {
+    id: [string(15), "Internal ID", true],
+    tranId: [string(45), "Document Number", true],
+    tranDate: [date(), "Date", true],
+    customer: [reference("customer"), "Customer", true],
+    subsidiary: [reference("subsidiary"), "Subsidiary", false],
+    payment: [number(), "Payment Amount", true],
+    unapplied: [number(), "Unapplied", false],
+    account: [reference("account"), "Account", false],
+    currency: [reference("currency"), "Currency", false],
+    status: [string(40, { enum: ["A", "B"] }), "Status", true],
+    apply: [{ type: "array", "x-ns-sublist": "apply" }, "Apply", false],
+  },
+  inventoryItem: {
+    id: [string(15), "Internal ID", true],
+    itemId: [string(60), "Item Name/Number", true],
+    displayName: [string(60), "Display Name", true],
+    description: [string(999), "Description", false],
+    basePrice: [number({ minimum: 0 }), "Base Price", true],
+    cost: [number({ minimum: 0 }), "Purchase Price", false],
+    quantityOnHand: [number({ minimum: 0 }), "Quantity On Hand", false],
+    incomeAccount: [reference("account"), "Income Account", false],
+    taxSchedule: [reference("taxSchedule"), "Tax Schedule", false],
+    subsidiary: [{ type: "array", "x-ns-sublist": "subsidiary" }, "Subsidiary", false],
+    isInactive: [boolean(), "Inactive", true],
+  },
+  subsidiary: {
+    id: [string(15), "Internal ID", true],
+    name: [string(120), "Name", true],
+    parent: [reference("subsidiary"), "Parent Subsidiary", false],
+    country: [string(2), "Country", false],
+    currency: [reference("currency"), "Currency", false],
+    isElimination: [boolean(), "Elimination", false],
+    isInactive: [boolean(), "Inactive", false],
+  },
+};
+
+const FILTER_KEY = {
+  customer: "customer",
+  salesOrder: "salesOrder",
+  invoice: "invoice",
+  customerPayment: "customerPayment",
+  inventoryItem: "inventoryItem",
+};
+
+/** The `application/schema+json`-shaped description of one record type. */
+export function describe(recordType, serverTime) {
+  const fields = FIELDS[recordType];
+  const filterable = FILTER_KEY[recordType] === undefined ? {} : FILTER_FIELDS[FILTER_KEY[recordType]];
+  const properties = {};
+  const required = [];
+  for (const [name, [schema, title, isRequired]] of Object.entries(fields)) {
+    properties[name] = { ...schema, title };
+    if (Object.hasOwn(filterable, name)) properties[name]["x-ns-filterable"] = true;
+    if (isRequired === true) required.push(name);
+  }
+  return {
+    "x-ns-type": recordType,
+    "x-ns-serverTime": serverTime,
+    type: "object",
+    properties,
+    required,
+  };
+}
+
+export function catalog(serverTime) {
+  return {
+    links: [{ rel: "self", href: "/services/rest/record/v1/metadata-catalog" }],
+    "x-ns-serverTime": serverTime,
+    items: RECORD_TYPES.map((name) => ({
+      name,
+      links: [{ rel: "canonical", href: `/services/rest/record/v1/metadata-catalog/${name}` }],
+    })),
+    totalResults: RECORD_TYPES.length,
+  };
+}

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

@@ -0,0 +1,105 @@
+// Deterministic primitives: internal ids, money, account-local dates and safe caller-key maps.
+import { fail } from "./errors.mjs";
+
+const ID_PATTERN = /^[1-9][0-9]{0,14}$/;
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+export const isInternalId = (value) => typeof value === "string" && ID_PATTERN.test(value);
+export const isUnsafeKey = (key) => UNSAFE_KEYS.has(key);
+
+/** A prototype-free map built from caller-chosen keys. */
+export function safeMap(entries) {
+  const map = new Map();
+  for (const [key, value] of entries) map.set(key, value);
+  return map;
+}
+
+/** Validate a caller-supplied path id before any state lookup. */
+export function requireId(context, value, label = "id") {
+  if (!isInternalId(value)) {
+    fail(context, "INVALID_ID", `Invalid value for the ${label} parameter. A NetSuite internal id is a positive integer.`);
+  }
+  return value;
+}
+
+export const round2 = (value) => Math.round((value + Number.EPSILON) * 100) / 100;
+export const round4 = (value) => Math.round((value + Number.EPSILON) * 10000) / 10000;
+export const cents = (value) => Math.round(value * 100);
+export const fromCents = (value) => round2(value / 100);
+
+const DAY_MS = 86400000;
+const pad = (value, width) => String(value).padStart(width, "0");
+
+/** Days since the Unix epoch for an account-local civil date. */
+export function dayNumber(year, month, day) {
+  return Math.floor(Date.UTC(year, month - 1, day) / DAY_MS);
+}
+
+export function civilFromDay(days) {
+  const date = new Date(days * DAY_MS);
+  return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate() };
+}
+
+/** Account-local ISO date (YYYY-MM-DD) for a virtual-time microsecond value at a fixed UTC offset. */
+export function accountDate(nowUs, offsetMinutes) {
+  const localMs = Math.floor(nowUs / 1000) + offsetMinutes * 60000;
+  const date = new Date(localMs);
+  return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
+}
+
+/** ISO-8601 UTC timestamp with a trailing Z, truncated to whole seconds. */
+export function timestamp(nowUs) {
+  const date = new Date(Math.floor(nowUs / 1000000) * 1000);
+  return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}T${pad(date.getUTCHours(), 2)}:${pad(date.getUTCMinutes(), 2)}:${pad(date.getUTCSeconds(), 2)}Z`;
+}
+
+const ISO_DATE = /^([0-9]{4})-([0-9]{2})-([0-9]{2})$/;
+const US_DATE = /^([0-9]{1,2})\/([0-9]{1,2})\/([0-9]{4})$/;
+
+/** Parse an account-local date literal (YYYY-MM-DD or M/D/YYYY). Returns null when unparsable. */
+export function parseDate(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  let year;
+  let month;
+  let day;
+  const iso = ISO_DATE.exec(text);
+  if (iso !== null) {
+    year = Number(iso[1]); month = Number(iso[2]); day = Number(iso[3]);
+  } else {
+    const us = US_DATE.exec(text);
+    if (us === null) return null;
+    month = Number(us[1]); day = Number(us[2]); year = Number(us[3]);
+  }
+  if (month < 1 || month > 12 || day < 1 || day > 31 || year < 1900 || year > 2999) return null;
+  const civil = civilFromDay(dayNumber(year, month, day));
+  if (civil.year !== year || civil.month !== month || civil.day !== day) return null;
+  return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
+}
+
+export const dateToDays = (iso) => {
+  const parts = ISO_DATE.exec(iso);
+  return parts === null ? null : dayNumber(Number(parts[1]), Number(parts[2]), Number(parts[3]));
+};
+
+export function addDays(iso, days) {
+  const base = dateToDays(iso);
+  if (base === null) return iso;
+  const civil = civilFromDay(base + days);
+  return `${pad(civil.year, 4)}-${pad(civil.month, 2)}-${pad(civil.day, 2)}`;
+}
+
+/** UTF-8 byte length of a string, computed from its code points (no Buffer in behavior modules). */
+export function utf8Length(text) {
+  let total = 0;
+  for (const character of text) {
+    const code = character.codePointAt(0);
+    if (code < 0x80) total += 1;
+    else if (code < 0x800) total += 2;
+    else if (code < 0x10000) total += 3;
+    else total += 4;
+  }
+  return total;
+}
+
+export const jsonBytes = (value) => utf8Length(JSON.stringify(value));