node-autotask 0.39.1 → 0.39.3

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.39.3] - 2026-10-30
+
+Patch: standalone fixes (#263, #264, #265, #266, #306 part a). No capability-plan change.
+
+### Fixed
+- **#264:** `credentialShapeProblem` now reports an interior line feed (`'line feed'`), matching its "interior CR/LF always reported" doc; previously an LF-laden credential reached fetch and surfaced as an opaque `NETWORK_ERROR`.
+- **#265:** `createIfNotExists` treats a dedup match with an all-digit string id (above 2^53) as existing, and the create dry-run `parent-exists` check accepts a string-id parent; both go through `parseIdentifier`.
+- **#263:** a mutation sent with `idempotent: true` (for example `client.http.request`) now voids cached reads like any other write. `idempotent` governs retry only; the internal `/query`, `/query/count` and `/query/next` read POSTs still skip invalidation.
+- **#306 (a):** the picklist-unavailable note now names the resource (`... unavailable for tickets.status (see reasons)`), matching the `<resource>.<field>` `reasons` keys; the `resolveCompositeNames` catch branch is covered by a test.
+
+### Changed
+- **#266 / #306 (a):** docs only. Pagination module headers now state that same-origin cursors are used and cross-origin cursors are refused with `ResponseRejectedError` (issue #54); the API.md note on id 0 is reworded as a node rule, not a vendor claim.
+
+## [0.39.2] - 2026-10-30
+
+Patch: follow-ups to the 0.39.0 / 0.39.1 label work (#302, #303, #304). The plan hash is unchanged (`9bb87de7...`); no capability-plan change, so the MCP server needs no re-pin.
+
+### Fixed
+- **#302: `fetchMany` / `fetchByIds` names merge.** `names.reasons` is keyed `<resource>.<field>` (`tickets.status`, `contracts.status`), so two resources sharing a field name no longer overwrite each other's reason. **Consumer-visible:** this applies to every `fetchMany` / `fetchByIds` result, including one whose items all name a single resource, so a reader of `names.reasons.status` now reads `names.reasons['tickets.status']`. Every failing resource's catalog error is kept in the new `names.catalogErrors` (keyed by resource); `names.catalogError` stays and is the first of them. The single-resource operations (`<resource>.query`, `aggregate`) are unchanged: `reasons` is still keyed by field.
+- **#303: composite name paths no longer read a foreign-key id of 0.** The full-context composites (`tickets.fullContext`, `companies.fullProfile`, ...) planned a read for `contractID: 0` and the like; 0 is the vendor's "no reference", so the sibling is `null` with no read, as on the row path.
+- **#304: a failed field-catalog read is no longer reported as "retrying will not help".** On the composite path (and on the row path when the second, field-filtered catalog read fails after the first succeeded) the picklist labels are `null` with `PICKLIST_CATALOG_UNAVAILABLE_NOTE` and the section / `names` carries `catalogError`. The "retrying will not help" honesty note (`FIELD_CATALOG_HONESTY_NOTE`) is now served only for a picklist the vendor does not serve. The pinned composite reasons moved accordingly (new optional `catalogError` on the composite `names` section).
+
+### Changed
+- **#303: 0.39.0 -> 0.39.1 behaviour note.** A value of 0 on a picklist whose values the vendor does not serve now gets a reason row (the honesty note); 0.39.0 gave none. A 0 on a picklist that IS served but does not define 0 still gets no reason row: the SDK treats a 0 absent from the picklist as "none". A defined 0 that the vendor hides from the API user therefore reads as `null` with no reason; the SDK cannot tell the two apart.
+- **#303: `docs/API.md` §11.27 response-size figure** now uses the live measurement (31 siblings per row, 341,178 B -> 477,325 B, +40%) instead of "~50%, 19 siblings".
+
 ## [0.39.1] - Unreleased
 
 Patch: label follow-ups from QA of #283. The plan hash is unchanged (`9bb87de7...`); only registry text in `capabilities.json` moved, so the MCP server needs no plan re-pin.

package/README.md

@@ -120,7 +120,7 @@ code `INVALID_CREDENTIAL_SHAPE`) **before any request is built**. The three cano
 `AUTOTASK_API_INTEGRATION_CODE` and `AUTOTASK_USER` are read as fall-backs, canonical first.
 
 **What the SDK refuses at construction.** `apiIntegrationCode`, `userName`, `secret` and
-`impersonationResourceId` reject a value with a surrounding quote pair or an interior CR (and refuse
+`impersonationResourceId` reject a value with a surrounding quote pair or an interior CR or LF (and refuse
 whitespace-only blank values exactly as before); padding-only whitespace is still trimmed as it
 always was. The same gate runs at the wire boundary, so a value that reaches the transport by any
 other route is refused before the request is sent. Errors are value-free: they name the field and

package/dist/{chunk-CQXB7KAO.js → chunk-5JAS6CAN.js}

@@ -125,7 +125,7 @@ import {
   VersionInformationResource,
   VersionResource,
   ZoneInformationResource
-} from "./chunk-LDTJNLX7.js";
+} from "./chunk-K6RZDRWX.js";
 import {
   AutotaskConfigError,
   BillingCodesResource,
@@ -141,7 +141,7 @@ import {
   TimeEntriesResource,
   resolveConfig,
   runWithSignal
-} from "./chunk-LN3HQQBR.js";
+} from "./chunk-GSMFRPYB.js";
 
 // src/client.ts
 var AutotaskClient = class {

package/dist/{chunk-LB34VFQY.cjs → chunk-BPRDYT5L.cjs}

@@ -1095,6 +1095,7 @@ function credentialShapeProblem(value, options = {}) {
     return "single- or double-quote surrounding the value";
   }
   if (value.includes("\r")) return "carriage return";
+  if (value.includes("\n")) return "line feed";
   return void 0;
 }
 var CREDENTIAL_ENV_LOAD_ACTION = "value appears shell-quoted or line-break contaminated \u2014 check how your env file was loaded (single-quoted values must be shell-sourced, not parsed by a quote-preserving loader)";
@@ -17469,7 +17470,7 @@ var HttpClient = class {
   }
   /** A real write (even a failed one — it may have partly applied) voids cached reads. */
   invalidateAfterWrite(opts) {
-    if (opts.method === "GET" || opts.idempotent === true) return;
+    if (opts.method === "GET" || opts.idempotent === true && /\/query(\/|\?|$)/.test(opts.path)) return;
     _optionalChain([this, 'access', _120 => _120.readCache, 'optionalAccess', _121 => _121.clear, 'call', _122 => _122()]);
     this.latestCountCache.clear();
     const nameOp = typeof opts.operation === "string" ? opts.operation : void 0;
@@ -20281,9 +20282,9 @@ var MutationBase = class extends MetaBase {
       const first = matches[0];
       if (first !== void 0) {
         const firstId = first.id;
-        if (typeof firstId === "number") {
+        if (isIdentifierCandidate(firstId)) {
           existing = first;
-          existingId = firstId;
+          existingId = parseIdentifier(firstId, "id");
         }
       }
     }
@@ -20382,9 +20383,13 @@ var MutationBase = class extends MetaBase {
         );
       }
       let parent = null;
-      if (typeof parentId === "number" && Number.isInteger(parentId) && parentId >= 0) {
+      if (isIdentifierCandidate(parentId)) {
         try {
-          parent = await this.fetchRecordRaw(parentPath, parentId, true);
+          parent = await this.fetchRecordRaw(
+            parentPath,
+            parseIdentifier(parentId, "parentId"),
+            true
+          );
         } catch (err) {
           if (!(err instanceof NotFoundError)) throw err;
         }
@@ -20557,7 +20562,7 @@ function createNamePlan(labelFields = [], labelResource) {
       ...lineOfBusinessContractId !== void 0 ? { lineOfBusinessContractId } : {}
     }),
     addResource: (value) => {
-      if (!isVendorId(value)) return;
+      if (!isVendorId(value) || Number(value) === 0) return;
       const k = String(value);
       if (!resSeen.has(k)) {
         resSeen.add(k);
@@ -20565,7 +20570,7 @@ function createNamePlan(labelFields = [], labelResource) {
       }
     },
     addFk: (table, value) => {
-      if (!isVendorId(value)) return;
+      if (!isVendorId(value) || Number(value) === 0) return;
       const k = `${table}:${String(value)}`;
       if (!fkSeen.has(k)) {
         fkSeen.add(k);
@@ -20787,23 +20792,30 @@ async function resolveCompositeNames(http, plan, opts = {}) {
   const picklists = {};
   if (plan.labelFields.length > 0) {
     let usable = true;
+    let failure;
     try {
       const labelResource = _nullishCoalesce(plan.labelResource, () => ( "tickets"));
       const catalog = await fieldCatalog(client, { resources: [labelResource], labels: true, fields: [...plan.labelFields] });
       const row = catalog.rows.find((r) => r.resource === labelResource);
       if (row === void 0 || row.error !== null || row.fields === void 0) {
         usable = false;
+        failure = _nullishCoalesce(_optionalChain([row, 'optionalAccess', _197 => _197.error]), () => ( { code: "INVALID_RESPONSE", message: `fieldCatalog: no ${labelResource} row` }));
       } else {
         for (const f of plan.labelFields) {
           const frow = row.fields.find((x) => x.name === f);
-          picklists[f] = _optionalChain([frow, 'optionalAccess', _197 => _197.picklistValues]);
+          picklists[f] = _optionalChain([frow, 'optionalAccess', _198 => _198.picklistValues]);
         }
       }
     } catch (err) {
-      if (isAutotaskError(err) && err.code !== "ABORTED") usable = false;
-      else throw err;
+      if (isAutotaskError(err) && err.code !== "ABORTED") {
+        usable = false;
+        failure = { code: err.code, message: err.message };
+      } else throw err;
+    }
+    if (!usable) {
+      section.catalogError = failure;
+      for (const f of plan.labelFields) section.reasons[f] = PICKLIST_CATALOG_UNAVAILABLE_NOTE;
     }
-    if (!usable) for (const f of plan.labelFields) section.reasons[f] = FIELD_CATALOG_HONESTY_NOTE;
   }
   let lineOfBusiness2 = null;
   const lobId = _nullishCoalesce(plan.lineOfBusinessId, () => ( contractLobPointer));
@@ -20830,13 +20842,13 @@ async function resolveCompositeNames(http, plan, opts = {}) {
   return {
     section,
     lineOfBusiness: lineOfBusiness2,
-    resourceName: (id) => _nullishCoalesce(_optionalChain([section, 'access', _198 => _198.rows, 'access', _199 => _199[`resource:${id}`], 'optionalAccess', _200 => _200.name]), () => ( null)),
-    recordName: (table, id) => _nullishCoalesce(_optionalChain([section, 'access', _201 => _201.rows, 'access', _202 => _202[`${table}:${id}`], 'optionalAccess', _203 => _203.name]), () => ( null)),
+    resourceName: (id) => _nullishCoalesce(_optionalChain([section, 'access', _199 => _199.rows, 'access', _200 => _200[`resource:${id}`], 'optionalAccess', _201 => _201.name]), () => ( null)),
+    recordName: (table, id) => _nullishCoalesce(_optionalChain([section, 'access', _202 => _202.rows, 'access', _203 => _203[`${table}:${id}`], 'optionalAccess', _204 => _204.name]), () => ( null)),
     labelFor: (field, value) => {
       if (value === null || value === void 0) return null;
       const values = picklists[field];
       if (values === void 0) {
-        section.reasons[field] = FIELD_CATALOG_HONESTY_NOTE;
+        section.reasons[field] = section.catalogError !== void 0 ? PICKLIST_CATALOG_UNAVAILABLE_NOTE : FIELD_CATALOG_HONESTY_NOTE;
         return null;
       }
       const hit = values.find((v) => String(v.value) === String(value));
@@ -20870,7 +20882,7 @@ function readNamesOpt(value, where) {
   }
   return value;
 }
-async function labelRows(client, resourceKey, rows) {
+async function labelRows(client, resourceKey, rows, resourceKeyedReasons = false) {
   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] };
@@ -20884,11 +20896,11 @@ async function labelRows(client, resourceKey, rows) {
     const row = catalog.rows.find((r) => r.resource === resourceKey);
     const known = _nullishCoalesce(lastPicklists.get(client), () => ( /* @__PURE__ */ new Map()));
     lastPicklists.set(client, known);
-    if (_optionalChain([row, 'optionalAccess', _204 => _204.fields]) === void 0) {
+    if (_optionalChain([row, 'optionalAccess', _205 => _205.fields]) === void 0) {
       const last = known.get(resourceKey);
       unavailable = (_nullishCoalesce(last, () => ( []))).filter((f) => candidates.includes(f));
       if (last === void 0 || unavailable.length > 0) {
-        catalogError = _nullishCoalesce(_optionalChain([row, 'optionalAccess', _205 => _205.error]), () => ( { code: "INVALID_RESPONSE", message: `fieldCatalog: no ${resourceKey} row` }));
+        catalogError = _nullishCoalesce(_optionalChain([row, 'optionalAccess', _206 => _206.error]), () => ( { code: "INVALID_RESPONSE", message: `fieldCatalog: no ${resourceKey} row` }));
       }
     } else {
       const all = row.fields.filter((f) => f.isPickList).map((f) => f.name);
@@ -20911,6 +20923,11 @@ async function labelRows(client, resourceKey, rows) {
   }
   const plan = builder.plan();
   const names = plan.resourceIds.length === 0 && plan.recordFks.length === 0 && picklistFields.length === 0 ? void 0 : await resolveCompositeNames(client.http, plan);
+  const secondReadFailed = _optionalChain([names, 'optionalAccess', _207 => _207.section, 'access', _208 => _208.catalogError]);
+  if (secondReadFailed !== void 0) {
+    catalogError ??= secondReadFailed;
+    unavailable = [.../* @__PURE__ */ new Set([...unavailable, ...picklistFields])];
+  }
   const out = rows.map((row) => {
     const r = { ...row };
     for (const [field, value] of Object.entries(row)) {
@@ -20926,13 +20943,13 @@ async function labelRows(client, resourceKey, rows) {
     return r;
   });
   const capped = names === void 0 ? 0 : Object.values(names.section.rows).filter((row) => row.capped).length;
-  const unresolved = Object.keys(_nullishCoalesce(_optionalChain([names, 'optionalAccess', _206 => _206.section, 'access', _207 => _207.reasons]), () => ( {})));
-  const reasons = { ..._optionalChain([names, 'optionalAccess', _208 => _208.section, 'access', _209 => _209.reasons]) };
+  const unresolved = Object.keys(_nullishCoalesce(_optionalChain([names, 'optionalAccess', _209 => _209.section, 'access', _210 => _210.reasons]), () => ( {})));
+  const reasons = { ..._optionalChain([names, 'optionalAccess', _211 => _211.section, 'access', _212 => _212.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 (unresolved.length > 0) parts.push(`picklist label(s) unavailable for ${unresolved.join(", ")} (see reasons)`);
+  if (unresolved.length > 0) parts.push(`picklist label(s) unavailable for ${unresolved.map((f) => resourceKeyedReasons ? `${resourceKey}.${f}` : f).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"
@@ -20956,22 +20973,27 @@ async function labelFetchResults(client, result) {
   });
   const results = [...result.results];
   const summaries = [];
+  const reasons = {};
+  const catalogErrors = {};
   for (const [resource, indices] of byResource) {
-    const labelled = await labelRows(client, resource, indices.map((i) => results[i].value));
+    const labelled = await labelRows(client, resource, indices.map((i) => results[i].value), true);
     indices.forEach((idx, j) => {
       results[idx] = { ...results[idx], value: labelled.rows[j] };
     });
-    if (labelled.names !== void 0) summaries.push(labelled.names);
+    if (labelled.names !== void 0) {
+      summaries.push(labelled.names);
+      for (const [field, why] of Object.entries(_nullishCoalesce(labelled.names.reasons, () => ( {})))) reasons[`${resource}.${field}`] = why;
+      if (labelled.names.catalogError !== void 0) catalogErrors[resource] = labelled.names.catalogError;
+    }
   }
   if (summaries.length === 0) return { ...result, results };
-  const reasons = Object.assign({}, ...summaries.map((s) => _nullishCoalesce(s.reasons, () => ( {}))));
-  const catalogError = _optionalChain([summaries, 'access', _210 => _210.find, 'call', _211 => _211((s) => s.catalogError !== void 0), 'optionalAccess', _212 => _212.catalogError]);
+  const catalogError = Object.values(catalogErrors)[0];
   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 } : {},
-    ...catalogError !== void 0 ? { catalogError } : {}
+    ...catalogError !== void 0 ? { catalogError, catalogErrors } : {}
   };
   return { ...result, results, names };
 }