node-autotask 0.16.0 → 0.17.0

package/N8N_MCP_MANIFEST.json

@@ -1,6 +1,6 @@
 {
   "schema": "node-autotask n8n consumer mcp projection v1",
-  "generatedAt": "2026-10-17T13:48:43.907Z",
+  "generatedAt": "2026-10-18T23:23:18.804Z",
   "generator": "scripts/project-n8n-mcp.mjs",
   "inputs": {
     "capabilities": "capabilities.json (the capability registry — the single source of truth)",
@@ -3667,6 +3667,6 @@
     "approvalGatedWrites": 2,
     "destructiveExcluded": 3
   },
-  "capabilitiesHash": "fd92667b96dd9c74d9bbda2a34bf50b9791e2f236a6d2bb50b50a02a1d064882",
+  "capabilitiesHash": "26246eab57263743486ab1afda89379b7b26462c592c5b104e727e337de92886",
   "curationHash": "e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b"
 }

package/N8N_MCP_MANIFEST.md

@@ -1,6 +1,6 @@
 # N8N MCP Manifest — node-autotask (consumer projection)
 
-<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-17T13:48:43.907Z — do not hand-edit. -->
+<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-18T23:23:18.804Z — do not hand-edit. -->
 
 The n8n CONSUMER projection of the capability registry: the canonical source for what the
 n8n-side MCP tools must expose. The SDK is canonical — this is a projection of it, never a
@@ -282,6 +282,6 @@ only via a recorded change to `n8n-mcp.curation.json`.
 
 ## Meta
 
-- generatedAt: 2026-10-17T13:48:43.907Z
-- capabilitiesHash: fd92667b96dd9c74d9bbda2a34bf50b9791e2f236a6d2bb50b50a02a1d064882
+- generatedAt: 2026-10-18T23:23:18.804Z
+- capabilitiesHash: 26246eab57263743486ab1afda89379b7b26462c592c5b104e727e337de92886
 - curationHash: e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b

package/README.md

@@ -147,6 +147,42 @@ length and a two-character prefix per value — never a full value. See
 [`docs/LIVE-TESTING.md`](./docs/LIVE-TESTING.md) §0b.
 
 
+### The full variable set
+
+`.env.example` is the committed template; `.env*` is gitignored, so real values never enter git.
+
+```sh
+cp .env.example .env      # then fill in the three credentials
+```
+
+Optional settings are **commented out with a sample value** — uncomment a line to set it. For example
+`AUTOTASK_PROFILE=agent` selects the conservative agent profile (page 25, 8,000/hr, 20 s timeout,
+1 retry, 3 concurrent), and `AUTOTASK_MAX_RETRIES=1` is that profile's retry budget. Leave the five
+server-layer overrides unset rather than blank: an empty value is *invalid* for them by design
+(fail-closed), so a stray `AUTOTASK_MAX_RETRIES=` stops startup with an error naming the variable.
+
+| variable | read by | meaning |
+|---|---|---|
+| `AUTOTASK_TRACKING_IDENTIFIER` | `bin/doctor.js`, examples, live scripts | API tracking identifier (aliases: `AUTOTASK_API_CODE`, `AUTOTASK_API_INTEGRATION_CODE`) |
+| `AUTOTASK_USERNAME` | same | API user (alias: `AUTOTASK_USER`) |
+| `AUTOTASK_SECRET` | same | secret — see the single-quote contract above |
+| `AUTOTASK_ZONE` | doctor, examples, live scripts | **catalog name**, not a host (default `old-australian` = webservices6); `other` requires a base URL — the template lists all 23 |
+| `AUTOTASK_BASE_URL` | doctor, examples, live scripts | explicit REST base; **wins** over the zone; include `/atservicesrest` |
+| `AUTOTASK_IMPERSONATION_ID` | doctor, examples | optional `ImpersonationResourceId` header |
+| `AUTOTASK_PROFILE` | reference MCP servers | `library` (default) / `agent` — the agent profile's numbers are compared in the template and in *Agent profile* above |
+| `AUTOTASK_RATE_LIMIT_PER_HOUR` | reference MCP servers | hourly limiter: a positive integer, or `0` / `off` to disable |
+| `AUTOTASK_MAX_CONCURRENT` | reference MCP servers | concurrency guard (vendor max 10) |
+| `AUTOTASK_TIMEOUT_MS` | reference MCP servers | whole-call timeout |
+| `AUTOTASK_MAX_RETRIES` | reference MCP servers | retry budget (`0` disables) |
+| `AUTOTASK_UNTRUSTED_WRAP` | MCP servers | `on` (default) / `off` — the `<untrusted_content>` projection |
+| `AUTOTASK_GATEWAY_MODE` | `examples/mcp-server-http.ts` | `on` for multi-tenant gateway mode (per-request credentials) |
+| `PORT` | `examples/mcp-server-http.ts` | listen port (default 7437) |
+| `AUTOTASK_ENV_FILE` | live scripts | alternate `.env` path (shell variables always win) |
+
+The SDK itself never reads `process.env`: pass `apiIntegrationCode` / `userName` / `secret`
+explicitly, or call `loadAutotaskCredentialsFromEnv()`.
+
+
 ## Agent profile (conservative limits for LLM-driven servers)
 
 `profile: 'agent'` on the config switches the SDK to conservative limits for

