node-autotask 0.40.0 → 0.42.0

package/docs/API.md

@@ -740,20 +740,11 @@ carry paging parameters.
     query-verb-ONLY (`queryAll` / `count` bags are unchanged; the raw
     `.query()` walker is uncapped — section 8's `queryBounded` is the MCP
     query surface the issue targets).
-  - **`fieldsPreset: name` (issue #61) — the closed includeFields
-    presets.** The named preset is resolved PRE-WALK to its `includeFields`
-    list (the vendor's own column selection rides the existing `IncludeFields`
-    wire path; `id` is always appended by the id-append — zero extra wire).
-    v1 ships the one preset the issue names: `billing_join` on
-    `billing_items` (the 14 join/measure columns — section 11.23). The
-    closed-bag refusals are pre-request (zero wire): unknown preset name
-    (the valid names are named), preset/resource mismatch (the preset and
-    its resource are named), and `fieldsPreset` + an explicit
-    `includeFields` in the same bag (both are named — no silent
-    precedence). The preset FIELD EXISTENCE is verified against the LIVE
-    field catalogue (the live-smoke check — the review correction's
-    mandate; the vendored spec is a non-authoritative guard only), not
-    against `MODEL_FIELD_SETS`.
+  - **`fieldsPreset` — removed in 0.42.0 (issue #287).** The closed
+    includeFields presets are gone; the former `billing_join` column list is
+    documented as a plain `includeFields` example in section 11.23. A
+    `fieldsPreset` in the bag is refused pre-request as an unknown key
+    (the valid keys are named; `includeFields` is the named successor).
 - Raw SDK reads are unchanged: `queryAll` (deterministic plain `T[]`,
   unbounded, 1000-page guarded) and `query` (stream, `for await ...`). The
   MCP surface steers the caller to the bounded `query` op; `queryAll` is for
@@ -1402,9 +1393,10 @@ notes cannot be deleted, so they never use create-then-delete.
   optionally scoped to one company (a `companyID eq` leaf and-joined server-side with the title match) and
   projected to the listed columns (`id` is always returned). `searchWithDetail` takes the same bag. Malformed
   `companyID` / `includeFields` are refused before any request. Other resources' `search` is unchanged.
-- **Deprecated (issue #278, since 0.38.0; removed in the next minor):** `time_entries.recentTickets` is a
-  strict subset of an aggregate grouped by ticket now that relation filters (§5) and default labels (§11.27)
-  exist. Replacement (1-2 calls instead of 2+):
+- `search` refuses an unknown option key (a misspelt `companyId` can't silently widen the search), and drops an
+  empty `userDefinedFields` the vendor appends to projected rows.
+- **Hours per ticket for a resource** (`time_entries.recentTickets` was removed in 0.41.0, issue #290): aggregate
+  the time entries grouped by ticket, using relation filters (§5) and label siblings (§11.27, opt-in):
 
   ```ts
   const res = await aggregate(client, 'time_entries.query', [
@@ -1412,29 +1404,16 @@ notes cannot be deleted, so they never use create-then-delete.
     { field: 'dateWorked', op: 'gte', value: '2026-10-01' },
     { field: 'dateWorked', op: 'lte', value: '2026-10-28' },
     { field: 'ticket.companyID', op: 'eq', value: 123 }, // optional: one company, resolved server-side
-  ], { groupBy: ['ticketID'], sum: ['hoursWorked'] });
+  ], { groupBy: ['ticketID'], sum: ['hoursWorked'], names: true });
   // res.groups[i] = { key: { ticketID, ticketIDName: '<untrusted_content>T20261001.0001 Printer down</untrusted_content>' },
   //                   count, sums: { hoursWorked } }
   ```
 
-  For per-ticket status / assignee / company use `operations.fetchByIds` on the group ticket ids (labels
-  included: `statusLabel`, `assignedResourceIDName`, `companyIDName`).
-- `time_entries.recentTickets(from, to, { resourceID, companyID?, tz?, limit? })` — the distinct tickets a
-  resource logged time against in an inclusive `dateWorked` window (`YYYY-MM-DD`; UTC days, or the local days in
-  `tz`). One bounded time-entry read (`dateWorked` + `resourceID`; `limit` 1-500, default 500, bounds the
-  **entries** scanned) plus `id in [...]` ticket reads (100 ids each). Result `{ items, entriesRead,
-  entriesWithoutTicket, unresolvedTicketIDs, window, truncated }`; each item carries `ticketID`, `ticketNumber`,
-  `title`, `status`, `assignedResourceID`, `companyID`, `entryCount`, `totalHours`, `lastWorked`, newest first.
-  TimeEntry has no `companyID`, so `companyID` is applied **after the join**, client-side on the ticket rows'
-  own `companyID` (the ticket read is not company-filtered on the wire). Entries on other companies' tickets
-  still consume `limit`; those tickets are only counted in `excludedTickets` (ids are not returned), and
-  `unresolvedTicketIDs` holds only tickets the read did not return at all (deleted or invisible, dropped from
-  `items` when `companyID` is set). `truncated: true` (same meaning as `postedWithin`) means the rollup covers
-  the scanned entries only; narrow the window. `search` refuses an unknown option key (a misspelt `companyId`
-  can't silently widen the search), and drops an empty `userDefinedFields` the vendor appends to projected rows.
-- **`tz` on the `dateWorked` ops** (`recentTickets`, `postedWithin`, `dateWorkedWindow`, `customRange` and the relative
+  For per-ticket status / assignee / company use `operations.fetchByIds` on the group ticket ids
+  (with `names: true`: `statusLabel`, `assignedResourceIDName`, `companyIDName`).
+- **`tz` on the `dateWorked` ops** (`postedWithin`, `dateWorkedWindow`, `customRange` and the relative
   windows): the vendor stores `dateWorked` as a date-only value at 00:00 UTC, so the wire bounds are always whole UTC days.
-  For `recentTickets` / `postedWithin` / `dateWorkedWindow` / `customRange` the `from`/`to` days ARE the days, so `tz` is
+  For `postedWithin` / `dateWorkedWindow` / `customRange` the `from`/`to` days ARE the days, so `tz` is
   validated but never shifts them. For the relative windows (`today`, `last7`, `lastFullMonth`, ...) `tz` picks which
   calendar dates the window covers in that zone and the bounds are whole UTC days of those dates. (Before 0.24.0 a `tz`
   behind UTC, e.g. `America/Los_Angeles`, selected the NEXT UTC day; live-verified 2026-10-23.)
@@ -1499,8 +1478,7 @@ resolver holds a status literal: the move engine's closed-target refusal,
 `tickets.forResource(resourceID, opts?)` lists the tickets assigned to one
 resource, as primary assignee, secondary resource, or both (the `scope` option,
 default `both`; the seam is `Tickets.assignedResourceID` for primary and the
-`TicketSecondaryResources` link table for secondary). It follows
-`time_entries.recentTickets`: two bounded reads (a `Tickets/query` on
+`TicketSecondaryResources` link table for secondary). Two bounded reads (a `Tickets/query` on
 `assignedResourceID` and a `TicketSecondaryResources/query` on `resourceID`,
 both `id in [...]`-chunked when the link set is large) unioned client-side —
 deliberately not the cross-field grouped `or`, whose live semantics are
@@ -1860,7 +1838,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `ticket_secondary_resources` | TicketSecondaryResource | entity | extended | yes (tickets) | query, count, get, create, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketSecondaryResources_get |
 | `ticket_webhooks` | TicketWebhook | entity | extended | yes (tickets) | query, count, get, create, update, delete, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketWebhook_get |
 | `tickets` | Ticket | entity | core | no | query, count, get, create, update, resolve, search, getContext | changeStatus, findByTicketNumber, forResource, fullContext, getEntityInfo, getFieldInfo, getUdfInfo, lineOfBusiness, openWithNoteAndAssign, slaHealthCheck, statusSemantics, summary, timeline | autotask_ticket_get |
-| `time_entries` | TimeEntry | entity | extended | no | query, count, get, create, update, delete, resolve | approve, createForResource, createIfNotExists, customRange, dateWorkedWindow, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, moveToTicket, postedWithin, recentTickets, today, yesterday | autotask_timeEntry_get |
+| `time_entries` | TimeEntry | entity | extended | no | query, count, get, create, update, delete, resolve | approve, createForResource, createIfNotExists, customRange, dateWorkedWindow, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, moveToTicket, postedWithin, today, yesterday | autotask_timeEntry_get |
 | `time_entry_attachments` | TimeEntryAttachment | entity | extended | yes (time_entries) | query, count, get, create, delete, resolve | download, getEntityInfo, getFieldInfo, getUdfInfo | autotask_timeEntryAttachment_get |
 | `time_off_requests` | TimeOffRequest | entity | extended | no | query, count, get, resolve | approve, getEntityInfo, getFieldInfo, getUdfInfo, reject | autotask_timeOffRequest_get |
 | `inventory_products` | InventoryProduct | entity | extended | no | query, count, get, create, update, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo, stockedItemsAdd, stockedItemsRemove, stockedItemsTransfer | autotask_inventoryProduct_get |
@@ -2184,11 +2162,14 @@ Field-validation failures ride on **HTTP 500**, not 4xx: the SDK surfaces a
 typed `ServerError` (code `SERVER_ERROR`, httpStatus 500) with a structured
 redacted `vendorError` naming the offending field and a deterministic
 `suggestedAction` (rw-test.md: 9/9 create probes PASS the contract). **Known
-quirk**: the error contract labels 500s `retryable: true` ("the server error is
-transient") even when the 500 is a *deterministic* missing-field rejection —
-retrying with the same body fails identically; fix the field instead
-(`src/errors/` sets `retryable: true` for `SERVER_ERROR` and for every
-httpStatus >= 500). **Resolution (issue #23):** the *deterministic*
+quirk**: the error contract labels 500s `retryable: true` even when the 500
+is a *deterministic* missing-field rejection — retrying with the same body
+fails identically; fix the field instead (`src/errors/` sets `retryable: true`
+for `SERVER_ERROR` and for every httpStatus >= 500). The plain-5xx
+`suggestedAction` is the honest SDK-voice hint (issue #287): the SDK already
+retried per its policy; a repeated 500 on one entity while others work
+usually means the API user lacks permission on that entity — ask the Autotask
+admin to grant it; otherwise retry once more at most. **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`,
@@ -2861,24 +2842,20 @@ alone cannot fit) and the result carries `truncated: true` and
 `truncation: { reason: 'maxBytes', maxBytes, fullBytes, omitted: [{ resource,
 kind, count }], note }`, so it is always valid JSON and never over the cap (a
 result whose envelope alone cannot fit, e.g. many resources under a small cap,
-is refused with `CONFIG_ERROR`). Both default off (the
-full rows, no cap); a model-facing server should pass `compact: true` and a
-`maxBytes`.
-
-**Reference targets (issue #219 N1).** Every projected field row carries
-`targetResource: string | null` and `targetEnumerable: boolean`: the plan
-resource key the vendor `referenceEntityType` names, and whether that
-resource has a read (`query`/`get`) path, i.e. whether a caller can
-enumerate valid ids with it. The join is DERIVED from the generated
-registry — `resourceForEntityType(entityType)` in
-`node-autotask/operations` reads each resource's plan `apiEntity` (plus
-the singular entity name where the plan's `apiEntity` is the plural path
-segment) and returns `null` when the plan carries no such resource, so a
-consumer never hand-maps `"CompanyLocation"` -> `company_locations`. A
-row for a target the plan cannot enumerate reads `null` + `false`; the
-row carries no remedy, label or exposure claim (`plan.referenceTargets`
-is the only home for those). The same helper serves reference UDF rows —
-there is no second entity-type table.
+is refused with `CONFIG_ERROR`). Issue #287: an ABSENT `compact` is now
+compact BY DEFAULT — compact ONLY when the call passes no `fields` filter AND
+no `labels: true` (`labels: true` without `fields` keeps the full rows +
+picklist values — the ~137 KB case above, unchanged); an explicit
+`compact: false` restores the full rows. `maxBytes` still defaults off; a
+model-facing server can rely on the compact default and pass a `maxBytes`.
+
+**Reference targets (issue #219 N1 — removed in issue #287).** The
+plan-static per-row extras `targetResource` / `targetEnumerable` and the
+`resourceForEntityType` helper are REMOVED (issue #287, breaking): a
+reference field row carries the vendor's `isReference` flag and
+`referenceEntityType` name, and the generated registry (the `apiEntity`
+join, via `autotask_catalog`) is where a caller resolves which plan
+resource enumerates a named entity — no second entity-type table ships.
 
 **User-defined fields (issue #219 N7).** `udfCapable` entities carry a
 parallel field system, and the served row states it rather than leaving it
@@ -3328,8 +3305,8 @@ picklist scope (owner-approved list: the ticket fields
 rides ONE `operations.fieldCatalog` `labels: true` call (zero extra wire
 on a warm fieldCache). The separate name-read budget counts COLD wire
 name reads only (cache hits are free of it); over-budget ids serve
-`name: null, capped: true` on the composite's name row + the top-level
-`truncated` marker — never an error. An unresolvable id serves the blind
+`name: null` on the composite's name row + the top-level `truncated`
+marker — never an error. An unresolvable id serves the blind
 marker (`name: null, blind: true`); a picklist whose values the vendor
 does not expose to this API user serves `null` + the fieldCatalog
 reason row (the #64 W-A4 wall) — never an error. A picklist that IS served but does not
@@ -3409,12 +3386,12 @@ additive, and mirrors the family:
   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)
+### 11.23 Free-text caps (issue #61)
 
 Issue #61 (the library remainder after the server-side split — TSV /
 `output_path` / the untrusted-wrapper opt-out live in the server repo)
-adds two opt-in keys to the bounded-query bag (section 4), both
-query-verb-ONLY and zero-wire or vendor-column-selection-only:
+added opt-in keys to the bounded-query bag (section 4), both
+query-verb-ONLY and zero-wire:
 
 - **`noteChars: N` — the free-text cap.** One integer (>= 1) caps EVERY
   string value in the resource's untrusted-class free-text fields (the
@@ -3426,20 +3403,6 @@ query-verb-ONLY and zero-wire or vendor-column-selection-only:
   ordering note). Additive result field: `noteCharsTruncated` (the
   truncated-field count; present only when > 0). Absent = the raw result
   bit-for-bit.
-- **`fieldsPreset: name` — the closed preset list.** A preset is
-  `{ resource, fields }` — hand-curated (NOT plan-derived: a curation
-  choice, same class as n8n-mcp.curation.json), resolved pre-walk to the
-  walk's `includeFields` (the vendor's column selection; `id` always
-  appended). The v1 list is CLOSED at the one preset the issue names:
-
-  | preset | resource | fields (14) |
-  |---|---|---|
-  | `billing_join` | `billing_items` | `companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable` |
-
-  `billing_join` is the billing-item join read: the FK columns that join a
-  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 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
@@ -3468,31 +3431,25 @@ query-verb-ONLY and zero-wire or vendor-column-selection-only:
   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
-  channel; the #64 fieldCache idiom), NOT against `MODEL_FIELD_SETS`
-  (the vendored-spec projection — a cheap NON-AUTHORITATIVE subset guard
-  only; the spec can lag the live API). The check runs in the live round
-  (`npm run live-smoke` — read-only, one field-catalogue read per preset;
-  a missing field FAILS the run), not in `npm test`. The v1 field list's
-  LIVE existence is verified there — the offline proof is the spec-subset
-  guard only (the review correction's mandate, the `fetchMany.liveFields`
-  live-first idiom).
-- **Refusals (pre-request, zero wire, typed):** unknown preset name (the
-  valid names are named — the closed-set discipline), preset/resource
-  mismatch (the preset and its resource are named), `fieldsPreset` + an
-  explicit `includeFields` (both are named — no silent precedence), and
-  `noteChars` `0` / negative / non-integer.
+- **Refusals (pre-request, zero wire, typed):** `noteChars` `0` /
+  negative / non-integer.
 - **Backwards compatibility:** both keys are OPT-IN on a closed bag —
   absent = the pre-#61 path bit-for-bit (the default-path zero-move is
-  pinned by the note-chars sidecar tests). New public exports:
-  `FIELD_PRESETS`, `FIELD_PRESET_NAMES`, `resolveFieldsPreset` and the
-  `FieldsPreset` type (additive; the public-surface gate passes as
-  additive-only). `UNTRUSTED_FIELDS_BY_RESOURCE` and
-  `noteCharsTruncationMarker` are internal. `src/untrusted.ts` is byte-identical
-  (the projection contract is untouched — the cap is a query-path
-  mechanism, not a projection change).
+  pinned by the note-chars sidecar tests). `UNTRUSTED_FIELDS_BY_RESOURCE`
+  and `noteCharsTruncationMarker` are internal. `src/untrusted.ts` is
+  byte-identical (the projection contract is untouched — the cap is a
+  query-path mechanism, not a projection change).
+
+**The `fieldsPreset` presets are removed (issue #287, 0.42.0).** The closed
+includeFields presets are gone — the `FIELD_PRESETS`, `FIELD_PRESET_NAMES`,
+`resolveFieldsPreset` and `FieldsPreset` exports and the bag key no longer
+exist, and a `fieldsPreset` in the bag is refused pre-request as an unknown
+key (the refusal names `includeFields`). The one preset v1 shipped —
+`billing_join` on `billing_items` — is now a plain column list:
+`companyID, ticketID, projectID, timeEntryID, contractServiceID,
+contractID, billingCodeID, expenseItemID, itemDate, quantity, rate,
+extendedPrice, totalAmount, nonBillable` — pass it as an explicit
+`includeFields` (`id` is always appended by the id-append).
 
 
 ### 11.24 The unbilled-work composite and the generic aggregate (issue #62)
@@ -3905,13 +3862,24 @@ returns the contract's reconciled P&L over a date window:
   catch-all/start, the provided-without-rate and fully-missing `missing`
   — never a silent zero — and `internalCost: 0` as a RESOLVED zero).
 
-### 11.27 Default label siblings on query, aggregate and fetch (issue #276)
+### 11.27 Label siblings on query, aggregate and fetch (opt-in, issue #287)
 
 Rows served by the invoke `<resource>.query` op (the bounded query), the group
 keys of `operations.aggregate`, and the found records of `operations.fetchMany`
-/ `operations.fetchByIds` carry label siblings **by default**, through the same
+/ `operations.fetchByIds` carry label siblings **when opted in** (issue #287:
+OFF by default — the label pass costs a field-catalog read plus up to 20 cold
+name reads per call, so a plain read returns raw ids), through the same
 `resolveCompositeNames` path the full-context composites use:
 
+- **The client option:** `labels: true` on the client config turns the label
+  siblings on for every read surface of that client (the MCP server sets it,
+  server-side).
+- **The per-call key:** `names: true` in the query bag / the aggregate opts /
+  the `fetchMany` / `fetchByIds` opts turns them on for that call; `names:
+  false` turns them off (even when the client has `labels: true`); ABSENT =
+  the client's option (the off default). A non-boolean `names` is refused
+  pre-request.
+
 | field on the row | sibling | example |
 |---|---|---|
 | a picklist field of the resource (catalog `isPickList`) | `<field>Label` | `status: 5` -> `statusLabel: "Complete"` |
@@ -3919,25 +3887,24 @@ keys of `operations.aggregate`, and the found records of `operations.fetchMany`
 | `ticketID` | `ticketIDName` = `"<ticketNumber> <title>"` | `"T20261001.0001 Printer down"` |
 | `resourceID` and every `*ResourceID` | `<field>Name` (staff name) | `assignedResourceIDName: "Ada Lovelace"` |
 
-- **Untrusted content:** every `*Name` value (and the alias) is vendor free text
+- **Untrusted content:** every `*Name` value is vendor free text
   outside the untrusted field registry, so the SDK caps it at 200 chars (the
   noteChars marker `… [+N chars truncated]`) and wraps it in
   `<untrusted_content>…</untrusted_content>` (embedded tags neutralised, the
   same `wrapUntrusted` the projection applies to `title`). Picklist `*Label`
   values stay raw (picklists are outside the untrusted class by the registry
   rule). Example: `contractIDName: "<untrusted_content>Managed Services 2026</untrusted_content>"`.
-- `assignedResourceName` is also written (same value as `assignedResourceIDName`):
-  a **deprecated alias**, still written in 0.39.0 (null with it, issue #282);
-  its removal is deferred to a later minor.
+- The `assignedResourceName` alias (0.39.0, issue #282) is removed (issue
+  #287) — read `assignedResourceIDName`.
 - Aggregate: `groups[].key.ticketIDName`, `groups[].key.statusLabel`, … (only the
   returned `top` groups are labelled).
 - A labelled field that is present in the row always gets its sibling (issue
   #282): a `null` value, a `0` id on any FK except `companyID` (never resolved: the node skips it and does not read a record; this is a node rule, not a vendor statement that 0 means "no reference"; `companyID: 0` is the tenant owner's own company and IS resolved, issue #306, verified live on one tenant, no other FK target probed has an id 0), an unknown id
-  (the vendor's not-found) or a capped id gets `null`, never a missing key and
-  never an error. Only a field absent from the row gets no sibling. Example:
+  (the vendor's not-found) or an id the cold-read cap left unlabelled gets
+  `null`, never a missing key and never an error. Only a field absent from the
+  row gets no sibling. Example:
   `{ contractID: null, contractIDName: null, assignedResourceID: null,
-  assignedResourceIDName: null, assignedResourceName: null, status: null,
-  statusLabel: null }`.
+  assignedResourceIDName: null, status: null, statusLabel: null }`.
 - A picklist value of `0` is looked up like any other value (issue #284): some
   picklists define it (live: contracts and projects `status` 0 = "Inactive",
   opportunities `status` 0 = "Not Ready To Buy", companies
@@ -3949,38 +3916,33 @@ keys of `operations.aggregate`, and the found records of `operations.fetchMany`
   SDK cannot tell the two apart. On a picklist the vendor does not serve at
   all, a 0 does get the reason row.) Any
   other value the served list lacks keeps its `reasons` row.
-- A failed field-catalog read (issue #284) leaves the picklist labels
-  unavailable, not absent, and the result says so: `names.catalogError`
-  (`{ code, message }`) plus a note. Picklist fields this client read from an
-  earlier catalog for the resource get a `null` `*Label` and a `reasons` row
-  (`PICKLIST_CATALOG_UNAVAILABLE_NOTE`). Before any successful read the
-  picklist fields are unknown (the live catalog is the only source of
-  picklist-ness), so no `*Label` is added and the note says that. When the
-  earlier read shows no picklist field is keyed in the rows, the failure cost
-  no label and no `names` summary is served. `*Name` siblings do not depend on
-  the catalog and are served as usual. Retry the call to label the picklists.
-- The resource `query()` iterator (the server's `output_path` walk) labels
-  each page the same way but has no result envelope, so it carries no `names`
-  summary: a capped id or a failed catalog read is not reported there. Use the
-  invoke `<resource>.query` op when the summary matters.
-- Opt out per call: `names: false` (query bag key, aggregate opts, fetchMany /
-  fetchByIds opts). A non-boolean `names` is refused pre-request.
+- A failed field-catalog read leaves the picklist fields UNKNOWN for the call
+  (the live catalog is the only source of picklist-ness): the `*Label` siblings
+  are simply absent and nothing is reported (the 0.39.x `catalogError` channel
+  was removed in issue #287). `*Name` siblings do not depend on the catalog and
+  are served as usual. Retry the call to label the picklists.
+- The resource `query()` iterator (the server's `output_path` walk) adds the
+  siblings to each page the same way when opted in but has no result envelope,
+  so it carries no `names` summary: the cold-read cap is not reported there
+  (a budget-exhausted id simply serves `null`). Use the invoke
+  `<resource>.query` op when the summary matters.
 - Caches: picklists ride the field cache, staff and record names the record
   cache (all default-on; invalidated as documented in §3 —
   a write through the client clears the affected resource's entries, TTL
   otherwise). A warm call costs zero extra vendor calls; a cold one costs one
   field-metadata GET for the resource plus one GET per distinct uncached id.
 - Cold-read cap: at most `DEFAULT_MAX_NAME_READS` (20) uncached name reads per
-  call (per resource for fetch batches). Ids over the cap get a `null` `*Name`
-  and the result carries a `names` summary — never silently unlabelled:
-  `names: { truncated: true, capped: N, note: "N id(s) left unlabelled (their *Name is null): the per-call cap of 20 uncached name reads was hit — …", reasons? }`.
-  `names` is also present (with `truncated: false`) when a picklist label could
-  not be resolved (`reasons` maps the field to why) or the field-catalog read
-  failed (`catalogError`). On `fetchMany` / `fetchByIds` `reasons` is keyed
-  `<resource>.<field>` (even when every item names one resource) and
-  `catalogErrors` lists every failing resource (`catalogError` is the first). Absent `names` = every sibling was resolved.
-  On the composite path a failed catalog read serves the same unavailable note
-  and a `catalogError` on the section, never the "retrying will not help" note.
+  call (per resource for fetch batches). The `names` summary appears ONLY when
+  something was left unlabelled — the cap was hit and/or a picklist label could
+  not be resolved: `{ note, reasons? }` (issue #287 trimmed the structured
+  `truncated` / `capped` / `catalogError` bookkeeping — the note is the
+  summary). Cap note: `"ids left unlabelled (their *Name is null): the
+  per-call cap of 20 uncached name reads was hit — names already read are
+  cached, so repeating or narrowing the call labels more"`. Unresolvable
+  picklists add a note clause and a `reasons` entry per field (the
+  field-catalog honesty note / the value-not-served note); on `fetchMany` /
+  `fetchByIds` the notes merge across resources and `reasons` keys the plain
+  field name. Absent `names` = every sibling was resolved.
 - Response size (full model, wrapped names): a tickets row grows ~40% (live,
   100 rows, 31 siblings per row, some of them null: 341,178 B -> 477,325 B;
   more when every FK is populated), a time_entries row ~77% (worst case, every

package/docs/LIVE-TESTING.md

@@ -1,8 +1,12 @@
 # Live testing (the morning run)
 
-The runbook for the REAL live run against an Autotask tenant. Reads
-credentials ONLY from the process environment. Nothing is committed, nothing
-is printed (the scripts emit env-var names only — verified by audit LIVE-1).
+The runbook for the REAL live run against an Autotask tenant. Credentials come
+from the process environment: the scripts autoload `./.env` (`AUTOTASK_ENV_FILE`
+overrides the path; variables already in the shell win), so the same values can
+be exported in the shell instead. Nothing is committed, and nothing sensitive
+is printed: the scripts emit env-var names only (verified by audit LIVE-1), and
+the `--dry` preflight prints a value-free summary — a length plus a 2-character
+prefix per value (shorter values print neither).
 The scripts FAIL CLOSED without credentials (exit 2) — a green exit is never
 a false pass.
 
@@ -13,8 +17,8 @@ a false pass.
   test old bytes; the check is newest-src vs oldest-dist mtimes, the
   `--allow-stale-dist` escape is explicit):
       npm run build
-- Credentials (values as placeholders — export in the SAME shell you run the
-  tests):
+- Credentials (values as placeholders — in `./.env`, or exported in the SAME
+  shell you run the tests; the shell wins):
       export AUTOTASK_TRACKING_IDENTIFIER="<your Tracking Identifier — Admin > API User Security>"
       export AUTOTASK_USERNAME="<your Username — API access must be enabled for that user>"
       export AUTOTASK_SECRET="<your Password/Secret — Admin > API User Security>"

package/docs/N8N-ADAPTER.md

@@ -151,7 +151,7 @@ Two sources in, markdown table out: the node repo (the ops column is re-derived
 | `ticketSecondaryResources` | TicketSecondaryResource | yes | create, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve |
 | `ticketWebhooks` | TicketWebhook | yes | get, getMany, delete | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
 | `tickets` | Ticket | no | create, get, getMany, slaHealthCheck, summary, timeline, update, count | slaHealthCheck → `tickets.slaHealthCheck`; summary → `tickets.summary`; timeline → `tickets.timeline` | changeStatus, count, create, findByTicketNumber, forResource, fullContext, get, getContext, getEntityInfo, getFieldInfo, getUdfInfo, lineOfBusiness, openWithNoteAndAssign, query, resolve, search, slaHealthCheck, statusSemantics, summary, timeline, update |
-| `timeEntries` | TimeEntry | no | create, update, get, getMany, getPosted, getUnposted, delete, count, createIfNotExists | createIfNotExists → `time_entries.createIfNotExists`; customRange → `time_entries.customRange`; getPosted → `time_entries.getPosted`; getUnposted → `time_entries.getUnposted`; last14 → `time_entries.last14`; last24h → `time_entries.last24h`; last30 → `time_entries.last30`; last7 → `time_entries.last7`; last90 → `time_entries.last90`; lastFullFortnight → `time_entries.lastFullFortnight`; lastFullMonth → `time_entries.lastFullMonth`; lastFullQuarter → `time_entries.lastFullQuarter`; lastFullWeek → `time_entries.lastFullWeek`; today → `time_entries.today`; yesterday → `time_entries.yesterday` | approve, count, create, createForResource, createIfNotExists, customRange, dateWorkedWindow, delete, get, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, moveToTicket, postedWithin, query, recentTickets, resolve, today, update, yesterday |
+| `timeEntries` | TimeEntry | no | create, update, get, getMany, getPosted, getUnposted, delete, count, createIfNotExists | createIfNotExists → `time_entries.createIfNotExists`; customRange → `time_entries.customRange`; getPosted → `time_entries.getPosted`; getUnposted → `time_entries.getUnposted`; last14 → `time_entries.last14`; last24h → `time_entries.last24h`; last30 → `time_entries.last30`; last7 → `time_entries.last7`; last90 → `time_entries.last90`; lastFullFortnight → `time_entries.lastFullFortnight`; lastFullMonth → `time_entries.lastFullMonth`; lastFullQuarter → `time_entries.lastFullQuarter`; lastFullWeek → `time_entries.lastFullWeek`; today → `time_entries.today`; yesterday → `time_entries.yesterday` | approve, count, create, createForResource, createIfNotExists, customRange, dateWorkedWindow, delete, get, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, moveToTicket, postedWithin, query, resolve, today, update, yesterday |
 | `timeEntryAttachments` | TimeEntryAttachment | yes | create, getMany, count, download, delete | download → `time_entry_attachments.download` | count, create, delete, download, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve |
 | `timeOffRequests` | TimeOffRequest | no | get, getMany, count, approve, reject | approve → `time_off_requests.approve`; reject → `time_off_requests.reject` | approve, count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, reject, resolve |
 | `(none — NOT IMPLEMENTED in node)` | InventoryProduct (StockedItemsAdd/Remove/Transfer pseudo-entities) | yes |  | stockedItemsAdd → `inventory_products.stockedItemsAdd`; stockedItemsRemove → `inventory_products.stockedItemsRemove`; stockedItemsTransfer → `inventory_products.stockedItemsTransfer` | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, stockedItemsAdd, stockedItemsRemove, stockedItemsTransfer, update |

package/docs/RELEASING.md

@@ -0,0 +1,121 @@
+# Releasing node-autotask
+
+Publishing happens only through `.github/workflows/release.yml`, which runs when a `v<version>` tag is pushed.
+Nobody (owner or agent) runs `npm publish` by hand. The day-to-day steps (version bump, merge, tag, confirm,
+record the plan hash) are the close-out checklist in [AGENTS.md](../AGENTS.md#5-close-out-autonomous-after-the-gates).
+This page covers the setup only the owner can do, the first CI release, and rollback.
+
+## Safeguards (no approval step)
+
+**Pushing a `v*` tag is the release.** The owner has delegated merge, tag and publish to agents: no
+per-release approval is requested. With approval removed, the only safeguards are the cadence gates in
+[AGENTS.md](../AGENTS.md) (green verify and CI, `y-pragent` all-clear on the final head, stronger-model QA,
+verified merge, the hard stops) and this workflow's own checks. A reviewer on the `release` environment, branch
+protection and a `v*` tag ruleset would add a hard gate, but need a GitHub plan that supports them on a private
+repo (see below). If agents are blocked from `gh pr merge` or tag pushes by the permission classifier, add
+Bash allow rules to `.claude/settings.json`: `gh pr merge *`, `git tag *`, `git push origin v*`,
+`gh release create *`.
+
+## What the workflows do
+
+- `ci.yml`: `npm ci`, then `npm run verify` with `COVERAGE=1`, so its single test run also enforces the coverage
+  thresholds. Runs on every pull request and push to `main`. On a pull request whose `package.json` version
+  differs from the base branch it also runs the release-consistency checks (`release:check`, plan hash
+  recorded, non-empty CHANGELOG section).
+- `release.yml` (on tag `v*`):
+  1. `verify` job (`contents: read`, no publish rights): `npm ci --ignore-scripts`; checks the tag is
+     annotated, equals `v` + `package.json` version, sits on `main`, has its plan hash recorded and a non-empty
+     `## [<version>]` CHANGELOG section; runs `release:check`, `clean` and `verify`; checks the tree is
+     unchanged; packs the tarball, records its sha256 and uploads it with the release notes.
+  2. `publish` job (`id-token: write` only, environment `release`): no checkout, no project install, no project
+     scripts, so no dependency code runs where a publish credential can be minted. Downloads the tarball, checks
+     its hash, then guards (public registry, not a prerelease, not below npm `latest`, skip if already on npm)
+     and runs `npm publish <tarball> --ignore-scripts --access public` via npm trusted publishing (OIDC).
+  3. `github-release` job (`contents: write`, after `publish`): `gh release create v<version>` with the
+     CHANGELOG section as notes.
+
+No `--provenance` while the repo is private: npm rejects it (E422), after already writing the signing entry to
+the public Rekor transparency log. When the repo goes public, add `--provenance` to the publish command.
+
+## Owner setup
+
+Labels below are as of writing; if a screen differs, check the current npm / GitHub UI and docs.
+
+### 1. npm trusted publishing (required)
+
+`release.yml` publishes with npm trusted publishing (OIDC): no long-lived token, so nothing to rotate or leak.
+Before the first CI release, on npmjs.com in the `node-autotask` package settings, add a GitHub Actions trusted
+publisher: user `msoukhomlinov`, repository `node-autotask`, workflow filename `release.yml`, environment
+`release`. npm must be >= 11.5.1 (the workflow installs exactly 11.5.1; bump it deliberately). Trusted publishing from a private repository works;
+only the provenance attestation is unavailable there (check the current npm docs if a screen differs). Until
+this is configured the publish step fails with an auth error before anything is published.
+
+After the first release succeeds this way, delete the old `NPM_TOKEN` secret (`gh secret delete NPM_TOKEN`),
+revoke the token on npmjs.com, and set the package's publishing access to disallow tokens.
+
+### 2. The `release` environment (optional, plan-dependent)
+
+`environment: release` is harmless when the environment does not exist: GitHub creates it, unprotected, on the
+first run. To make it a second gate, in Settings > Environments > `release`:
+
+1. Add yourself as a required reviewer. Leave "prevent self-review" off: agents push tags with your
+   credentials, so the run counts as triggered by you.
+2. Restrict deployments to tags matching `v*`.
+
+On a private repository, environment reviewers and deployment rules may need a paid plan: check the current
+GitHub docs.
+
+### 3. Branch and tag protection (needs GitHub Pro or a public repo)
+
+Branch protection and rulesets are not available on the current plan for this private repo (the API answers
+"Upgrade to GitHub Pro or make this repository public"). When they are:
+
+1. `main`: require a pull request and the `verify` check from `ci.yml`; block force pushes and deletion.
+2. Tags `v*`: restrict creation, update and deletion to yourself.
+3. `y-pragent` cannot be a required check (it posts comments, not an approving review or status); its
+   final-head all-clear stays a process rule (AGENTS.md step 3).
+
+**Residual risk until then:** anyone with write access can push a `v*` tag on a non-`main` commit and run
+*that commit's* `release.yml`, which can mint an OIDC publish credential (the on-`main` check lives in the
+workflow file, so a modified workflow can drop it). The npm trusted publisher is bound to the `release.yml`
+filename and the `release` environment, not to a branch, so this stays open until a deployment tag restriction or
+required reviewers exist on that environment. Keep write access to people and agents bound by AGENTS.md.
+
+### 4. GitHub Actions minutes
+
+CI runs on every PR and push to `main`; on a private repository that consumes the account's Actions minutes.
+
+## The first CI-driven release
+
+1. Confirm the npm trusted publisher is configured (setup 1); optionally set up the `release` environment.
+2. Run the cadence to close-out: release PR with the version bump and CHANGELOG heading, `y-pragent`
+   all-clear on the final head, stronger-model QA SHIP, merged; then the annotated tag on the merge commit is pushed.
+3. Watch the run (`gh run list --workflow release.yml`, `gh run watch`); approve the deployment if reviewers
+   are configured.
+4. Check `npm view node-autotask@<version> version` and `gh release view v<version>`.
+
+If the run fails:
+
+- **Before `npm publish`** (nothing published): a re-run uses the workflow file *at the tagged commit*. A
+  transient failure can be re-run as is. If the fix is in the workflow or the code, merge it to `main`, delete
+  the unused tag (`git push origin :refs/tags/v<version>` and `git tag -d v<version>`), and tag the new merge
+  commit with the same version. Only ever do this when `npm view node-autotask@<version>` shows nothing.
+- **After `npm publish`** (npm has the version but the run is red): re-run failed jobs; a re-run publish step sees the
+  version on npm and skips, then `github-release` runs. Or create the release by hand:
+  `gh release create v<version> --verify-tag --title v<version> --notes-file <CHANGELOG section file>`.
+- **A cancelled run** (a newer tag queued behind it): re-run it.
+- **Publish fails with an auth error**: the trusted publisher is not configured or does not match this repo,
+  workflow filename and environment (setup 1).
+
+## Rollback
+
+npm versions are immutable: never `npm unpublish` (it is restricted after 72 hours anyway, and the MCP server
+pins exact versions). Instead:
+
+1. Deprecate the bad version: `npm deprecate node-autotask@<bad> "<reason>; use <good>"`.
+2. If `latest` points at it, move the tag back: `npm dist-tag add node-autotask@<good> latest`.
+3. Ship the fix as a new version through the normal cadence (minor if the plan changed).
+4. Edit the GitHub release notes to point at the fix; do not delete a published version's git tag.
+5. Tell the MCP server repo (`msoukhomlinov/iit-mcp-autotask`) which version to pin.
+
+`npm deprecate` and `npm dist-tag` need an authenticated npm session with 2FA; they are owner actions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.40.0",
+  "version": "0.42.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,
@@ -114,7 +114,7 @@
     "coverage": "vitest run --coverage",
     "lint": "eslint src test",
     "lint:fix": "eslint src test --fix",
-    "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",
+    "verify": "npm run lockfile:check && npm run typecheck && npm run lint && npm run generate:check && npm run docs:render: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",
@@ -128,6 +128,7 @@
     "catalog:build": "node scripts/build-tool-catalog.mjs",
     "catalog:check": "node scripts/build-tool-catalog.mjs --check",
     "docs:render": "node scripts/render-docs.mjs",
+    "docs:render:check": "node scripts/render-docs.mjs --check",
     "mcp:check-surface": "node scripts/check-mcp-surface.mjs",
     "n8n:project": "node scripts/project-n8n-mcp.mjs",
     "n8n:project:check": "node scripts/project-n8n-mcp.mjs --check",