@firedrill-tools/netsuite 0.1.2

package/firedrill/tools/netsuite/lib/wire-decode.mjs

@@ -0,0 +1,107 @@
+// Pure decoder helpers. Every property access is guarded, JSON bodies are depth-checked with an explicit stack,
+// and reserved property names are reported to the handler so the NetSuite envelope survives.
+const MAX_DEPTH = 512;
+const UNSAFE = new Set(["__proto__", "constructor", "prototype"]);
+
+export function firstQuery(request, name) {
+  const values = Object.hasOwn(request.query, name) ? request.query[name] : undefined;
+  return Array.isArray(values) && values.length > 0 ? values[0] : undefined;
+}
+
+export function firstHeader(request, name) {
+  const values = Object.hasOwn(request.headers, name) ? request.headers[name] : undefined;
+  return Array.isArray(values) && values.length > 0 ? values[0] : undefined;
+}
+
+export function pathValue(request, name) {
+  return Object.hasOwn(request.path, name) ? request.path[name] : undefined;
+}
+
+/** Decode one path segment; a mangled percent-encoding is returned unchanged so the handler can reject it. */
+export function decodeSegment(value) {
+  if (typeof value !== "string") return value;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+const list = (value) => (typeof value === "string" && value.length > 0
+  ? value.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0)
+  : undefined);
+
+/** Query parameters shared by the read routes. */
+export function readArguments(request) {
+  const args = {};
+  for (const name of ["q", "limit", "offset", "expandSubResources", "simpleEnumFormat"]) {
+    const value = firstQuery(request, name);
+    if (value !== undefined) args[name] = value;
+  }
+  const fields = list(firstQuery(request, "fields"));
+  if (fields !== undefined) args.fields = fields;
+  return args;
+}
+
+/** Headers shared by the write routes. */
+export function writeArguments(request) {
+  const args = {};
+  const key = firstHeader(request, "x-netsuite-idempotency-key");
+  if (key !== undefined) args.idempotencyKeyHeader = key;
+  const validation = firstHeader(request, "x-netsuite-propertynamevalidation");
+  if (validation === "ignore" || validation === "warning" || validation === "error") {
+    args.propertyNameValidation = validation;
+  }
+  const ifMatch = firstHeader(request, "if-match");
+  if (ifMatch !== undefined) args.ifMatchVersion = ifMatch;
+  const replace = list(firstQuery(request, "replace"));
+  if (replace !== undefined) args.replace = replace;
+  return args;
+}
+
+/** Depth and reserved-name check over a decoded JSON value, with an explicit stack. */
+function inspect(value) {
+  const stack = [{ node: value, depth: 1 }];
+  while (stack.length > 0) {
+    const entry = stack.pop();
+    if (entry.depth > MAX_DEPTH) return "depth";
+    const node = entry.node;
+    if (Array.isArray(node)) {
+      for (const child of node) {
+        if (typeof child === "object" && child !== null) stack.push({ node: child, depth: entry.depth + 1 });
+      }
+      continue;
+    }
+    if (typeof node !== "object" || node === null) continue;
+    for (const key of Object.keys(node)) {
+      if (UNSAFE.has(key)) return "prototype";
+      const child = node[key];
+      if (typeof child === "object" && child !== null) stack.push({ node: child, depth: entry.depth + 1 });
+    }
+  }
+  return null;
+}
+
+/**
+ * Decode a JSON request body. `body` is always present so the operation's strict input schema is satisfied;
+ * a shape problem travels as `bodyError`, which the handler turns into INVALID_REQUEST with NetSuite's envelope.
+ */
+export function bodyArguments(request, { optional = true } = {}) {
+  const body = request.body;
+  if (body === undefined || body.kind === "none") {
+    return optional ? { body: {} } : { body: {}, bodyError: "not-json" };
+  }
+  if (body.kind !== "json") return { body: {}, bodyError: "not-json" };
+  const value = body.value;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { body: {}, bodyError: "not-json" };
+  }
+  const problem = inspect(value);
+  if (problem !== null) return { body: {}, bodyError: problem };
+  return { body: value };
+}
+
+export const ACCOUNT_CONTENT_TYPE = "application/vnd.oracle.resource+json; type=singular";
+export const COLLECTION_CONTENT_TYPE = "application/vnd.oracle.resource+json; type=collection";
+export const ERROR_CONTENT_TYPE = "application/vnd.oracle.resource+json; type=error";
+export const SCHEMA_CONTENT_TYPE = "application/schema+json";

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

