node-autotask 0.18.0 → 0.20.0

package/docs/API.md

@@ -93,7 +93,7 @@ auto-retry on all legs — plus a concurrency guard (`maxConcurrent`, default 10
 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.
-Redirects are never followed (a 3xx throws `REDIRECT_BLOCKED`, so auth headers cannot leave the configured origin). Retry waits are capped at 60 s and never outlast the call deadline: a larger `Retry-After` (or one that exceeds the remaining budget) throws the `RateLimitError` immediately. `RequestOptions` adds `signal` (caller `AbortSignal`, combined with the deadline; aborting throws `AutotaskAbortError`, code `ABORTED`, and cancels retry sleeps) and `idempotent` (retry a non-GET method on 5xx/network errors; set on the `/query` and `/query/count` POST reads; on a mutation it is the issue #105 opt-back into the pre-#105 auto-retry — never set on real writes by the SDK). `client.withSignal(signal, () => ...)` applies a caller `AbortSignal` to every request (and retry wait) made inside the callback — the way to propagate MCP request cancellation through `invoke` without a signal parameter on each method. A real write clears the read cache. A non-JSON 2xx body is typed by the response `Content-Type` (section 2.1): a non-JSON-ish header throws the retryable `UNEXPECTED_CONTENT_TYPE` (the edge/maintenance page — a maintenance notice is waited out up to `maintenanceMaxWaitMs`, default 1 h, for reads and writes; otherwise a GET or idempotent-flagged call retries and a write makes one call: section 2.1); a JSON-ish or ABSENT header keeps `INVALID_RESPONSE` (the #13/W-A7 shape-drift key); JSON under any other header still decodes (the decode attempt is unconditional). A blank 2xx on a call that expects a result (every method but `DELETE` by default — `RequestOptions.expectBody`) throws the typed `EMPTY_RESPONSE` (`DELETE` and 204 keep returning `undefined`). A response above `maxResponseBytes` throws `RESPONSE_TOO_LARGE`; HTTP 412 maps to `ConflictError` (category `conflict`).
+Redirects are never followed (a 3xx throws `REDIRECT_BLOCKED`, so auth headers cannot leave the configured origin). Retry waits are capped at 60 s and never outlast the call deadline: a larger `Retry-After` (or one that exceeds the remaining budget) throws the `RateLimitError` immediately. `RequestOptions` adds `signal` (caller `AbortSignal`, combined with the deadline; aborting throws `AutotaskAbortError`, code `ABORTED`, and cancels retry sleeps) and `idempotent` (retry a non-GET method on 5xx/network errors; set on the `/query` and `/query/count` POST reads; on a mutation it is the issue #105 opt-back into the pre-#105 auto-retry — never set on real writes by the SDK). `client.withSignal(signal, () => ...)` applies a caller `AbortSignal` to every request (and retry wait) made inside the callback — the way to propagate MCP request cancellation through `invoke` without a signal parameter on each method. A real write clears the read cache. A non-JSON 2xx body is typed by the response `Content-Type` (section 2.1): a non-JSON-ish header throws the retryable `UNEXPECTED_CONTENT_TYPE` (the edge/maintenance page — a maintenance notice is waited out up to `maintenanceMaxWaitMs`, default 1 h, for reads and writes; the same wait recognises the page at any status for calls safe to re-send (a GET or an explicitly idempotent-flagged call — an unflagged mutation makes ONE send with `details.maintenanceDetected`): section 2.1; otherwise a GET or idempotent-flagged call retries and a write makes one call); a JSON-ish or ABSENT header keeps `INVALID_RESPONSE` (the #13/W-A7 shape-drift key); JSON under any other header still decodes (the decode attempt is unconditional). A blank 2xx on a call that expects a result (every method but `DELETE` by default — `RequestOptions.expectBody`) throws the typed `EMPTY_RESPONSE` (`DELETE` and 204 keep returning `undefined`). A response above `maxResponseBytes` throws `RESPONSE_TOO_LARGE`; HTTP 412 maps to `ConflictError` (category `conflict`).
 Per-tenant 429 cooldown gate (`cooldown`, ON by default): once a 429 surfaces from the transport (retries spent, a `Retry-After` too long to wait out, or a non-retriable method), the client records a cooldown deadline for that tenant (lowercased `UserName` + lowercased host — impersonation does not change the key), and every further call for that tenant fails LOCALLY — before the semaphore, the hourly limiter and fetch, with zero upstream calls — with a `RateLimitError` (`code: 'RATE_LIMITED_COOLDOWN'`, `notSent: true`, `retryAfter` = remaining seconds; no credentials appear in the message) until the deadline passes. Duration is `Retry-After` clamped to `cooldown.maxMs` (default 15 minutes), or `cooldown.defaultMs` (default 60 s) when the header is missing or unparseable; the thread-threshold 429 (vendor code `Itgenatr005`, which clears in seconds) arms only a short window: min(`Retry-After`, 10 s), default 5 s. A 2xx from a call that got through clears the gate early; expiry is lazy (the first call after the deadline deletes the entry and proceeds); a hostile `Retry-After` (huge, zero, negative, non-numeric) is clamped to the cap or falls back to the default, so a lock-out is always bounded. `thresholdInformation.get()` bypasses the gate so a throttled tenant can still read its own headroom (a 2xx from it clears the gate; a 429 re-arms it). The default store is the in-process in-memory map shared by every client instance (capped at 1024 entries, evicting the earliest deadline first — failing open); `cooldown: { enabled: false }` disables the gate and `cooldown.store` injects a custom `CooldownStore` (the interface leaves room for a shared/Redis-backed store). Gated calls emit an audit event marked `notSent` and do not count toward `rateLimit.perHour`. Limits worth knowing: the gate is per process — other processes and integrations on the same tenant are invisible to it (`thresholdInformation` is the only cross-integration signal); it can mask early recovery if the vendor window clears before `Retry-After`; a process that loads both the ESM and the CJS build gets two default stores (the default store is deliberately not anchored on `globalThis`) — inject one shared `CooldownStore` if you need cross-build sharing.
 
 Credential-shaped fields are redacted in audit payloads by default.
@@ -259,7 +259,7 @@ status → what the vendor does that triggers it.
 | `RateLimitError` | `RATE_LIMITED` | rate_limit | 429 | hourly/secondly budget exceeded — `retryAfter` from `Retry-After` — retryable |
 | `RateLimitError` | `RATE_LIMITED_COOLDOWN` | rate_limit | — (call not sent) | per-tenant cooldown after a surfaced 429 (issue #6) — `notSent: true`, `retryAfter` = remaining seconds — not retryable before the deadline |
 | `ServerError` | `SERVER_ERROR` | server | 5xx | vendor 5xx — retryable — EXCEPT a deterministic field-validation 500 (a known phrase, `isDeterministicVendor500`): same class/code/status, `retryable: false` + `details.deterministic: true` (issue #23) |
-| `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) |
+| `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 non-JSON `2xx` maintenance page is waited out up to `maintenanceMaxWaitMs` (default 1 h) for reads AND writes; at `4xx`/`5xx` the page is waited out only for calls safe to re-send (GET / explicitly idempotent-flagged) — an unflagged mutation makes one send and carries `details.maintenanceDetected` (issue #114); a wait that ran is reported on the surfaced error as `details.maintenance` (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`, labeled in `details.idRefs`); a cap-tripped bounded client scan (`resolution.scanOnMiss` only; never a silent `null`); a numeric-id miss |
@@ -342,21 +342,41 @@ transport `RequestOptions` flag) or raises `maxRetries`. An
 contract break is not transient.
 
 **Maintenance-window auto-retry (weekly window).** Autotask runs a weekly
-maintenance window (typically under 30 minutes) during which the edge answers
-an HTML page — the non-JSON 2xx above — before the application ever sees the
-request. When that page reads as a maintenance notice, the transport waits
-`maintenancePollMs` (default 30 s) and retries, for up to
-`maintenanceMaxWaitMs` (default 1 hour) from the first such response. This
-applies to **reads and writes**: the page is a pre-execution edge signal, which
-is the one case where a bounded auto-retry of a write is safe — the general
-rule is untouched (a 5xx / network / timeout error never auto-retries a write;
-§2.2). The wait does not consume `maxRetries`, each post-wait attempt gets a
-fresh `timeoutMs`, and a caller `AbortSignal` interrupts the wait. A page that
-does not look like a maintenance notice (for example a wrong `baseUrl` serving
-a web site) is surfaced at once. On exhaustion the error carries
-`details.maintenance = { waits, waitedMs, maxWaitMs, exhausted: true }` and a
-suggestedAction naming the window. Disable with `maintenanceMaxWaitMs: 0`
-(config or per call).
+maintenance window during which the edge answers an HTML page before the
+application ever sees the request. The transport recognises that page from the
+**first 256 bytes** of its body at any status (`2xx`, `4xx`, `5xx`) — issue
+#114: the edge picks the status line, and a 503/404 HTML page used to burn the
+retry budget or surface as `NOT_FOUND`. The gate is the body: a **JSON** body
+never enters (a JSON 503 is the application answering; it keeps the normal
+rules, and a write still makes one send). When the page reads as a maintenance
+notice:
+
+- a non-JSON **`2xx`** page is waited out and retried for **reads and writes**
+  (a 2xx HTML page is edge-served before execution — the 0.16.0 premise);
+- a non-JSON **`4xx`/`5xx`** page is waited out and retried only for calls that
+  are **safe to re-send** (`retriable5xx`: a `GET` or an explicitly
+  `idempotent`-flagged call). An UNFLAGGED mutation answered with such a page
+  makes **exactly one send** and surfaces the status's own error with
+  `details.maintenanceDetected = true` and a verify-before-reissuing action — a
+  proxy can serve that page AFTER forwarding the write, so the outcome is
+  unknown (the §2.2 write rule is intact).
+
+The wait polls `maintenancePollMs` (default 30 s) for up to
+`maintenanceMaxWaitMs` (default 1 hour) from the first such response. The
+observed ceiling is 4 h (`MAINTENANCE_WINDOW_MAX_MS`; 19 live windows:
+30–240 min, median ≈ 2 h) — an unattended worker should pass
+`maintenanceMaxWaitMs: MAINTENANCE_WINDOW_MAX_MS`. The wait does not consume
+`maxRetries`, each post-wait attempt gets a fresh `timeoutMs`, and a caller
+`AbortSignal` interrupts the wait. A non-JSON HTML-ish page that does not look
+like a maintenance notice (for example a wrong `baseUrl` serving a web site, or
+a stock proxy page) is surfaced at once with
+`details.maintenancePatternMiss = true` and the 256-byte snippet logged at
+`debug` (issue #114 — the next occurrence supplies the wording). When a wait
+ran, the surfaced error always carries
+`details.maintenance = { waits, waitedMs, maxWaitMs, exhausted }` (`exhausted`
+is true when the budget was spent; a wording change on a later page surfaces
+that page's own error with `exhausted: false`). Disable with
+`maintenanceMaxWaitMs: 0` (config or per call).
 Zone discovery rides the same transport, so a startup failure during
 maintenance is recognisable by the code. `details.bodySnippet` is the first
 256 BYTES of the raw body — TRUNCATION ONLY (the name-based redaction is a
@@ -491,7 +511,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 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 |
+| `maintenanceMaxWaitMs` | 3 600 000 (1 h) | — | **maintenance-window auto-retry** (weekly Autotask window): when the first 256 bytes of a non-JSON body read as a maintenance notice, the transport waits `maintenancePollMs` and retries for up to this long from the FIRST such page. A `2xx` page is waited out for reads AND writes (edge-served before execution); a `4xx`/`5xx` page only for calls safe to re-send (GET / explicitly idempotent-flagged) — an unflagged mutation makes ONE send and carries `details.maintenanceDetected` (a proxy can serve the page after forwarding). JSON bodies never enter. Does not consume `maxRetries`; each post-wait attempt gets a fresh `timeoutMs`. `0` disables the wait. A non-matching HTML-ish page stamps `details.maintenancePatternMiss`. Observed ceiling 4 h: `MAINTENANCE_WINDOW_MAX_MS` (19 windows: 30–240 min, median ≈ 2 h) |
 | `maintenancePollMs` | 30 000 | — | poll interval while waiting out a maintenance page |
 | `maxConcurrent` | 10 | 10 (vendor) | concurrency guard |
 | `profile` | `library` | — | `library` = today's defaults (changes nothing); `agent` = the conservative `AGENT_PROFILE` limits for LLM-driven workloads (below). Resolution: explicit config > profile > library default |
@@ -752,6 +772,30 @@ carry paging parameters.
     `limit >= latest` (above that the returned count is governed by
     `latest`; `limit` is the blind-branch walk window). `latest` is
     query-verb-ONLY (`queryAll` / `count` bags are unchanged).
+    **The count-probe cache (issue #127).** The walk's count probes (the
+    initial `count(F)` + every `id gt T` threshold probe) are cached per
+    client in a short-TTL in-process store: 30 s TTL, 4096-entry memory
+    guard, keyed by (resource plan key, canonical filter serialisation).
+    A re-asked "top N" within 30 s makes ZERO extra vendor count calls
+    (full-set AND threshold mode). A real write through the SAME client
+    clears the cache — and a probe still in flight across the write is
+    DISCARDED by the cache's invalidation epoch (issue #139: its pre-write
+    answer must not re-anchor a stale top-N within the TTL — the next
+    `latest` re-probes). Never cached: the blind-surface / pinned-empty
+    sentinels (the plan-pinned stamps stay fresh and re-derive on every
+    call), errors, and anything outside the probe path — the plain `count`
+    op and `operations.aggregate` call the vendor count directly and
+    promise fresh totals. A write made ELSEWHERE (another client, the
+    Autotask UI) shows up once the 30 s TTL expires — that is the
+    documented snapshot trade. The truncation guard covers the
+    growth-of-total direction; a stale-LOW total within the TTL is NOT
+    left to it: when a full-set walk truncates against a cached total,
+    the SDK re-probes the total ONCE fresh (invalidating the entry) and
+    continues the walk to a larger fresh total — the
+    `LATEST_WINDOW_INCOMPLETE` refusal stands only when the fresh probe
+    confirms the cached value (bounded: at most one extra count probe per
+    walk). A total of `0` is NEVER cached, so a repeated call after an
+    out-of-band insert re-probes instead of returning a false empty.
   - **`noteChars: N` (issue #61) — the opt-in per-field free-text cap.**
     `N` (integer >= 1, pre-request validated, zero wire) caps EVERY
     string value in the resource's untrusted-class free-text fields
@@ -938,12 +982,24 @@ 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);
+- a query's `includeFields` NAMES and its `filter` condition FIELD NAMES are
+  validated **pre-request** (issues #119b + #125): the authority is the
+  entity's LIVE field metadata (the vendored spec when that read faults —
+  the resource's plan-pinned live-only fields, `metadata.liveOnlyFields`,
+  are exempt from the vendored refusal: the live entity carries them and
+  the vendor model omits them (e.g. `time_entries.postedDate` /
+  `postedOnTime`); a truly unknown name is still refused), every unknown
+  name is named in one typed `CONFIG_ERROR` before the query POST (zero
+  query wire — the cold fieldCache may cost the one authority metadata GET
+  first), and `fieldCheck: false` in the query bag disables BOTH name
+  checks (the `string[]` / non-empty shape check and the filter grammar
+  always run). The `count` verb's bag (closed to `filter` + the
+  `fieldCheck` opt-out — issue #145) is name-checked the same way
+  (issue #140 — the documented unchecked scope is the direct
+  `queryBounded` / `queryAll` client paths AND the `operations.aggregate`
+  filter, which is grammar-checked only — its groupBy/sum field names ARE
+  checked; name-checking the aggregate filter is a separate follow-up, the
+  op's own field whitelist being the different authority);
 - `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
@@ -1444,6 +1500,16 @@ drift). Records exist only for plan rows that are implemented/tested; the
 plan (`capabilities.plan.json`) is the single source of truth and the
 registry is its compiled form.
 
+**Consumer-defaulted arguments (issue #115).** A manifest CONSUMER may fill an
+argument this registry marks required when the caller omits it — the manifest
+describes the SDK operation, not the consumer's tool contract. The one
+instance today is `contracts.profitability`: the SDK requires
+`dateFrom`/`dateTo`, and iit-mcp-autotask defaults both to the last full
+calendar month (UTC) when the caller omits them. The served
+`metadata.args`/`metadata.usage` and the record's
+`inputSchema.opts.description` state the caveat; a consumer that trusts the
+raw manifest should apply the same contract.
+
 ### 9.1 Generated artifact #5: `src/relationships.ts` (the relationship map + zone facts)
 
 The regen chain's 5th generated module (plan S12 §2.4: the 4 generated
@@ -1962,7 +2028,9 @@ into one predicted-failure-free attempt.
 - **`time_entries.postedWithin(from, to, opts?)`** — the working posted-state
   window read: an inclusive UTC `dateWorked` window (`from`/`to` are
   `YYYY-MM-DD` date strings — the S1c guard forbids Date positionals), ONE
-  bounded query (`limit` 1-500, default 25) returning
+  bounded query (`limit` 1-500, default 500 — the hard cap, issue #128: a
+  window with more than 500 matching rows needs `time_entries.query` with the
+  same `dateWorked` filter, its 2500-row walk cap) returning
   `{ items, postedCount, unpostedCount, window }`; `opts.posted` narrows
   (true = posted rows only, false = unposted rows only, omitted = both
   counted in one pass) and `ticketID` / `resourceID` narrow further.
@@ -1978,7 +2046,7 @@ into one predicted-failure-free attempt.
   the posted/unposted counts then cover the returned rows ONLY (at most
   `limit`); re-query with a wider window or a narrowing filter to reconcile
   the totals. `time_entries.dateWorkedWindow(from, to, opts?)` is the
-  clearer-named alias: the same wire, the same result (incl. `truncated`),
+  unambiguous-named alias: the same wire, the same result (incl. `truncated`),
   its own op identity (plan row / MCP tool
   `autotask_timeEntry_date_worked_window` / operation label) — the name
   names the `dateWorked` field the window is on; `postedWithin` keeps its
@@ -2618,8 +2686,11 @@ additive, and mirrors the family:
   with the identical contract, so the whole window family is uniformly
   timezone-anchored (default UTC unchanged).
 - **Shape and wire** — each op is exactly ONE bounded query (`MaxRecords`
-  1-500, default 25; the `itemDate` / `invoiceDateTime` `gte`/`lte` filter
-  rides the wire), and the result is the plain `items[]` array — no counts
+  1-500, default 500 — the hard cap, issue #128: a call without `limit` takes
+  the first 500 rows in id order; a window with more than 500 matching rows
+  needs the bounded query op with the same date-window filter — its 2500-row
+  walk cap; the `itemDate` / `invoiceDateTime` `gte`/`lte` filter rides the
+  wire), and the result is the plain `items[]` array — no counts
   (the time-entry family shape).
 
 ### 11.23 Free-text caps and includeFields presets (issue #61)
@@ -2653,19 +2724,34 @@ 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` — the field-NAME checks' opt-out (issues #119b +
+  #125).** By default the bounded `query` op validates every `includeFields`
+  name AND every `filter` condition field 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. Under
+  degradation the resource's plan-pinned live-only fields (the record's
+  `metadata.liveOnlyFields` — the live entity carries them and the vendor
+  model omits them: `time_entries.postedDate` / `postedOnTime`, the W-D3
+  spec gap) are EXEMPT from the vendored refusal, so a caller-composed
+  `postedDate` filter degrades to the pre-#125 behaviour (the query reaches
+  the vendor and works on a zone that honours the field); a name unknown to
+  BOTH the vendored spec and the pinned set is still refused. Every unknown
+  name is named in ONE typed `CONFIG_ERROR` (zero query wire — the cold
+  fieldCache may cost the one authority metadata GET first), with
   `fieldCheck: false` as the escape hatch and `operations.fieldCatalog` as
-  the discovery pointer. The shape check (`string[]`, non-empty entries)
-  always runs.
+  the discovery pointer. The shape checks (`string[]` non-empty
+  `includeFields`; the filter grammar) always run. The `count` verb's bag
+  (closed to `filter` + the `fieldCheck` opt-out — issue #145) is
+  name-checked the same way (issue #140 — the documented unchecked scope
+  is the direct `queryBounded` / `queryAll` client paths AND the
+  `operations.aggregate` filter, which is grammar-checked only — its
+  groupBy/sum field names ARE checked; name-checking the aggregate filter
+  is a separate follow-up, the op's own field whitelist being the
+  different authority).
 - **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.18.0",
+  "version": "0.20.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,
@@ -87,6 +87,7 @@
     "bin",
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "ARCHITECTURE.md",
     "capabilities.json",