node-autotask 0.16.0 → 0.18.0

package/docs/API.md

@@ -81,15 +81,15 @@ flow.
 Native global `fetch` (Node >= 24) — zero runtime dependencies across the
 whole package. `HttpClient.request<T>(opts): Promise<T>` is the single
 transport primitive (`RequestOptions { method, path, query?, body?, headers? }`):
-JSON bodies, retries with backoff (budget `maxRetries`) in two legs (issue
-#105): a 429 (a pre-processing refusal — the vendor rejected the call before
-executing it) is retried per `Retry-After` on the pre-#105 retriable set
+JSON bodies, retries with backoff (budget `maxRetries`) in three legs
+(issues #105/#109): a 429 (a pre-processing refusal — the vendor rejected
+the call before executing it) is retried per `Retry-After` on the pre-#105 retriable set
 (GET/PUT/DELETE + idempotent-flagged calls — an unflagged POST/PATCH surfaces
 a 429 at once, as before #105), while 5xx/network errors are auto-retried only
 for GET and idempotent-flagged calls: a mutation makes exactly one send on a
 5xx or network error (the write-outcome is unknown once the body was written);
 an explicit `idempotent: true` on a mutation opts back into the pre-#105
-auto-retry on both legs — plus a concurrency guard (`maxConcurrent`, default 10 — the API
+auto-retry on all legs — plus a concurrency guard (`maxConcurrent`, default 10 — the API
 allows <= 10 concurrent), one correlation id per request (surfaced on every
 error and to `onAudit`), and the opt-in client-side hourly budget tracker
 (`rateLimit.perHour`, default off — a sliding one-hour window that waits for a slot within the call deadline, else throws `RateLimitError` with `retryAfter`; the API allows 10,000 req/hour). The tracker is PER PROCESS: it counts only this client's attempts and cannot see other instances or integrations on the tenant (`thresholdInformation.get()` is the only cross-integration signal; the local count is `client.hourlyBudget()`, section 3.2.1). Under the `agent` config profile the exhaustion `suggestedAction` says stop or narrow the query — never raise the limit.
@@ -107,7 +107,22 @@ always, personal/business-sensitive data by default.
 `code` (stable SCREAMING_SNAKE machine code), `category`, `retryable`,
 `operation`, `httpStatus`, `vendorError` (raw vendor body under a documented
 key), `resourceIds`, `suggestedAction` (deterministic next step only),
-`correlationId`, `url`. The vendor documents no error bodies; the shape
+`correlationId`, `url`.
+**`resourceIds` is the LEGACY, unlabeled id list (issue #116).** The stamp
+sites name records of SEVERAL vendor entities — the failed record's own id
+on a `get` miss (any entity), ticket / company / contact ids on the special
+ops, a billing-code id on the `time_entries` allocation failures, staff ids
+on the assignee/owner prechecks — and the field never says which. Every
+SDK stamp site that sets `resourceIds` also sets `details.idRefs` — the
+same ids, each labeled `{ entity, id }` with the vendor entity name
+(singular
+snake_case — `company`, `ticket`, `contact`, `billing_code`, `resource`
+(staff), the same word the error message uses; the pairing is a guarantee
+of the SDK stamp sites — a consumer-constructed error may set `resourceIds`
+without `idRefs`). Machine consumers key on `idRefs`; `resourceIds` is kept
+for compatibility, and neither is ever the input to `expandResourceNames`
+(staff ids only — a colliding non-staff id resolves to an unrelated
+person's name, section 7.7). The vendor documents no error bodies; the shape
 `{ errors: [{ message, field?, code? }] }` is pinned from the node's
 errorHandler and parsed defensively (`parseVendorErrors`,
 `formatVendorDetail`). `errorFromStatus(status, body, url?, operation?,
@@ -151,8 +166,10 @@ served payload verbatim).
 
 `buildFilter(conditions)` wraps caller conditions (multiple top-level
 conditions are `and`-wrapped); `validateFilter` enforces the vendor caps
-(section 5 below). `buildQueryRequest` produces the `QueryModel` wire body
-(`{ MaxRecords, IncludeFields?, filter }`). `normalizedConditions` is the
+(section 5 below). `buildQueryBody` produces the `QueryModel` wire body
+(`{ MaxRecords, IncludeFields?, filter }`, `id` appended to a caller
+`includeFields`), shared by page 1 (`buildQueryRequest`) and every cursor
+continuation of a walk (issue #118). `normalizedConditions` is the
 shared filter-shape gate of the query family (every query-family entry
 point routes through it pre-request): the `filter` param accepts a
 conditions array or `{ filter: [...] }`, and `undefined`/`null` are the
@@ -245,7 +262,7 @@ status → what the vendor does that triggers it.
 | `UnexpectedContentTypeError` | `UNEXPECTED_CONTENT_TYPE` | server | 2xx (non-JSON body + a non-JSON-ish `Content-Type`) | the edge serves a non-JSON page (maintenance) — the vendor never processed the request; `details = { httpStatus, contentType, bodySnippet (256 B) }` — retryable (advisory). A maintenance-notice page is waited out up to `maintenanceMaxWaitMs` (default 1 h) for reads AND writes; on exhaustion `details.maintenance` reports the wait (section 2.1) |
 | `EmptyResponseError` | `EMPTY_RESPONSE` | server | 2xx (empty body, `expectBody`) | a blank 2xx on a call that expects a result (non-DELETE by default — section 2.1); `details = { httpStatus, method }` — retryable for non-DELETE (advisory: the loop never retries 2xx) |
 | `CircuitBreakerError` | `CIRCUIT_BREAKER_OPEN` | policy | — (call not sent) | the host circuit breaker (issue #26, opt-in) is open — refused LOCALLY before the request (zero upstream calls, no hourly stamp) — `notSent: true`, `retryAfter` = remaining open seconds — **retryable: true** (the deliberate divergence from #6's not-retryable cooldown refusal: the open period is bounded and advertised; section 3.2.2) |
-| `ResolutionError` | `RESOLUTION_AMBIGUOUS` / `RESOLUTION_TRUNCATED` / `NOT_FOUND` | resolution | — | `resolve`: multiple exact matches (candidates in `resourceIds`); a cap-tripped bounded client scan (`resolution.scanOnMiss` only; never a silent `null`); a numeric-id miss |
+| `ResolutionError` | `RESOLUTION_AMBIGUOUS` / `RESOLUTION_TRUNCATED` / `NOT_FOUND` | resolution | — | `resolve`: multiple exact matches (candidates in `resourceIds`, labeled in `details.idRefs`); a cap-tripped bounded client scan (`resolution.scanOnMiss` only; never a silent `null`); a numeric-id miss |
 | `PaginationLimitError` | `PAGINATION_LIMIT` | policy | — | a page walk that would exceed the 1000-page guard (`suggestedAction` names the tighter filter) |
 | `QueryTooLongError` | `QUERY_TOO_LONG` | policy | — | caller-requested `via: 'get'` whose serialized URL would exceed the 2048-char GET cap — the SDK never silently degrades to POST |
 | `StaleObjectError` | `STALE_OBJECT` | conflict | — | the caller-supplied `lastModifiedDate` no longer matches the vendor's current value (no `If-Match`/ETag exists) |
@@ -371,7 +388,10 @@ write that answered nothing is now a typed failure (strict default: no
 
 **Deterministic validation 500 (#23).** A 500 whose `errors[]` entries match
 the documented heuristic phrases (`isDeterministicVendor500` — `exceeds
-maximum length` to start) is PERMANENT: the transport makes exactly ONE
+maximum length`, `Missing Required Field`, `Value does not exist for the
+required field`, and since issue #119 `Unable to find <field> in the <entity>
+Entity.` — the live field-existence signature of an unknown `includeFields`
+name) is PERMANENT: the transport makes exactly ONE
 upstream call (it breaks out before the retry decision — the parsed body is
 already in hand at the retry site), and the mapped error keeps the
 `ServerError` class + `SERVER_ERROR` code + status 500 but carries
@@ -470,7 +490,7 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
 |---------|---------|-----|-------|
 | `pageSize` | 10 | 500 (vendor max) | page size for query walks; `maxRecords` on the wire |
 | `timeoutMs` | 30 000 | — | whole-call budget, incl. retries |
-| `maxRetries` | 3 | — | the client's retry budget, overridable per call (`InvokeOptions.maxRetries` / `MutationOpts.maxRetries`; `0` = exactly one send per request the call performs). The budget caps two legs (issue #105): the 429 leg (retried on GET/PUT/DELETE + flagged calls — unchanged) and the 5xx/network leg (GET + flagged only) |
+| `maxRetries` | 3 | — | the client's retry budget, overridable per call (`InvokeOptions.maxRetries` / `MutationOpts.maxRetries`; `0` = exactly one send per request the call performs). The budget caps three legs (issues #105/#109): the 429 leg (retried on GET/PUT/DELETE + flagged calls — unchanged) and the 5xx/network + non-JSON 2xx legs (GET + flagged only) |
 | `maintenanceMaxWaitMs` | 3 600 000 (1 h) | — | **maintenance-window auto-retry** (weekly Autotask window): when the edge answers a non-JSON HTML page that reads as a maintenance notice, the transport waits `maintenancePollMs` and retries for up to this long from the FIRST such page — for reads AND writes (the edge answered before the vendor application saw the request; the weekly window is typically under 30 min). Does not consume `maxRetries`; each post-wait attempt gets a fresh `timeoutMs`. `0` disables the wait. A page that does not look like maintenance (e.g. a wrong `baseUrl`) never enters the loop |
 | `maintenancePollMs` | 30 000 | — | poll interval while waiting out a maintenance page |
 | `maxConcurrent` | 10 | 10 (vendor) | concurrency guard |
@@ -660,9 +680,16 @@ carry paging parameters.
 
 - **Page walk — cursor-follow on `pageDetails.nextPageUrl`** (node-style): page 1
   POSTs the `QueryModel` body (`MaxRecords = pageSize`) to `/V1.0/<E>/query`;
-  later pages POST the preserved filter to the ABSOLUTE `nextPageUrl`, rebased
-  to the client base URL (same-origin cursors verbatim; cross-origin re-based —
-  the node's custom-zone behaviour).
+  later pages POST the SAME body (`buildQueryBody` — `MaxRecords`,
+  `IncludeFields` with the `id` append, the preserved `filter`) to the ABSOLUTE
+  `nextPageUrl`, rebased to the client base URL (same-origin cursors verbatim;
+  cross-origin re-based — the node's custom-zone behaviour). Issue #118: before
+  the fix later pages POSTed `{ filter }` alone and returned the FULL vendor
+  model (live-reproduced 2026-10-19: page 1 of a three-field subset walk —
+  `id`, `title`, `status` — carried 4 keys, page 2 carried 76). The vendor HONOURS `IncludeFields` on a continuation and
+  IGNORES `MaxRecords` (it serves its own 500-row page; the walk slices to its
+  limit, so the RESULT is exact and the wire page size on page 2+ is the
+  vendor's).
 - `Page<T>`: `{ items, page (1-based), pageSize, requestCount (the vendor
   value verbatim — the MaxRecords echo, not a total), hasMore (nextPageUrl
   !== null), totalPages }`. `totalPages` is the pages KNOWN so far —
@@ -911,6 +938,12 @@ the mode pinned (§7.4). The governor rules (pinned):
   the SDK; the caller passes `limit` as the TOTAL cap (default 500, max
   2500) and never owns a stream. `queryAll` keeps its raw behavior (the
   unbounded walk; the catalog text steers the caller away for normal work);
+- a query's `includeFields` NAMES are validated **pre-request** (issue
+  #119b): the live field metadata is the authority (the vendored spec when
+  that read faults), every unknown name is named in one typed
+  `CONFIG_ERROR` before the query POST, and `fieldCheck: false` in the query
+  bag disables the name check (the `string[]` / non-empty shape check always
+  runs);
 - `dryRun` must be a real boolean: anything else (`'true'`, `0`, `null`) is
   refused before any request — only an explicit `false` applies a write;
 - `<resource>.createIfNotExists` takes its match fields as an optional
@@ -1097,6 +1130,18 @@ can be blind to the API user while per-id reads work, so an `id in`
 lookup on a blind table would silently return nothing; the per-id GET is
 the authority read (section 11.2).
 
+**The input is Resource (staff) ids only (issue #116).** Because the op's
+one wire verb is `GET /V1.0/Resources/{id}`, an id of any other vendor
+entity (a ticket / company / contact / billing-code id) resolves to an
+unrelated person's name when it collides with a live staff id (and the
+wrong name then sticks in the default-on `resourceNameCache` under that id
+until TTL — a one-off mis-feed keeps serving it; section 11.21), or to a
+misleading `blind: true` marker when it does not. An `AutotaskError`'s
+legacy `resourceIds` may carry exactly those (the field is unlabeled —
+section 1.5): a consumer must filter the error's `details.idRefs`
+(`{ entity, id }`) on `entity: 'resource'` before feeding ids here — never
+the unlabeled field.
+
 - **Input**: `ids: (number | string)[]` — vendor numeric resource ids
   (safe integers, or the canonical integer string for ids above 2^53 —
   the exact digits ride the wire URL verbatim). Non-numeric string ids
@@ -1621,7 +1666,8 @@ retrying with the same body fails identically; fix the field instead
 httpStatus >= 500). **Resolution (issue #23):** the *deterministic*
 validation 500 is no longer labelled retryable — a 500 whose `errors[]` text
 matches the documented heuristic phrases (`isDeterministicVendor500`:
-`exceeds maximum length`, `Missing Required Field`, `Value does not exist for the required field`) makes exactly ONE upstream call (the
+`exceeds maximum length`, `Missing Required Field`, `Value does not exist for the required field`,
+`Unable to find <field> in the <entity> Entity.` — issue #119, live-verified 2026-10-19) makes exactly ONE upstream call (the
 transport skips the retry), keeps the `ServerError` class + `SERVER_ERROR`
 code + status 500, but carries `retryable: false`, `details.deterministic:
 true`, and a `suggestedAction` pointing at the field catalog
@@ -2000,7 +2046,11 @@ the TTL is the other expiry path.
 
 **The on-demand op:** `operations.fieldCatalog(client, opts?)`
 (`{ resources?, include?, fields?, labels?, fresh? }` — `fields` filters the
-fields-kind rows to the named fields and reports `unmatchedFields`; `labels`
+fields-kind rows to the named fields and reports `unmatchedFields`; a
+projected row is marked `projected: true` (issue #121 — the four derived
+lists then describe the PROJECTED set only, so a consumer can never read a
+projected `required`/`queryable` list as the resource's full picture; a full
+row omits the key); `labels`
 adds the picklist labels; default: the five workflow
 resources, `include: ['fields']`; the closed opts bag is documented in
 the registry record). One bounded entityInformation GET per resource ×
@@ -2603,6 +2653,19 @@ query-verb-ONLY and zero-wire or vendor-column-selection-only:
   billing item to its company / ticket / project / time entry / contract
   service / contract / billing code / expense item, plus the date and the
   amount fields — the "common narrow read" the issue's example targets.
+- **`fieldCheck: false` — the includeFields NAME check's opt-out (issue
+  #119b).** By default the bounded `query` op validates every `includeFields`
+  name BEFORE the query POST: the authority is the entity's LIVE field
+  metadata (`getFieldInfo()` through the cache-aware channel of section
+  11.14 — warm = zero wire), degrading to the vendored spec
+  (`src/field-sets.ts`) when the metadata read faults; with neither an
+  authority the check is skipped. The live set wins when present — a
+  live-only field (`time_entries.postedDate`) is accepted and a
+  vendored-only field the tenant no longer has is refused. Every unknown
+  name is named in ONE typed `CONFIG_ERROR` (zero query wire), with
+  `fieldCheck: false` as the escape hatch and `operations.fieldCatalog` as
+  the discovery pointer. The shape check (`string[]`, non-empty entries)
+  always runs.
 - **The live check (the AC test for the presets).** Each preset's fields
   are asserted to EXIST on the live resource against the LIVE field
   catalogue (`operations.fieldCatalog` — the entityInformation/fields

package/examples/basic.ts

@@ -32,8 +32,8 @@ import { AutotaskClient, type ZoneName } from 'node-autotask';
 const apiCode = process.env.AUTOTASK_TRACKING_IDENTIFIER ?? process.env.AUTOTASK_API_CODE ?? process.env.AUTOTASK_API_INTEGRATION_CODE;
 const user = process.env.AUTOTASK_USERNAME ?? process.env.AUTOTASK_USER;
 const secret = process.env.AUTOTASK_SECRET;
-const zone = process.env.AUTOTASK_ZONE;
-const impersonation = process.env.AUTOTASK_IMPERSONATION_ID;
+const zone = process.env.AUTOTASK_ZONE?.trim() || undefined;
+const impersonation = process.env.AUTOTASK_IMPERSONATION_ID?.trim() || undefined;
 
 const DRY = !(apiCode && user && secret);
 

package/examples/mcp-server-http.ts

@@ -95,13 +95,14 @@ import {
   GATEWAY_WARMUP_BUDGET_MS,
 } from './mcp-gateway.js';
 
-const PORT = Number(process.env.PORT ?? 7437);
+const PORT_RAW = process.env.PORT?.trim();
+const PORT = PORT_RAW !== undefined && PORT_RAW !== '' ? Number(PORT_RAW) : 7437;
 const apiCode = process.env.AUTOTASK_TRACKING_IDENTIFIER ?? process.env.AUTOTASK_API_CODE ?? process.env.AUTOTASK_API_INTEGRATION_CODE;
 const user = process.env.AUTOTASK_USERNAME ?? process.env.AUTOTASK_USER;
 const secret = process.env.AUTOTASK_SECRET;
-const zone = process.env.AUTOTASK_ZONE;
-const impersonation = process.env.AUTOTASK_IMPERSONATION_ID;
-const baseUrl = process.env.AUTOTASK_BASE_URL;
+const zone = process.env.AUTOTASK_ZONE?.trim() || undefined;
+const impersonation = process.env.AUTOTASK_IMPERSONATION_ID?.trim() || undefined;
+const baseUrl = process.env.AUTOTASK_BASE_URL?.trim() || undefined;
 /** The explicit env-vs-gateway switch (issue #5): "on" = credentials per request, headers only. */
 const GATEWAY = (process.env.AUTOTASK_GATEWAY_MODE ?? 'off').toLowerCase() === 'on';
 /** Env mode: DRY when no credentials. Gateway mode is never "DRY" — a request

package/examples/mcp-server.ts

@@ -64,9 +64,9 @@ import { withEnvOverrides } from './mcp-env-config.js';
 const apiCode = process.env.AUTOTASK_TRACKING_IDENTIFIER ?? process.env.AUTOTASK_API_CODE ?? process.env.AUTOTASK_API_INTEGRATION_CODE;
 const user = process.env.AUTOTASK_USERNAME ?? process.env.AUTOTASK_USER;
 const secret = process.env.AUTOTASK_SECRET;
-const zone = process.env.AUTOTASK_ZONE;
-const impersonation = process.env.AUTOTASK_IMPERSONATION_ID;
-const baseUrl = process.env.AUTOTASK_BASE_URL;
+const zone = process.env.AUTOTASK_ZONE?.trim() || undefined;
+const impersonation = process.env.AUTOTASK_IMPERSONATION_ID?.trim() || undefined;
+const baseUrl = process.env.AUTOTASK_BASE_URL?.trim() || undefined;
 const DRY = !(apiCode && user && secret);
 
 /** One client for the whole process (fail-closed construction; null in DRY mode). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime dependencies. Built for building MCP servers and integrations.",
   "type": "module",
   "sideEffects": false,
@@ -112,7 +112,7 @@
     "coverage": "vitest run --coverage",
     "lint": "eslint src test",
     "lint:fix": "eslint src test --fix",
-    "verify": "npm run typecheck && npm run lint && npm run generate:check && npm run build && node scripts/check-capabilities.mjs --ship && npm run mcp:project:check && npm run n8n:project:check && npm run catalog:check && npm run mcp:check-surface && npm run public-surface && npm run verify:pack && npm test",
+    "verify": "npm run lockfile:check && npm run typecheck && npm run lint && npm run generate:check && npm run build && node scripts/check-capabilities.mjs --ship && npm run mcp:project:check && npm run n8n:project:check && npm run catalog:check && npm run mcp:check-surface && npm run public-surface && npm run verify:pack && npm test",
     "plan:derive": "node scripts/derive-plan.mjs",
     "generate:check": "node scripts/generate-batch.mjs --check && node scripts/generate-batch.mjs --check --group B",
     "capabilities:build": "node scripts/generate-capabilities.mjs",
@@ -131,6 +131,7 @@
     "n8n:project:check": "node scripts/project-n8n-mcp.mjs --check",
     "verify:pack": "node scripts/verify-pack.mjs",
     "release:check": "node scripts/check-release-plan-hash.mjs",
+    "lockfile:check": "node scripts/check-lockfile-sync.mjs",
     "capabilities:check:ship": "node scripts/check-capabilities.mjs --ship",
     "prepack": "npm run build",
     "prepublishOnly": "npm run release:check && npm run clean && npm run verify && npm run capabilities:check:ship",