@@ -0,0 +1,228 @@
+// Provider-shaped HTTP codecs. Pure: no state is read here and every response body is assembled from the
+// operation outcome alone.
+import { problemBody } from "./errors.mjs";
+import { selfLinks } from "./project.mjs";
+import {
+  ACCOUNT_CONTENT_TYPE, bodyArguments, COLLECTION_CONTENT_TYPE, decodeSegment, ERROR_CONTENT_TYPE,
+  firstHeader, firstQuery, pathValue, readArguments, SCHEMA_CONTENT_TYPE, writeArguments,
+} from "./wire-decode.mjs";
+
+// Framework-raised codes (they never reach a handler) that still have an exact NetSuite equivalent.
+// Keyed by the outcome status the framework reports, so the NetSuite code always agrees with the HTTP status
+// the framework puts on the wire (invalid -> 400, denied -> 403, unsupported -> 404) whatever the internal code is.
+const FRAMEWORK_CODES = new Map([
+  ["invalid", "INVALID_PARAMETER"],
+  ["denied", "INSUFFICIENT_PERMISSION"],
+  ["unsupported", "NONEXISTENT_ID"],
+]);
+
+const DENIED_DETAIL =
+  "Permission Violation: You need a higher level of permission to access this record. Please contact your account administrator.";
+
+// Caller-safe wording for each framework code; framework messages name internal identifiers, so none is quoted.
+const FRAMEWORK_DETAIL = new Map([
+  ["INSUFFICIENT_PERMISSION", DENIED_DETAIL],
+  ["INVALID_PARAMETER", "Invalid request parameter value. One of the supplied parameters is not valid for this request."],
+  ["NONEXISTENT_ID", "The requested record operation is not available in this account."],
+  ["UNEXPECTED_ERROR", "Unexpected error."],
+]);
+
+const codeOf = (outcome) => {
+  const code = outcome?.error?.code;
+  if (typeof code === "string" && code.startsWith("tool.")) return code.slice(5);
+  return FRAMEWORK_CODES.get(outcome?.status) ?? "UNEXPECTED_ERROR";
+};
+
+/** True when the outcome carries a framework code, whose message is internal wording we must not quote. */
+const isFrameworkError = (outcome) => {
+  const code = outcome?.error?.code;
+  return typeof code !== "string" || !code.startsWith("tool.");
+};
+
+const detailsOf = (outcome) => {
+  const details = outcome?.error?.details;
+  return typeof details === "object" && details !== null && !Array.isArray(details) ? details : {};
+};
+
+function errorBody(outcome) {
+  const code = codeOf(outcome);
+  if (isFrameworkError(outcome)) {
+    // Framework messages name internal identifiers, so they are never quoted into a provider-shaped body.
+    return problemBody(code, FRAMEWORK_DETAIL.get(code) ?? "Unexpected error.", {});
+  }
+  const details = detailsOf(outcome);
+  const detail = typeof details.detail === "string" ? details.detail : (outcome?.error?.message ?? "Request failed.");
+  return problemBody(code, detail, details);
+}
+
+const errorResponse = (outcome) => ({
+  headers: {
+    "content-type": ERROR_CONTENT_TYPE,
+    ...(codeOf(outcome) === "CONCURRENCY_LIMIT_EXCEEDED" ? { "retry-after": "5" } : {}),
+  },
+  body: { kind: "json", value: errorBody(outcome) },
+});
+
+const okObject = (outcome) => {
+  const value = outcome?.value;
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+};
+
+/** 200 responses carrying a record or a collection. */
+function jsonCodec(contentType, transform = (value) => value) {
+  return ({ outcome }) => {
+    const value = okObject(outcome);
+    if (value === null) return errorResponse(outcome);
+    return { headers: { "content-type": contentType }, body: { kind: "json", value: transform(value) } };
+  };
+}
+
+/** 204 responses: no body, a Location header naming the record that was written. */
+const writeCodec = ({ outcome }) => {
+  const value = okObject(outcome);
+  if (value === null) return errorResponse(outcome);
+  const location = typeof value.location === "string" ? value.location : undefined;
+  return {
+    headers: location === undefined ? {} : { location },
+    body: { kind: "empty" },
+  };
+};
+
+const recordCodec = jsonCodec(ACCOUNT_CONTENT_TYPE);
+const collectionCodec = jsonCodec(COLLECTION_CONTENT_TYPE);
+
+/** The REST subsidiary route answers the record-collection shape, not the MCP shape. */
+const subsidiaryCollectionCodec = jsonCodec(COLLECTION_CONTENT_TYPE, (value) => ({
+  ...value,
+  items: Array.isArray(value.items)
+    ? value.items.map((entry) => ({ links: selfLinks("subsidiary", entry?.id ?? ""), id: entry?.id ?? "" }))
+    : [],
+}));
+
+const idArguments = (request) => ({ recordId: decodeSegment(pathValue(request, "id")) ?? "" });
+
+const listRoute = (id) => [id, { decode: (request) => ({ arguments: readArguments(request) }), encode: collectionCodec }];
+
+const getRoute = (id) => [id, {
+  decode: (request) => ({ arguments: { ...readArguments(request), ...idArguments(request) } }),
+  encode: recordCodec,
+}];
+
+const createRoute = (id) => [id, {
+  decode: (request) => {
+    const write = writeArguments(request);
+    return {
+      arguments: { ...write, ...bodyArguments(request, { optional: false }) },
+      ...(write.idempotencyKeyHeader === undefined ? {} : { idempotencyKey: write.idempotencyKeyHeader }),
+    };
+  },
+  encode: writeCodec,
+}];
+
+const updateRoute = (id) => [id, {
+  decode: (request) => {
+    const write = writeArguments(request);
+    return {
+      arguments: { ...write, ...idArguments(request), ...bodyArguments(request, { optional: false }) },
+      ...(write.idempotencyKeyHeader === undefined ? {} : { idempotencyKey: write.idempotencyKeyHeader }),
+    };
+  },
+  encode: writeCodec,
+}];
+
+const transformRoute = (id, target) => [id, {
+  decode: (request) => {
+    const write = writeArguments(request);
+    return {
+      arguments: {
+        ...write,
+        ...idArguments(request),
+        target,
+        transformMarker: decodeSegment(pathValue(request, "transformMarker")) ?? "",
+        ...bodyArguments(request, { optional: true }),
+      },
+      ...(write.idempotencyKeyHeader === undefined ? {} : { idempotencyKey: write.idempotencyKeyHeader }),
+    };
+  },
+  encode: writeCodec,
+}];
+
+export const routes = Object.fromEntries([
+  listRoute("customer-list"),
+  getRoute("customer-get"),
+  createRoute("customer-create"),
+  updateRoute("customer-update"),
+  ["customer-delete", {
+    decode: (request) => {
+      const write = writeArguments(request);
+      return {
+        arguments: { ...idArguments(request), ...(write.idempotencyKeyHeader === undefined ? {} : { idempotencyKeyHeader: write.idempotencyKeyHeader }) },
+        ...(write.idempotencyKeyHeader === undefined ? {} : { idempotencyKey: write.idempotencyKeyHeader }),
+      };
+    },
+    encode: writeCodec,
+  }],
+  listRoute("sales-order-list"),
+  getRoute("sales-order-get"),
+  createRoute("sales-order-create"),
+  updateRoute("sales-order-update"),
+  ["sales-order-items", {
+    decode: (request) => ({
+      arguments: {
+        ...idArguments(request),
+        ...(firstQuery(request, "limit") === undefined ? {} : { limit: firstQuery(request, "limit") }),
+        ...(firstQuery(request, "offset") === undefined ? {} : { offset: firstQuery(request, "offset") }),
+      },
+    }),
+    encode: collectionCodec,
+  }],
+  transformRoute("sales-order-transform", "invoice"),
+  listRoute("invoice-list"),
+  getRoute("invoice-get"),
+  createRoute("invoice-create"),
+  updateRoute("invoice-update"),
+  transformRoute("invoice-transform", "customerPayment"),
+  listRoute("customer-payment-list"),
+  getRoute("customer-payment-get"),
+  listRoute("inventory-item-list"),
+  getRoute("inventory-item-get"),
+  ["subsidiary-list", {
+    decode: (request) => ({
+      arguments: {
+        ...(firstQuery(request, "limit") === undefined ? {} : { limit: firstQuery(request, "limit") }),
+        ...(firstQuery(request, "offset") === undefined ? {} : { offset: firstQuery(request, "offset") }),
+      },
+    }),
+    encode: subsidiaryCollectionCodec,
+  }],
+  ["metadata-catalog-list", {
+    decode: () => ({ arguments: {} }),
+    encode: jsonCodec(COLLECTION_CONTENT_TYPE),
+  }],
+  ["metadata-catalog-type", {
+    decode: (request) => ({ arguments: { recordType: decodeSegment(pathValue(request, "recordType")) ?? "" } }),
+    encode: jsonCodec(SCHEMA_CONTENT_TYPE),
+  }],
+  ["suiteql", {
+    decode: (request) => {
+      const decoded = bodyArguments(request, { optional: false });
+      const args = { ...decoded };
+      if (decoded.body !== undefined) {
+        const body = decoded.body;
+        delete args.body;
+        args.q = typeof body.q === "string" ? body.q : "";
+        if (Array.isArray(body.params)) args.params = body.params;
+      } else if (decoded.bodyError === undefined) {
+        args.q = "";
+      }
+      const prefer = firstHeader(request, "prefer");
+      if (prefer !== undefined) args.prefer = prefer;
+      const limit = firstQuery(request, "limit");
+      if (limit !== undefined) args.limit = limit;
+      const offset = firstQuery(request, "offset");
+      if (offset !== undefined) args.offset = offset;
+      return { arguments: args };
+    },
+    encode: collectionCodec,
+  }],
+]);

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