package/capabilities.json

@@ -1,9 +1,9 @@
 {
-  "generatedAt": "2026-10-17T13:48:43.536Z",
+  "generatedAt": "2026-10-18T23:23:18.606Z",
   "groups": {
     "B": {
       "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-      "builtAt": "2026-10-17T13:48:43.535Z",
+      "builtAt": "2026-10-18T23:23:18.605Z",
       "records": [
         {
           "id": "appointments.count",
@@ -56168,7 +56168,7 @@
     },
     "A": {
       "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-      "builtAt": "2026-10-17T13:48:43.536Z",
+      "builtAt": "2026-10-18T23:23:18.606Z",
       "records": [
         {
           "id": "companies.count",
@@ -112388,7 +112388,7 @@
     },
     "operations": {
       "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-      "builtAt": "2026-10-17T13:48:43.536Z",
+      "builtAt": "2026-10-18T23:23:18.606Z",
       "records": [
         {
           "id": "operations.aggregate",

package/dist/capabilities.cjs

@@ -2,9 +2,9 @@
 
 
 
-var _chunkEWMG3HHUcjs = require('./chunk-EWMG3HHU.cjs');
+var _chunk5ZGXWS4Ecjs = require('./chunk-5ZGXWS4E.cjs');
 
 
 
 
-exports.CAPABILITIES = _chunkEWMG3HHUcjs.CAPABILITIES; exports.CAPABILITY_GROUPS = _chunkEWMG3HHUcjs.CAPABILITY_GROUPS; exports.CAPABILITY_PLAN_HASHES = _chunkEWMG3HHUcjs.CAPABILITY_PLAN_HASHES;
+exports.CAPABILITIES = _chunk5ZGXWS4Ecjs.CAPABILITIES; exports.CAPABILITY_GROUPS = _chunk5ZGXWS4Ecjs.CAPABILITY_GROUPS; exports.CAPABILITY_PLAN_HASHES = _chunk5ZGXWS4Ecjs.CAPABILITY_PLAN_HASHES;

package/dist/capabilities.js

@@ -2,7 +2,7 @@ import {
   CAPABILITIES,
   CAPABILITY_GROUPS,
   CAPABILITY_PLAN_HASHES
-} from "./chunk-JIDR3NPV.js";
+} from "./chunk-6SP6GJJR.js";
 export {
   CAPABILITIES,
   CAPABILITY_GROUPS,

package/dist/{chunk-MAYYTYV5.cjs → chunk-4RJG73GY.cjs}

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5; var _class6;
 
-var _chunkEWMG3HHUcjs = require('./chunk-EWMG3HHU.cjs');
+var _chunk5ZGXWS4Ecjs = require('./chunk-5ZGXWS4E.cjs');
 
 // src/auth.ts
 var AUTH_HEADERS = {
@@ -171,6 +171,7 @@ var AutotaskError = class extends Error {
   
   
   
+  /** Legacy unlabeled id list (issue #116) — see `AutotaskErrorOptions.resourceIds`; the labeled companion rides on `details.idRefs`. */
   
   
   
@@ -15655,7 +15656,7 @@ function unwrapItems(body, operation) {
   }
   return { items: body.items, pageDetails: body.pageDetails };
 }
-function unwrapItem(body, id, operation) {
+function unwrapItem(body, id, operation, entity) {
   if (!isRecord2(body) || !("item" in body)) {
     throw new AutotaskError("Expected the item envelope { item }; got a different shape", {
       code: "INVALID_RESPONSE",
@@ -15671,6 +15672,7 @@ function unwrapItem(body, id, operation) {
       {
         httpStatus: 200,
         resourceIds: id !== void 0 ? [id] : void 0,
+        ...id !== void 0 && entity !== void 0 ? { details: { idRefs: [{ entity, id }] } } : {},
         operation,
         suggestedAction: "Verify the id, or resolve the record by name first."
       }
@@ -15991,7 +15993,7 @@ function capabilitySets() {
   const fieldOps = /* @__PURE__ */ new Map();
   const udfOps = /* @__PURE__ */ new Map();
   const resources = /* @__PURE__ */ new Set();
-  for (const rec of _chunkEWMG3HHUcjs.CAPABILITIES) {
+  for (const rec of _chunk5ZGXWS4Ecjs.CAPABILITIES) {
     if (rec.resource === "operations") continue;
     resources.add(rec.resource);
     if (rec.operation === "getFieldInfo") fieldOps.set(rec.resource, rec);
@@ -16991,6 +16993,19 @@ function decodeFileData(body) {
     { code: "INVALID_RESPONSE", category: "server" }
   );
 }
+var DEPLURAL_EXCEPTIONS = {
+  tag_aliase: "tag_alias"
+};
+function entityNameFromPath(resourcePath) {
+  const segment = resourcePath.slice(resourcePath.lastIndexOf("/") + 1);
+  const snake = segment.replace(/([A-Z])/g, (_m, c, i) => (i > 0 ? `_` : "") + c.toLowerCase()).replace(/_{2,}/g, "_");
+  if (snake.endsWith("ies")) return `${snake.slice(0, -3)}y`;
+  if (snake.endsWith("s")) {
+    const stripped = snake.slice(0, -1);
+    return _nullishCoalesce(DEPLURAL_EXCEPTIONS[stripped], () => ( stripped));
+  }
+  return snake;
+}
 var BaseResource = class {
   
   
@@ -17000,6 +17015,10 @@ var BaseResource = class {
   get resourcePath() {
     return this.config.resourcePath;
   }
+  /** The vendor entity this resource's ids identify (issue #116 — the `details.idRefs` label, e.g. `company`). */
+  get entityName() {
+    return entityNameFromPath(this.resourcePath);
+  }
   /** Parent-scoped template (from the config); undefined for top-level resources. */
   get parentScopedPath() {
     return this.config.parentScopedPath;
@@ -17507,7 +17526,7 @@ var BaseResource = class {
   async getGlobal(id, fresh = false) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.cachedGet(`${this.resourcePath}/${numeric}`, `${this.config.key}.get`, fresh, this.config.key);
-    return unwrapItem(res, numeric, `${this.config.key}.get`);
+    return unwrapItem(res, numeric, `${this.config.key}.get`, this.entityName);
   }
   /**
    * V2 merge read: a FRESH single-record GET that skips response redaction
@@ -17529,7 +17548,7 @@ var BaseResource = class {
       skipResponseRedaction: true,
       maxRetries: _optionalChain([readOpts, 'optionalAccess', _172 => _172.maxRetries])
     });
-    return unwrapItem(res, numeric, `${this.config.key}.get`);
+    return unwrapItem(res, numeric, `${this.config.key}.get`, this.entityName);
   }
   /**
    * Issue #34 fallback merge read: a FRESH parent-scoped single-record GET
@@ -17548,13 +17567,13 @@ var BaseResource = class {
       skipResponseRedaction: true,
       maxRetries: _optionalChain([readOpts, 'optionalAccess', _173 => _173.maxRetries])
     });
-    return unwrapItem(res, numeric, `${this.config.key}.get`);
+    return unwrapItem(res, numeric, `${this.config.key}.get`, this.entityName);
   }
   /** Parent-scoped `GET .../{parentId}/<Child>/{id}` → `{ item }` unwrapped. */
   async getScopedRaw(parentId, id, fresh = false) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.cachedGet(this.scopedItemPath(parentId, id), `${this.config.key}.get`, fresh, this.config.key);
-    return unwrapItem(res, numeric, `${this.config.key}.get`);
+    return unwrapItem(res, numeric, `${this.config.key}.get`, this.entityName);
   }
   /**
    * Attachment single-read: the vendor answers the model DIRECTLY (swagger),
@@ -17564,23 +17583,23 @@ var BaseResource = class {
   async getScopedModel(parentId, id, fresh = false) {
     const numeric = parseIdentifier(id, "id");
     const res = await this.cachedGet(this.scopedItemPath(parentId, id), `${this.config.key}.get`, fresh, this.config.key);
-    return this.unwrapModelLike(res, numeric);
+    return this.unwrapModelLike(res, numeric, this.entityName);
   }
-  unwrapModelLike(body, id) {
+  unwrapModelLike(body, id, entity) {
     if (!isRecord2(body)) {
       throw new AutotaskError(
         `Expected an attachment model (or { item } / { items }) envelope for ID ${id}; got a different shape`,
-        { code: "INVALID_RESPONSE", category: "server", resourceIds: [id] }
+        { code: "INVALID_RESPONSE", category: "server", resourceIds: [id], details: { idRefs: [{ entity, id }] } }
       );
     }
     if (Object.keys(body).length === 0) {
-      throw new NotFoundError(`The record with ID ${id} was not found`, { httpStatus: 200, resourceIds: [id] });
+      throw new NotFoundError(`The record with ID ${id} was not found`, { httpStatus: 200, resourceIds: [id], details: { idRefs: [{ entity, id }] } });
     }
-    if ("item" in body) return unwrapItem(body, id);
+    if ("item" in body) return unwrapItem(body, id, void 0, entity);
     if (Array.isArray(body.items)) {
       const first = body.items[0];
       if (first === null || first === void 0) {
-        throw new NotFoundError(`The record with ID ${id} was not found`, { httpStatus: 200, resourceIds: [id] });
+        throw new NotFoundError(`The record with ID ${id} was not found`, { httpStatus: 200, resourceIds: [id], details: { idRefs: [{ entity, id }] } });
       }
       return first;
     }
@@ -17928,7 +17947,7 @@ var BaseResource = class {
     if (!isRecord2(res)) {
       throw new AutotaskError(
         `Expected the deleted attachment model for ID ${numeric}; got a different shape`,
-        { code: "INVALID_RESPONSE", category: "server", resourceIds: [numeric] }
+        { code: "INVALID_RESPONSE", category: "server", resourceIds: [numeric], details: { idRefs: [{ entity: this.entityName, id: numeric }] } }
       );
     }
     return res;
@@ -18319,9 +18338,9 @@ var BaseResource = class {
     const resource = RESOURCE_KEY_BY_PATH[entityPath];
     const res = await this.cachedGet(`${entityPath}/${numeric}`, `${this.config.key}.fetchRecord`, fresh, resource);
     if (this.config.attachmentGet) {
-      return this.unwrapModelLike(res, numeric);
+      return this.unwrapModelLike(res, numeric, entityNameFromPath(entityPath));
     }
-    return unwrapItem(res, numeric, `${this.config.key}.fetchRecord`);
+    return unwrapItem(res, numeric, `${this.config.key}.fetchRecord`, entityNameFromPath(entityPath));
   }
   /**
    * `getContext` part fetch: a single-record read that degrades to `null`
@@ -18428,6 +18447,7 @@ var BaseResource = class {
         {
           code: "RESOLUTION_AMBIGUOUS",
           resourceIds: ids,
+          details: { idRefs: ids.map((cid) => ({ entity: this.entityName, id: cid })) },
           // issue #59 PR-B: the miss-channel pointer (the generic floor names
           // the resource's own search op — reachable only where searchFields
           // is non-empty, so the named op always exists here).
@@ -18564,7 +18584,7 @@ var BaseResource = class {
       const ids = matches.map((m) => m.id).filter((id) => typeof id === "number");
       throw new ResolutionError(
         `findBy${field}: "${value}" is ambiguous on ${this.config.key} (matched ${matches.length} records)`,
-        { code: "RESOLUTION_AMBIGUOUS", resourceIds: ids }
+        { code: "RESOLUTION_AMBIGUOUS", resourceIds: ids, details: { idRefs: ids.map((cid) => ({ entity: this.entityName, id: cid })) } }
       );
     }
     return matches[0];

package/dist/{chunk-EWMG3HHU.cjs → chunk-5ZGXWS4E.cjs}

@@ -2,7 +2,7 @@
 var CAPABILITY_GROUPS = {
   "B": {
     "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-    "builtAt": "2026-10-17T13:48:43.535Z",
+    "builtAt": "2026-10-18T23:23:18.605Z",
     "records": [
       {
         "id": "appointments.count",
@@ -56167,7 +56167,7 @@ var CAPABILITY_GROUPS = {
   },
   "A": {
     "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-    "builtAt": "2026-10-17T13:48:43.536Z",
+    "builtAt": "2026-10-18T23:23:18.606Z",
     "records": [
       {
         "id": "companies.count",
@@ -112387,7 +112387,7 @@ var CAPABILITY_GROUPS = {
   },
   "operations": {
     "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-    "builtAt": "2026-10-17T13:48:43.536Z",
+    "builtAt": "2026-10-18T23:23:18.606Z",
     "records": [
       {
         "id": "operations.aggregate",

package/dist/{chunk-JIDR3NPV.js → chunk-6SP6GJJR.js}

@@ -2,7 +2,7 @@
 var CAPABILITY_GROUPS = {
   "B": {
     "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-    "builtAt": "2026-10-17T13:48:43.535Z",
+    "builtAt": "2026-10-18T23:23:18.605Z",
     "records": [
       {
         "id": "appointments.count",
@@ -56167,7 +56167,7 @@ var CAPABILITY_GROUPS = {
   },
   "A": {
     "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-    "builtAt": "2026-10-17T13:48:43.536Z",
+    "builtAt": "2026-10-18T23:23:18.606Z",
     "records": [
       {
         "id": "companies.count",
@@ -112387,7 +112387,7 @@ var CAPABILITY_GROUPS = {
   },
   "operations": {
     "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-    "builtAt": "2026-10-17T13:48:43.536Z",
+    "builtAt": "2026-10-18T23:23:18.606Z",
     "records": [
       {
         "id": "operations.aggregate",