node-autotask 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-10-31
+
+The capability plan changed (a new operation row + a new MCP tool, a new error code on the aggregate and per-resource query rows, and new closed bag keys): this release needs a minor bump.
+
+### Breaking
+
+- **#287: row labels are off by default.** The `query()` iterator, the invoke `*.query` bag, the `operations.aggregate` group keys and `operations.fetchMany`/`fetchByIds` no longer add the `*Name`/`*Label` label siblings by default — the label pass (a field-catalog read plus bounded name reads) is not paid on every read. Restore the previous output with `names: true` per call, or with the new client-level `labels: true` option (`AutotaskClientConfig.labels`, default `false`) — a bag/opts `names` always wins over the client default. The MCP server (iit-mcp-autotask) enables the client option when it re-pins to this version (downstream handoff); until then the MCP surface loses every `*Name`/`*Label` sibling — enable client `labels: true` or pass `names: true` per call.
+- **#287: `operations.fieldCatalog` is compact by default when `fields` is absent** — field rows are the compact projection (`{ name, type, isPickList, isReference, udf }`; picklist values only with `labels: true` AND a `fields` filter). Pass `fields` for the full rows, or `compact: false` to force them; an explicit `compact` always wins. `maxBytes` remains the size cap.
+- **#287: `operations.fieldCatalog` rows drop `targetResource`/`targetEnumerable`** (plan-static extras). Reference enumeration: `operations.relationshipMap` / the plan's `referenceTargets`.
+- **#287: the `entityType` exports are removed** — `ENTITY_TYPE_TO_RESOURCE`, `isEnumerableResource` and `resourceForEntityType` are gone (no in-repo or server consumers).
+- **#287: the 0.39.x label plumbing is trimmed.** Removed: the `names.catalogError` / `names.catalogErrors` result fields, the `PICKLIST_CATALOG_UNAVAILABLE_NOTE` export, the per-client remembered-picklist fallback (a failed field-catalog read now yields plain null `*Label`s with the surviving honesty notes), the fetchMany `<resource>.<field>` reasons keying, and the composite catalog-failure notes. The null-sibling-key contract (null, never a missing key), the `*Name` + `*Label` shape, the FK-0 skip and the picklist-value notes are unchanged.
+- **#287: the `assignedResourceName` alias is removed** — use `assignedResourceIDName`.
+- **#287: the `fieldsPreset` bag key and the one `billing_join` preset are removed** — `fieldsPreset` is refused pre-request as an unknown key (the closed-bag refusal; the suggestion may point at `includeFields`). Pass `includeFields` explicitly: the preset was `["companyID", "ticketID", "projectID", "timeEntryID", "contractServiceID", "contractID", "billingCodeID", "expenseItemID", "itemDate", "quantity", "rate", "extendedPrice", "totalAmount", "nonBillable"]` on `billing_items.query`.
+- **#288: via INVOKE, the positional `get` trailing `{ fresh }` bag is refused** with a typed message naming the option — the `fresh` invoke option (`invoke(client, "<resource>.get", [id], { fresh: true })`) is the only spelling. The typed `client.<resource>.get(id, { fresh: true })` method signature is unchanged.
+- **#288: `in`/`notIn` comma-string coercion is fixed** — only canonical safe-integer tokens become numbers; ids above 2^53 and non-canonical tokens (`1e21`) stay strings, so one list can no longer carry an unsafe numeric id.
+
+### Added
+
+- **#287: `SCOPE_REQUIRED` — the unscoped-walk refusal** (a new stable error code, the `ScopeRequiredError` class): `operations.aggregate` group/sum with no filter is refused pre-request (zero wire) unless `acknowledgeUnscoped: true` is passed (count mode is unaffected — one vendor count, no walk), and the invoke `*.query` path spends one pre-flight `<resource>.count` when the walk would read over 500 rows with no id scope in the filter — a count over the threshold refuses with the typed code (`details.count`) before the walk. A failed or blind count fails open: the walk runs and the skip is named in the result's `scopeNote`.
+- **#287: `walk: { maxRows }` on the invoke query bag** (new closed key) — the bounded query serves at most `maxRows` rows in total; the page size stays `min(500, limit)`, so one vendor page may fetch more rows than `maxRows` and the surplus is sliced off (fetched, not served). The result's `truncated: boolean` — `false` only when the cursor is exhausted, `true` iff more rows exist past the cap (so an exact-multiple count with a live next page reports `true`); `operations.aggregate` results gain `truncated` too.
+- **#287: the self-relation prefix in query filters** — `<resource>.<field>` where the prefix equals the query's own resource key is the own field (identity strip, zero parent walk; the own field goes through the ordinary field-name check), so `ticket.<field>` on `tickets.query` works. Empty `exist`/`notExist` values were already accepted and are pinned by a test.
+- **#287: `operations.resolveAny` `match: 'auto'`** (staff resolve) — exact-first (the existing per-resource order), then on a miss a case-insensitive text CONTAINS on the resource's primary text field, bounded by the existing scan caps; exactly one match resolves, several yield `RESOLUTION_AMBIGUOUS` with the candidates, none yields the miss outcome. `match` defaults to `'exact'` (today's behaviour).
+- **#287: `operations.sanitiseResult(result, operation)`** — the projection-layer untrusted-content helper as an SDK surface (new MCP tool `autotask_sanitize_result`): one zero-wire call wraps the vendor free text of a RAW SDK result in the `<untrusted_content>` markers using the operation's own registry record (`metadata.untrustedFields`); an unknown operation is a typed refusal; a NEW object when the operation declares untrusted fields (the input is never mutated), the input returned unchanged (the same reference) when it declares none.
+- **#287/#288: the `suggestedAction` content moves into the SDK** — the field-name refusal is UDF-aware (a filter refusal on a UDF-capable resource carries the UDF remedy: filter the tenant field with `udf: true` — max 1 per query — its names and picklist ids via `operations.fieldCatalog` `include: ['udf']`, `labels: true`; the `fieldCheck: false` escape is for genuine vendor names only, never a UDF name; the includeFields refusal keeps the vendor-name remedy + escape), and the plain-5xx `suggestedAction` is the honest SDK-voice hint: 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. The MCP server deletes its rewrite layers and keeps the pass-through (the deterministic vendor-500 override is unchanged).
+
 ## [0.41.0] - 2026-10-30
 
 The capability plan changed (an operation row was removed): this release needs a minor bump.