@@ -0,0 +1,181 @@
+// Customer writes: create, merge-patch update and the referential delete.
+import { quote } from "./errors.mjs";
+import { open } from "./session.mjs";
+import { loadRecord } from "./handlers-read.mjs";
+import {
+  booleanField, checkPropertyNames, checkVersion, idempotencyKey, numberField,
+  referenceField, replaceList, requestBody, stringField,
+} from "./body.mjs";
+
+const KNOWN = new Set([
+  "entityId", "companyName", "isPerson", "firstName", "middleName", "lastName", "email", "phone",
+  "altPhone", "subsidiary", "currency", "terms", "creditLimit", "comments", "isInactive", "categoryId",
+]);
+const REPLACEABLE = new Set(["companyName", "email", "phone", "altPhone", "comments", "creditLimit", "terms", "addressBook"]);
+const CURRENCY_FOR = new Map([["1", "1"], ["2", "3"]]);
+
+function readFields(session, input, body) {
+  checkPropertyNames(session, input, body, KNOWN);
+  return {
+    entityId: stringField(session, body, "entityId", 83),
+    companyName: stringField(session, body, "companyName", 83),
+    isPerson: booleanField(session, body, "isPerson"),
+    firstName: stringField(session, body, "firstName", 32),
+    middleName: stringField(session, body, "middleName", 32),
+    lastName: stringField(session, body, "lastName", 32),
+    email: stringField(session, body, "email", 254),
+    phone: stringField(session, body, "phone", 22),
+    altPhone: stringField(session, body, "altPhone", 22),
+    comments: stringField(session, body, "comments", 999),
+    creditLimit: numberField(session, body, "creditLimit", { min: 0, max: 1000000000 }),
+    isInactive: booleanField(session, body, "isInactive"),
+    subsidiaryId: referenceField(session, body, "subsidiary"),
+    termsId: referenceField(session, body, "terms"),
+  };
+}
+
+function resolveSubsidiary(session, subsidiaryId) {
+  const id = subsidiaryId ?? session.account.defaultSubsidiaryId;
+  if (session.get("subsidiaries", id) === null) {
+    session.fail("INVALID_KEY_OR_REF", `Invalid subsidiary reference key ${quote(String(id))}.`, { errorPath: "subsidiary" });
+  }
+  if (!session.inScope(id)) {
+    session.fail("INVALID_KEY_OR_REF", `Subsidiary ${quote(String(id))} is outside the subsidiary restriction of this role.`, {
+      errorPath: "subsidiary",
+    });
+  }
+  return id;
+}
+
+function checkTerms(session, termsId) {
+  if (termsId === undefined || termsId === null) return termsId ?? null;
+  if (!["1", "2", "3"].includes(termsId)) {
+    session.fail("INVALID_KEY_OR_REF", `Invalid terms reference key ${quote(termsId)}.`, { errorPath: "terms" });
+  }
+  return termsId;
+}
+
+function checkDuplicate(session, entityId, ownId) {
+  for (const row of session.rows("customers")) {
+    if (row.id !== ownId && row.entityId.toLowerCase() === entityId.toLowerCase()) {
+      session.fail("USER_ERROR", `This entity already exists. The name ${quote(entityId)} is already in use by another customer.`, {
+        errorPath: "entityId",
+      });
+    }
+  }
+}
+
+export const customerWrites = {
+  "customer.create": (input, context) => {
+    const session = open(context);
+    session.permit("LIST_CUSTJOB", "create");
+    idempotencyKey(session, input);
+    const body = requestBody(session, input);
+    const fields = readFields(session, input, body);
+    session.rows("customers");
+    const subsidiaryId = resolveSubsidiary(session, fields.subsidiaryId);
+    const termsId = checkTerms(session, fields.termsId);
+    const isPerson = fields.isPerson === true;
+    const displayName = isPerson
+      ? `${fields.lastName ?? ""}${fields.lastName !== undefined && fields.firstName !== undefined ? ", " : ""}${fields.firstName ?? ""}`.trim()
+      : (fields.companyName ?? "").trim();
+    if (displayName.length === 0) {
+      session.fail("USER_ERROR", "Please enter a value for Company Name, or a first and last name for an individual customer.", {
+        errorPath: isPerson ? "lastName" : "companyName",
+      });
+    }
+    const id = session.nextId("nextEntityId", "customers");
+    const entityId = (fields.entityId ?? `C${id} ${displayName}`).slice(0, 83);
+    checkDuplicate(session, entityId, null);
+    const row = {
+      id,
+      entityId,
+      companyName: isPerson ? (fields.companyName ?? null) : displayName,
+      isPerson,
+      firstName: fields.firstName ?? null,
+      lastName: fields.lastName ?? null,
+      middleName: fields.middleName ?? null,
+      email: fields.email ?? null,
+      phone: fields.phone ?? null,
+      altPhone: fields.altPhone ?? null,
+      subsidiaryId,
+      currencyId: CURRENCY_FOR.get(subsidiaryId) ?? "1",
+      termsId,
+      creditLimit: fields.creditLimit ?? null,
+      comments: fields.comments ?? null,
+      isInactive: fields.isInactive === true,
+      categoryId: null,
+      defaultAddress: null,
+      addressBook: [],
+      dateCreated: session.now,
+      createdDate: session.now,
+      lastModifiedDate: session.now,
+      createdById: session.employee.id,
+      lastModifiedById: session.employee.id,
+      version: 1,
+    };
+    session.put("customers", id, row);
+    session.recordChanged("customer", id, "CREATE", subsidiaryId);
+    return { id, location: `/services/rest/record/v1/customer/${id}` };
+  },
+
+  "customer.update": (input, context) => {
+    const session = open(context);
+    session.permit("LIST_CUSTJOB", "edit");
+    idempotencyKey(session, input);
+    const body = requestBody(session, input);
+    const replace = replaceList(session, input, REPLACEABLE);
+    const current = loadRecord(session, "customer", input.recordId);
+    checkVersion(session, input, current);
+    const fields = readFields(session, input, body);
+    session.rows("customers");
+    const updated = { ...current };
+    for (const name of replace) {
+      if (name === "addressBook") {
+        updated.addressBook = [];
+        updated.defaultAddress = null;
+      } else if (name === "terms") updated.termsId = null;
+      else updated[name] = null;
+    }
+    for (const [key, value] of [
+      ["companyName", fields.companyName], ["firstName", fields.firstName], ["middleName", fields.middleName],
+      ["lastName", fields.lastName], ["email", fields.email], ["phone", fields.phone], ["altPhone", fields.altPhone],
+      ["comments", fields.comments], ["creditLimit", fields.creditLimit],
+    ]) {
+      if (value !== undefined) updated[key] = value;
+    }
+    if (fields.isInactive !== undefined && fields.isInactive !== null) updated.isInactive = fields.isInactive;
+    if (fields.isPerson !== undefined && fields.isPerson !== null) updated.isPerson = fields.isPerson;
+    if (fields.termsId !== undefined) updated.termsId = checkTerms(session, fields.termsId);
+    if (fields.subsidiaryId !== undefined && fields.subsidiaryId !== null) {
+      updated.subsidiaryId = resolveSubsidiary(session, fields.subsidiaryId);
+      updated.currencyId = CURRENCY_FOR.get(updated.subsidiaryId) ?? "1";
+    }
+    if (fields.entityId !== undefined && fields.entityId !== null) updated.entityId = fields.entityId;
+    checkDuplicate(session, updated.entityId, current.id);
+    updated.lastModifiedDate = session.now;
+    updated.lastModifiedById = session.employee.id;
+    updated.version = current.version + 1;
+    session.put("customers", current.id, updated);
+    session.recordChanged("customer", current.id, "UPDATE", updated.subsidiaryId);
+    return { id: current.id, location: `/services/rest/record/v1/customer/${current.id}` };
+  },
+
+  "customer.delete": (input, context) => {
+    const session = open(context);
+    session.permit("LIST_CUSTJOB", "full");
+    idempotencyKey(session, input);
+    const current = loadRecord(session, "customer", input.recordId);
+    const referenced = [
+      ...session.rows("sales-orders"),
+      ...session.rows("invoices"),
+      ...session.rows("customer-payments"),
+    ].some((row) => row.entityId === current.id);
+    if (referenced) {
+      session.fail("USER_ERROR", "This record cannot be deleted because it is referenced by one or more transactions.");
+    }
+    session.remove("customers", current.id);
+    session.recordChanged("customer", current.id, "DELETE", current.subsidiaryId);
+    return { id: current.id };
+  },
+};