node-autotask 0.38.0 → 0.39.1

package/dist/{chunk-KPYXO7F5.js → chunk-LDTJNLX7.js}

@@ -30,10 +30,10 @@ import {
   unwrapItems,
   unwrapOperation,
   vendorId
-} from "./chunk-4QHGCYEI.js";
+} from "./chunk-LN3HQQBR.js";
 import {
   CAPABILITIES
-} from "./chunk-U3K6IDKB.js";
+} from "./chunk-GDSCYY2G.js";
 
 // src/resources/appointments.ts
 var AppointmentsResource = class extends BaseResource {

package/dist/{chunk-4QHGCYEI.js → chunk-LN3HQQBR.js}

@@ -1,6 +1,6 @@
 import {
   CAPABILITIES
-} from "./chunk-U3K6IDKB.js";
+} from "./chunk-GDSCYY2G.js";
 import {
   wrapUntrusted
 } from "./chunk-5VHSLJMR.js";
@@ -17878,7 +17878,8 @@ var WORKFLOW_RESOURCES = [
 // src/operations/fieldCatalog.ts
 var MAX_FIELD_CATALOG_WIRE = 60;
 var FIELD_CATALOG_HONESTY_NOTE = "Live field metadata reports the SHAPE of a field (existence, requiredness, type, maxLength, read-only, queryable, picklist-ness) as FLAGS and NAMES: picklist-ness as a flag (isPickList) and picklist field names (picklistFields). With the opt-in `labels: true`, picklist rows carry the vendor's exposed picklist VALUES (labels next to each value); without it the op serves no VALUES. It cannot resolve a picklist VALUE the vendor does not expose to this API user (the W-A4 wall \u2014 e.g. the attachments Type picklist): retrying the catalog will not surface a withheld value; that gap is vendor-side, not a client defect.";
-var FIELD_CATALOG_OPT_KEYS = ["resources", "include", "fresh", "fields", "labels"];
+var MIN_FIELD_CATALOG_MAX_BYTES = 4096;
+var FIELD_CATALOG_OPT_KEYS = ["resources", "include", "fresh", "fields", "labels", "compact", "maxBytes"];
 function projectFieldRow(raw, labels = false, udf = false) {
   const r = typeof raw === "object" && raw !== null ? raw : {};
   const name = typeof r.name === "string" ? r.name : "";
@@ -17905,6 +17906,16 @@ function projectFieldRow(raw, labels = false, udf = false) {
     ...values !== void 0 ? { picklistValues: values } : {}
   };
 }
+function compactFieldRow(f, udf, keepValues) {
+  return {
+    name: f.name,
+    type: f.type,
+    isPickList: f.isPickList,
+    isReference: f.referenceEntityType !== "",
+    udf,
+    ...keepValues && f.picklistValues !== void 0 ? { picklistValues: f.picklistValues } : {}
+  };
+}
 function isObjectOrArrayType(type) {
   const t = type.trim().toLowerCase();
   return t === "object" || t === "array" || t === "collection" || t.endsWith("[]");
@@ -17972,7 +17983,7 @@ function apiEntityFor(rec) {
 function validateCatalogOptsShape(opts) {
   if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
     throw new AutotaskConfigError(
-      "fieldCatalog: opts must be an object { resources?: string[], include?: (info|fields|udf)[], fresh?: boolean, fields?: string[], labels?: boolean }"
+      "fieldCatalog: opts must be an object { resources?: string[], include?: (info|fields|udf)[], fresh?: boolean, fields?: string[], labels?: boolean, compact?: boolean, maxBytes?: number }"
     );
   }
   for (const key of Object.keys(opts ?? {})) {
@@ -18061,6 +18072,61 @@ function resolveLabels(opts) {
   }
   return opts?.labels === true;
 }
+function resolveSizeOpts(opts) {
+  if (opts?.compact !== void 0 && typeof opts.compact !== "boolean") {
+    throw new AutotaskConfigError(`fieldCatalog: opts.compact must be a boolean (got ${typeof opts.compact})`);
+  }
+  const maxBytes = opts?.maxBytes;
+  if (maxBytes !== void 0 && (typeof maxBytes !== "number" || !Number.isInteger(maxBytes) || maxBytes < MIN_FIELD_CATALOG_MAX_BYTES)) {
+    throw new AutotaskConfigError(
+      `fieldCatalog: opts.maxBytes must be an integer >= ${MIN_FIELD_CATALOG_MAX_BYTES} (got ${String(maxBytes)})`
+    );
+  }
+  return { compact: opts?.compact === true, maxBytes };
+}
+var jsonBytes = (v) => Buffer.byteLength(JSON.stringify(v), "utf8");
+var TRIM_KINDS = ["udf", "fields", "picklistFields", "queryable", "readOnly", "required"];
+function applyMaxBytes(result, maxBytes) {
+  const fullBytes = jsonBytes(result);
+  if (fullBytes <= maxBytes) return;
+  result.truncated = true;
+  const omitted = /* @__PURE__ */ new Map();
+  const truncation = { reason: "maxBytes", maxBytes, fullBytes, omitted: [], note: "" };
+  result.truncation = truncation;
+  const lists = [];
+  for (const kind of TRIM_KINDS.slice(0, 2)) {
+    for (let i = result.rows.length - 1; i >= 0; i--) {
+      const row = result.rows[i];
+      if (Array.isArray(row[kind])) lists.push({ resource: row.resource, kind, list: row[kind] });
+    }
+  }
+  for (const kind of TRIM_KINDS.slice(2)) {
+    for (let i = result.rows.length - 1; i >= 0; i--) lists.push({ resource: result.rows[i].resource, kind, list: result.rows[i][kind] });
+  }
+  for (; ; ) {
+    truncation.omitted = [...omitted.values()];
+    const rowsDropped = truncation.omitted.filter((o) => o.kind === "fields" || o.kind === "udf").reduce((a, o) => a + o.count, 0);
+    const namesDropped = truncation.omitted.length > 0 && truncation.omitted.some((o) => o.kind !== "fields" && o.kind !== "udf");
+    truncation.note = `${rowsDropped} field row(s) omitted to fit maxBytes ${maxBytes} (the full result is ${fullBytes} bytes); ` + (namesDropped ? "the row name lists were trimmed as well (see omitted). " : "the row name lists (required, readOnly, queryable, picklistFields) still name every field. ") + `Narrow with fields: [...], ${result.compact ? "" : "use compact: true, "}or raise maxBytes.`;
+    let bytes = jsonBytes(result);
+    if (bytes <= maxBytes) return;
+    if (lists.every((l) => l.list.length === 0)) {
+      throw new AutotaskConfigError(
+        `fieldCatalog: maxBytes ${maxBytes} cannot hold this result: with every field row and name list dropped it is still ${bytes} bytes for ${result.rows.length} resource row(s); request fewer resources or raise maxBytes`
+      );
+    }
+    for (const { resource, kind, list } of lists) {
+      while (list.length > 0 && bytes > maxBytes) {
+        bytes -= jsonBytes(list.pop()) + 1;
+        const key = `${resource}:${kind}`;
+        const entry = omitted.get(key) ?? { resource, kind, count: 0 };
+        entry.count += 1;
+        omitted.set(key, entry);
+      }
+      if (bytes <= maxBytes) break;
+    }
+  }
+}
 function assertWithinWireCap(targetCount, kindCount) {
   const cost = targetCount * kindCount;
   if (cost > MAX_FIELD_CATALOG_WIRE) {
@@ -18142,11 +18208,16 @@ async function sweepResource(ctx, resource, tally) {
     }
   }
   row.cache = allCached ? { hit: true, age: ages.length > 0 ? Math.max(...ages) : 0 } : { hit: false, age: null };
+  if (ctx.compact) {
+    const keepValues = labels && fieldsFilter !== void 0;
+    if (row.fields !== void 0) row.fields = row.fields.map((f) => compactFieldRow(f, false, keepValues));
+    if (Array.isArray(row.udf)) row.udf = row.udf.map((f) => compactFieldRow(f, true, keepValues));
+  }
   const declared = derivedFieldsFor(resource);
   if (declared.length > 0) {
     const byField = new Map(declared.map((d) => [d.field, d]));
     row.derivedFields = declared;
-    for (const field of row.fields ?? []) {
+    for (const field of ctx.compact ? [] : row.fields ?? []) {
       const derivation = byField.get(field.name);
       if (derivation === void 0) continue;
       field.derived = {
@@ -18164,21 +18235,23 @@ async function fieldCatalog(client, opts) {
   const targets = resolveTargets(opts, fieldOps, allResources);
   const fieldsFilter = resolveFieldsFilter(opts);
   const labels = resolveLabels(opts);
+  const { compact, maxBytes } = resolveSizeOpts(opts);
   assertWithinWireCap(targets.length, include.length);
   const cache = client.http.fieldCache;
   const zone = client.config.zone ?? "unknown";
   const rows = [];
   const tally = { wireUsed: 0, anyPicklistValues: false };
-  const ctx = { client, include, fieldsFilter, labels, fresh: opts?.fresh === true, fieldOps, udfCapable };
+  const ctx = { client, include, fieldsFilter, labels, compact, fresh: opts?.fresh === true, fieldOps, udfCapable };
   for (const resource of targets) {
     const row = await sweepResource(ctx, resource, tally);
     if (row !== void 0) rows.push(row);
   }
-  return {
+  const result = {
     zone,
     label: zone,
     cached: cache !== void 0,
     labels,
+    compact,
     ttlMs: cache?.ttlMs ?? null,
     fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
     rows,
@@ -18196,6 +18269,8 @@ async function fieldCatalog(client, opts) {
       note: FIELD_CATALOG_HONESTY_NOTE
     }
   };
+  if (maxBytes !== void 0) applyMaxBytes(result, maxBytes);
+  return result;
 }
 
 // src/field-sets.ts
@@ -20455,6 +20530,7 @@ var BaseResource = class extends MutationBase {
 
 // src/operations/compositeNames.ts
 var PICKLIST_VALUE_NOT_SERVED_NOTE = "The picklist is served to this API user, but this record's value is not in it (an inactive or unexposed value) \u2014 the label cannot be resolved and is null; refreshing the field catalog will not surface it. (A picklist the vendor does not expose at all is reported with the field-catalog honesty note instead.)";
+var PICKLIST_CATALOG_UNAVAILABLE_NOTE = "The field-catalog read that serves picklist labels failed for this call, so this label is unavailable (null), not absent: the value may well have one. Retry the call once the catalog read succeeds (see names.catalogError).";
 var DEFAULT_MAX_NAME_READS = 20;
 var TICKET_LABEL_FIELDS = ["status", "priority", "ticketType", "issueType", "subIssueType", "source", "queueID"];
 function isVendorId(value) {
@@ -20765,7 +20841,7 @@ async function resolveCompositeNames(http, plan, opts = {}) {
       }
       const hit = values.find((v) => String(v.value) === String(value));
       if (hit === void 0) {
-        section.reasons[field] = PICKLIST_VALUE_NOT_SERVED_NOTE;
+        if (String(value) !== "0") section.reasons[field] = PICKLIST_VALUE_NOT_SERVED_NOTE;
         return null;
       }
       return typeof hit.label === "string" ? hit.label : null;
@@ -20786,6 +20862,7 @@ function untrustedName(name) {
   const [[capped]] = truncateNoteChars([{ v: name }], LABEL_NAME_MAX_CHARS, ["v"]);
   return wrapUntrusted(capped.v) ?? capped.v;
 }
+var lastPicklists = /* @__PURE__ */ new WeakMap();
 function readNamesOpt(value, where) {
   if (value === void 0) return true;
   if (typeof value !== "boolean") {
@@ -20794,19 +20871,35 @@ function readNamesOpt(value, where) {
   return value;
 }
 async function labelRows(client, resourceKey, rows) {
-  const present = /* @__PURE__ */ new Set();
-  for (const row of rows) for (const [k, v] of Object.entries(row)) if (v !== null && v !== void 0) present.add(k);
-  if (present.size === 0) return { rows: [...rows] };
+  const keys = /* @__PURE__ */ new Set();
+  for (const row of rows) for (const k of Object.keys(row)) keys.add(k);
+  if (keys.size === 0) return { rows: [...rows] };
   let picklistFields = [];
+  let unavailable = [];
+  let catalogError;
   const modelFields = MODEL_FIELD_SETS[resourceKey] ?? [];
-  const candidates = [...present].filter((f) => f !== "id" && modelFields.includes(f) && ROW_FK_TABLES[f] === void 0 && !isResourceFkField(f));
+  const candidates = [...keys].filter((f) => f !== "id" && modelFields.includes(f) && ROW_FK_TABLES[f] === void 0 && !isResourceFkField(f));
   if (candidates.length > 0) try {
     const catalog = await fieldCatalog(client, { resources: [resourceKey], labels: true });
-    const fields = catalog.rows.find((r) => r.resource === resourceKey)?.fields ?? [];
-    picklistFields = fields.filter((f) => f.isPickList && candidates.includes(f.name)).map((f) => f.name);
+    const row = catalog.rows.find((r) => r.resource === resourceKey);
+    const known = lastPicklists.get(client) ?? /* @__PURE__ */ new Map();
+    lastPicklists.set(client, known);
+    if (row?.fields === void 0) {
+      const last = known.get(resourceKey);
+      unavailable = (last ?? []).filter((f) => candidates.includes(f));
+      if (last === void 0 || unavailable.length > 0) {
+        catalogError = row?.error ?? { code: "INVALID_RESPONSE", message: `fieldCatalog: no ${resourceKey} row` };
+      }
+    } else {
+      const all = row.fields.filter((f) => f.isPickList).map((f) => f.name);
+      known.set(resourceKey, all);
+      picklistFields = all.filter((f) => candidates.includes(f));
+    }
   } catch (err) {
     if (!isAutotaskError(err) || err.code === "ABORTED") throw err;
   }
+  const labelled = (field) => picklistFields.includes(field) || unavailable.includes(field) || ROW_FK_TABLES[field] !== void 0 || isResourceFkField(field);
+  if (catalogError === void 0 && ![...keys].some(labelled)) return { rows: [...rows] };
   const builder = createNamePlan(picklistFields, resourceKey);
   for (const row of rows) {
     for (const [field, value] of Object.entries(row)) {
@@ -20817,29 +20910,43 @@ async function labelRows(client, resourceKey, rows) {
     }
   }
   const plan = builder.plan();
-  if (plan.resourceIds.length === 0 && plan.recordFks.length === 0 && picklistFields.length === 0) return { rows: [...rows] };
-  const names = await resolveCompositeNames(client.http, plan);
+  const names = plan.resourceIds.length === 0 && plan.recordFks.length === 0 && picklistFields.length === 0 ? void 0 : await resolveCompositeNames(client.http, plan);
   const out = rows.map((row) => {
     const r = { ...row };
     for (const [field, value] of Object.entries(row)) {
-      if (value === null || value === void 0 || value === 0 || value === "0") continue;
-      if (picklistFields.includes(field)) r[`${field}Label`] = names.labelFor(field, value);
+      const has2 = value !== null && value !== void 0 && names !== void 0;
+      if (picklistFields.includes(field)) r[`${field}Label`] = has2 ? names.labelFor(field, value) : null;
+      else if (unavailable.includes(field)) r[`${field}Label`] = null;
+      const set = has2 && value !== 0 && value !== "0";
       const table = ROW_FK_TABLES[field];
-      if (table !== void 0 && isVendorId(value)) r[`${field}Name`] = untrustedName(names.recordName(table, value));
-      else if (isResourceFkField(field) && isVendorId(value)) r[`${field}Name`] = untrustedName(names.resourceName(value));
+      if (table !== void 0) r[`${field}Name`] = set && isVendorId(value) ? untrustedName(names.recordName(table, value)) : null;
+      else if (isResourceFkField(field)) r[`${field}Name`] = set && isVendorId(value) ? untrustedName(names.resourceName(value)) : null;
     }
     if (r["assignedResourceIDName"] !== void 0) r["assignedResourceName"] = r["assignedResourceIDName"];
     return r;
   });
-  const capped = Object.values(names.section.rows).filter((row) => row.capped).length;
-  const reasons = names.section.reasons;
-  if (capped === 0 && Object.keys(reasons).length === 0) return { rows: out };
+  const capped = names === void 0 ? 0 : Object.values(names.section.rows).filter((row) => row.capped).length;
+  const unresolved = Object.keys(names?.section.reasons ?? {});
+  const reasons = { ...names?.section.reasons };
+  for (const f of unavailable) reasons[f] = PICKLIST_CATALOG_UNAVAILABLE_NOTE;
+  if (capped === 0 && unresolved.length === 0 && catalogError === void 0) return { rows: out };
   const parts = [];
   if (capped > 0) parts.push(`${capped} id(s) left unlabelled (their *Name is null): the per-call cap of ${DEFAULT_MAX_NAME_READS} uncached name reads was hit \u2014 names already read are cached, so repeating or narrowing the call labels more`);
-  if (Object.keys(reasons).length > 0) parts.push(`picklist label(s) unavailable for ${Object.keys(reasons).join(", ")} (see reasons)`);
+  if (unresolved.length > 0) parts.push(`picklist label(s) unavailable for ${unresolved.join(", ")} (see reasons)`);
+  if (catalogError !== void 0) {
+    parts.push(
+      `the ${resourceKey} field catalog read failed (${catalogError.code}), so picklist labels are unavailable for this call, not absent: ` + (unavailable.length > 0 ? `the *Label is null for ${unavailable.join(", ")}` : "no *Label sibling was added (the picklist fields are unknown until a catalog read succeeds)") + " \u2014 retry the call to label them"
+    );
+  }
   return {
     rows: out,
-    names: { truncated: capped > 0, capped, note: parts.join("; "), ...Object.keys(reasons).length > 0 ? { reasons } : {} }
+    names: {
+      truncated: capped > 0,
+      capped,
+      note: parts.join("; "),
+      ...Object.keys(reasons).length > 0 ? { reasons } : {},
+      ...catalogError !== void 0 ? { catalogError } : {}
+    }
   };
 }
 async function labelFetchResults(client, result) {
@@ -20858,11 +20965,13 @@ async function labelFetchResults(client, result) {
   }
   if (summaries.length === 0) return { ...result, results };
   const reasons = Object.assign({}, ...summaries.map((s) => s.reasons ?? {}));
+  const catalogError = summaries.find((s) => s.catalogError !== void 0)?.catalogError;
   const names = {
     truncated: summaries.some((s) => s.truncated),
     capped: summaries.reduce((n, s) => n + s.capped, 0),
     note: summaries.map((s) => s.note).join("; "),
-    ...Object.keys(reasons).length > 0 ? { reasons } : {}
+    ...Object.keys(reasons).length > 0 ? { reasons } : {},
+    ...catalogError !== void 0 ? { catalogError } : {}
   };
   return { ...result, results, names };
 }
@@ -26528,8 +26637,10 @@ export {
   WORKFLOW_RESOURCES,
   MAX_FIELD_CATALOG_WIRE,
   FIELD_CATALOG_HONESTY_NOTE,
+  MIN_FIELD_CATALOG_MAX_BYTES,
   fieldCatalog,
   PICKLIST_VALUE_NOT_SERVED_NOTE,
+  PICKLIST_CATALOG_UNAVAILABLE_NOTE,
   TICKET_LABEL_FIELDS,
   createNamePlan,
   addNameSibling,