node-autotask 0.20.0 → 0.23.0

package/docs/API.md

@@ -1,6 +1,6 @@
 # API Reference — node-autotask
 
-> Generated from: `src/` (core modules), `src/errors.ts`, `src/config.ts`,
+> Generated from: `src/` (core modules), `src/errors/`, `src/config/`,
 > `src/pagination.ts`, `src/query.ts`, `src/operations/`, and the capability
 > registry (`capabilities.json` + `capabilities.plan.json`). The normative
 > architecture is `ARCHITECTURE.md`; this reference documents the public
@@ -49,7 +49,7 @@ Integration endpoints are on their own accessors: `authenticateResource.get()`
 `zoneInformation.get(user?)` (the swagger-required `user` query param
 defaults to the configured UserName — the vendor 404s the param-less call).
 
-### 1.2 `config.ts` — configuration + zone catalog
+### 1.2 `config/` — configuration + zone catalog
 
 `AutotaskConfig` / `ResolvedAutotaskConfig` + the 23-zone catalog
 (`ZONE_CATALOG`, `ZONES`, `DEFAULT_ZONE`), `zoneUrl()`, `resolveBaseUrl()`,
@@ -76,7 +76,7 @@ endpoint (`client.authenticateResource.get()` → `AuthTokenResultModel
 { authToken, expiration }`), which is a credential probe, not a stored-token
 flow.
 
-### 1.4 `http.ts` — HTTP transport
+### 1.4 `http/` — HTTP transport
 
 Native global `fetch` (Node >= 24) — zero runtime dependencies across the
 whole package. `HttpClient.request<T>(opts): Promise<T>` is the single
@@ -101,7 +101,7 @@ Every 2xx JSON body also passes through the response redaction transform
 (`redactResponseBody`, section 10) at this single choke point — secret fields
 always, personal/business-sensitive data by default.
 
-### 1.5 `errors.ts` — error hierarchy
+### 1.5 `errors/` — error hierarchy
 
 `AutotaskError` is the base: every error carries the structured contract —
 `code` (stable SCREAMING_SNAKE machine code), `category`, `retryable`,
@@ -593,7 +593,7 @@ diagnostic is appended as a separate field, and a 401 is still never retried.
 
 `circuitBreaker: { enabled: true }` opts into the optional circuit breaker
 at the transport (OFF by default — without it, behaviour is byte-identical
-to before; no env overrides — `src/config.ts` never reads `process.env`).
+to before; no env overrides — `src/config/` never reads `process.env`).
 Vendor health is HOST-scoped (a zone outage hits every tenant on that
 zone), so the key is the lowercased host of the resolved base URL
 (`buildBreakerKey` — the same derivation as `buildTenantKey`'s host part,
@@ -776,8 +776,11 @@ carry paging parameters.
     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
+    A re-asked "top N" within 30 s makes ZERO extra vendor count calls for
+    every CACHED probe (full-set AND threshold mode); a probe that answered
+    0 is deliberately re-wired (a 0 is never cached — see below), so a
+    threshold search that hit a 0 pays those probes again. 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
@@ -937,11 +940,18 @@ MCP-independent: no MCP imports, no zod.
 
 Bounded multi-resource text search. Runs each requested resource's OWN
 `search` helper (server-side bounded `contains` — never a listAll scan)
-across the selected resources with one limit budget. `resources` defaults to
-`WORKFLOW_RESOURCES`; `limit` defaults to 25 per resource, clamped to the
-vendor max of 500. Resources without a `search` helper are skipped and
-REPORTED (the `skipped` array), never errored. Returns
-`{ query, results: [{ resource, matches }], skipped }`.
+across the selected resources. `resources` defaults to `WORKFLOW_RESOURCES`;
+`limit` is **per resource** (default 25, clamped to the vendor max of 500), so
+a sweep over N resources can return up to N x `limit` matches. Optional
+`totalLimit` (positive integer) caps the whole sweep: resources are searched in
+request order, each asked for `min(limit, remaining)`; once the cap is met the
+rest are not queried and are listed in `notSearched`, and `truncated` is true
+when more matches may exist (a resource was not searched, or a searched
+resource returned exactly the quota it was asked for, `min(limit, remaining)`). Resources without a
+`search` helper are skipped and REPORTED (the `skipped` array), never errored.
+Returns `{ query, results: [{ resource, matches }], skipped }`; with
+`totalLimit` the result also carries `notSearched` and `truncated`, and
+without it the result is unchanged.
 
 ### 7.2 `resolveAny(client, identifier, opts?)`
 
@@ -1022,8 +1032,8 @@ dry-run envelope) is that path's — not a second implementation.
 The three MCP mode tools (`autotask_read` / `autotask_write` /
 `autotask_delete`) dispatch through the SAME router as `invoke` with the mode
 pinned (`InvokeMode = 'read' | 'write' | 'delete'`; the mode predicate is the
-registry `effect`, verified one-to-one: 961 read / 198 write / 54
-destructive of the 1213 ops). `invoke()` itself is UNCHANGED — the
+registry `effect`, verified one-to-one: 962 read / 198 write / 54
+destructive of the 1214 ops). `invoke()` itself is UNCHANGED — the
 programmatic escape hatch, its mode derived from the record, so it can never
 be cross-mode-refused.
 
@@ -1038,27 +1048,27 @@ be cross-mode-refused.
 - everything else is the governor's, unchanged: the dry-run-first default
   and the `confirm === <op key>` gate (all 54 deletes; the 3 approval-gated
   writes — inside `autotask_write` too) apply exactly as in `invoke`.
-  Pinned by the full-surface suite (`test/operations/invoke-modes.test.ts`:
-  all 1213 ops × 3 modes, zero wire).
+  Pinned by the full-surface suite (`test/operations/invoke/modes.test.ts`:
+  all 1214 ops × 3 modes, zero wire).
 
 **Harness approval policy (recommended).** Require approval on every tool
-whose MCP annotation is `readOnlyHint !== true` — today exactly **254
-tools**: the 252 dedicated write/delete tools (198 `effect=write` + 54
-`effect=destructive`, every one of them has a dedicated tool) +
-`autotask_write` + `autotask_delete`. The remaining **601 tools** (the 588
+whose MCP annotation is `readOnlyHint !== true` — today exactly **256
+   tools**: the 254 dedicated write/delete tools (198 `effect=write` + 56
+   `effect=destructive`, every one of them has a dedicated tool) +
+`autotask_write` + `autotask_delete`. The remaining **602 tools** (the 589
 dedicated read tools + the 10 core read tools + `autotask_read` +
 `autotask_catalog` + `autotask_describe`) all carry `readOnlyHint: true`
 and are safe ungated: every op they can route is `effect=read` (zero
 mutating requests — pinned by the test inventory, §6 of the split design).
-Refined class for the highest-risk ops: the **55 tools with
-`destructiveHint: true`** (54 dedicated delete tools + `autotask_delete`)
+Refined class for the highest-risk ops: the **57 tools with
+`destructiveHint: true`** (56 dedicated delete tools + `autotask_delete`)
 additionally require `confirm === <operation key>` even inside
 `autotask_delete`, and the 3 approval-gated writes
 (`configuration_items.moveConfigurationItem`, `contacts.moveToCompany`,
 `resources.transferOwnership`) require the same confirm inside
 `autotask_write`. Migration: `autotask_invoke` is REPLACED by
 `autotask_read`/`autotask_write`/`autotask_delete` — update harness config
-(approve the 254 above) and remove any `autotask_invoke` entry. The rule is
+(approve the 256 above) and remove any `autotask_invoke` entry. The rule is
 derivable from the registry `effect` column (and the mode tools' fixed
 annotations) — it never needs a hand-maintained name list.
 
@@ -1117,7 +1127,7 @@ const applied = await recovery(client, { resource: 'configuration_item_dns_recor
   preserved) + the boundary note in `warnings[]` (the SAME generated note
   `recovery` serves — the describe and dry-run channels cannot drift).
   Pinned by `test/operations/recovery.test.ts` (11 tests) + the full-surface
-  governor suite (`test/operations/invoke-modes.test.ts`).
+  governor suite (`test/operations/invoke/modes.test.ts`).
 
 ### 7.6 `fetchMany(client, items, opts?)` / `fetchByIds(client, items, opts?)` — bulk fetch by ids
 
@@ -1125,7 +1135,7 @@ Two cross-resource bulk reads with per-item typed results — one entry per
 input occurrence: `{ resource, id, found, value, error?: { code, httpStatus?,
 message } }`; a NOT_FOUND or fault on one item never aborts the rest; the
 result is `{ results, ok, failed }`. Both refuse pre-request (zero wire):
-non-numeric string ids (pointing at `autotask_resolve_any` — canonical
+non-numeric string ids (pointing at `operations.resolveAny` — canonical
 integer strings above 2^53 pass with their exact digits), parent-scoped
 children (their `get` needs `parentId`), unknown `fields` keys (the complete
 problem list in one message), unsafe number ids (the canonical-string
@@ -1201,7 +1211,7 @@ 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
-  are refused pre-request pointing at `autotask_resolve_any` (the
+  are refused pre-request pointing at `operations.resolveAny` (the
   complete problem list in one message, zero wire). Cap 500 per call
   (the pinned `EXPAND_RESOURCE_NAMES_MAX_IDS`; `opts.maxIds` may lower
   the cap, never raise it); over → `CONFIG_ERROR` pre-request, zero wire.
@@ -1300,6 +1310,79 @@ const n = await aggregate(client, 'billing_items.query', [{ field: 'companyID',
 const fold = await aggregate(client, 'time_entries.query', [{ field: 'dateWorked', op: 'gte', value: '2026-09-01' }], { groupBy: ['ticketID'], sum: ['hoursWorked'], top: 10 });
 ```
 
+### 7.9 `uiLink(client, input)` / `buildUiLink(input)` — Autotask UI deep links (issue #202)
+
+Pure, **zero-wire** builder of ExecuteCommand deep links:
+`https://ww<N>.autotask.net/Autotask/AutotaskExtend/ExecuteCommand.aspx?Code=<Command>&<Param>=<value>`.
+`input` is `{ entity, id | ticketNumber, host? }`; the op returns `{ url }`, or
+`{ url: null, reason }` when no UI host can be derived. Reachable as
+`operations.uiLink` through `invoke` / `autotask_read`; `buildUiLink` is the
+in-process helper (returns the URL or `undefined`; it also accepts `zone` /
+`baseUrl` to derive the host).
+
+| `entity` | Link |
+| --- | --- |
+| `time_entries` | `Code=EditTimeEntry&WorkEntryID=<id>` |
+| `tickets` | `Code=OpenTicketDetail&TicketID=<id>` or `&TicketNumber=<T…>` |
+| `tasks` | `Code=OpenTaskDetail&TaskID=<id>` |
+| `projects` | `Code=OpenProject&ProjectID=<id>` |
+| `companies` / `contacts` / `contracts` | `OpenAccount&AccountID` / `OpenContact&ContactID` / `OpenContract&ContractID` |
+| `configuration_items` | `Code=EditInstalledProduct&InstalledProductID=<id>` |
+
+- **Host derivation:** `ww<N>` comes from the client's live REST base
+  (`webservices<N>`); a base without `<N>` (`pre-release-de`/`-es`, a custom
+  host) yields no link — a host is never guessed. Pass `host: 'ww<N>.autotask.net'`
+  to name it.
+- **Safety:** ids are positive safe integers; `ticketNumber` must match
+  `^T\d{8}\.\d{4}$` and is only valid for `tickets`; exactly one of
+  `id` / `ticketNumber`; an unknown entity, bad id or bad host is a typed
+  `CONFIG_ERROR` naming the valid values — no vendor string is interpolated.
+- **Caveats:** the user must be logged in and their security level applies (a
+  link grants no access); ExecuteCommand opens a popup; an invalid query string
+  shows an error page; there is no `OpenTimeEntry` command. The op never checks
+  the record exists. Unverified live: the `ww<N>` ↔ `webservices<N>` mapping for
+  each catalog zone (`zoneInformation.get().webUrl` is the authority) and that
+  `WorkEntryID` equals the REST time-entry `id`.
+
+
+### 7.10 `moveToTicket` — governed create-verify-delete moves (issue #197)
+
+`time_entries.moveToTicket(sourceId, toTicketId, opts)` and
+`ticket_charges.moveToTicket(sourceId, toTicketId, opts)` re-parent a record the
+vendor will not re-parent by update (probed live: an update of `ticketID`
+returns success and keeps the old value). Both run on one shared engine
+(`src/resources/special/_shared/move-engine.ts`); notes are different —
+`ticket_notes` update with a new `ticketID` (parent-scoped) does move a note, and
+notes cannot be deleted, so they never use create-then-delete.
+
+- **Governed:** effect `destructive`; dry-run first (a GET-only preview that
+  returns the create payload); apply needs `dryRun: false` and
+  `confirm: '<resource>.moveToTicket'`. Options: `maxSourceAgeDays` (default 14,
+  lowerable never raised), `lastModifiedDate` (stale guard), `maxRetries` (reads only).
+- **Hard invariants (typed `MOVE_*` refusal, zero writes, re-run at apply):**
+  source exists and is on a ticket (task/internal refused), target exists and is
+  open, target differs from the source ticket, source not billed/posted
+  (`billing_items` by `timeEntryID`; unreadable fails closed) or approved, no
+  attachments (a delete destroys them), not older than the age limit, and no twin
+  already on the target (checked in the preview and again immediately before the POST).
+- **Apply order:** POST (once, never retried) -> read the new record back and compare
+  -> re-read the source (any drift rolls the new record back) -> DELETE the source.
+- **Result:** `{ status: 'moved' | 'moved_source_absent' | 'moved_manual_delete',
+  sourceId, newId, correlationId, snapshot, facts, manualAction? }`. Every other
+  outcome throws `MoveRefusedError` whose `details.status` is `failed` (nothing
+  changed), `partial` (both records exist) or `unknown`; details carry ids, never values.
+  The SDK stores nothing — persist `snapshot` if you need it.
+- **Manual GUI path:** a refusal that a person can finish in the UI (billed,
+  approved, attachments, too old) and a source delete the vendor refuses carry
+  `manualAction: { action: 'delete_source', uiLink, reason }`. `uiLink` is an
+  `operations.uiLink` deep link: the time entry itself (its edit page), or the
+  parent ticket for a charge (no ExecuteCommand code exists for charges). It is
+  `null` when no UI host can be derived from the client base.
+- **Caveats:** the new record gets a fresh create date and creator; creating and
+  deleting may trigger notifications, SLA and workflow rules the API cannot
+  suppress; vendor acceptance of the create is not validated by a dry run.
+  Contract fields are copied only when the target ticket has the same company and contract.
+
 ## 8. Resource surface (128 resources)
 
 <!-- BEGIN GENERATED:api-per-entity -->
@@ -1541,7 +1624,7 @@ cannot drift from the plan):
 - `EMPTY_REASON_STAMPS` (issue #14) — resource → op → the typed empty-reason
   `{ surface, kind, note, authority, remedy }` (`plan.emptyReasons`, the
   ww29-sweep-pinned 184 rows): the runtime lookup `base.ts` attaches to
-  0/empty count/query results + the update dry-run envelope, and `http.ts`
+  0/empty count/query results + the update dry-run envelope, and the HTTP transport (`src/http/`)
   attaches to the typed error's `details` (the SAME generated data the plan
   serves — the result channel and the plan cannot drift). The
   `blind-surface` kind is ABSENT by design: `base.ts` synthesizes it from
@@ -1703,15 +1786,16 @@ resource paths, of which **40** expose a create op (the stampable set; the
   the validation-layer spelling `InternallAllocationCodeID` is rejected by the
   deserializer (key oracle, S9b §5: the gate-1 error text names the validation
   layer, not the body key).
-- **2026-10-06 vendor drift (confirm-100)**: the vendor now refuses ALL
-  time-entry writes for this API-only user with
-  "API-only user cannot be selected for this field" — `create` **and**
-  `createForResource` (stage-11 proven, 8 live creates 2026-10-04) alike.
-  The wall is vendor eligibility, not missing tenant data: valid (resource,
-  role) pairs exist in the tenant (postedWithin rows: resourceID
-  31131373 / 29869529 with roleID 29682834) but belong to human resources
-  the API user cannot select. Unsatifiable for an API-only integration
-  user; the typed W-A3 pointer note carries this.
+- **2026-10-06 vendor drift (confirm-100), re-scoped 2026-10-21 (#195)**: a
+  (resource, role) pair that selects the API-only user's own resource was
+  refused with "API-only user cannot be selected for this field" — `create`
+  and `createForResource` (stage-11 proven, 8 live creates 2026-10-04)
+  alike. This is a pair-scoped wall, not a blanket refusal: live
+  `time_entries.create` calls succeeded on 2026-10-21 (pair not recorded);
+  the authorised pair set has NOT been re-adjudicated by a live probe. Valid
+  (resource, role) pairs exist in the tenant (postedWithin rows: resourceID
+  31131373 / 29869529 with roleID 29682834). The typed W-A3 pointer note
+  carries this.
 
 ### 11.5 Company-create side effect
 
@@ -1728,7 +1812,7 @@ redacted `vendorError` naming the offending field and a deterministic
 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.ts` sets `retryable: true` for `SERVER_ERROR` and for every
+(`src/errors/` sets `retryable: true` for `SERVER_ERROR` and for every
 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`:
@@ -1823,7 +1907,7 @@ synthesis. The 9 registry-backed records — `tickets` / `companies` /
 `.create` + `time_entries.create` / `time_entries.createForResource` — render
 the override verbatim, and every example passes its own record's `inputSchema`
 (the governor dispatch validator; pinned by
-`test/scripts/mcp-surface-guidance.test.ts`). The `configuration_items`
+`test/scripts/mcp-surface/create-examples.test.ts`). The `configuration_items`
 body documents the §11.3 product wall, not a working create;
 `time_entries.create` points at `createForResource` (the linkage-aware
 method). The plan's 12-target list also names `tickets.createIfNotExists`,
@@ -1917,9 +2001,9 @@ so the answer to "why is this empty?" is data, not speculation:
   (`ticket_history.query` W1: the vendor requires exactly ONE ticketID-eq
   filter — unfiltered 500s by contract; WITH the filter the query WORKS
   (live 2026-10-06) → `tickets.timeline` / `tickets.fullContext` stay the
-  composites; `time_entries.create` W-A3: the API-only-resource wall
-  ("API-only user cannot be selected for this field" — 2026-10-06 drift,
-  `createForResource` walled by the same drift); `authenticate.get` W2:
+  composites; `time_entries.create` W-A3: the pair-scoped wall on the
+  API-only user's own resource ("API-only user cannot be selected for this
+  field" — 2026-10-06; creates succeeded 2026-10-21, pair not recorded); `authenticate.get` W2:
   designator-only;
   `time_entries.getPosted` / `time_entries.getUnposted` W-D3: this zone's
   TimeEntry entity exposes no posted-state filter field — the working read
@@ -2455,7 +2539,7 @@ what makes it usable as a recovery signal from inside the client.
   lifetime, like a cache); no change to the served MCP/n8n text (transport
   behaviour, like #34).
 
-Pins: `test/transport-zone-reresolve.test.ts` (11 pins, mock wire only —
+Pins: `test/transport-zone-reresolve/*.test.ts` (11 pins, mock wire only —
 no vendor wire in tests; the 10 issue-required + the breaker probe
 host-pinning pin).
 
@@ -2599,6 +2683,17 @@ TIME"). A `fresh: true` call closes the gap immediately: it bypasses
 BOTH the name cache and the ReadCache and refreshes both, so the rename
 is served on the very next fresh call (issue #77).
 
+**Per-part projection (issue #200)**: `companies.fullProfile` accepts
+`fields?: { locations?, contacts?, notes?, projects?, openTickets? }` — each a
+non-empty list of exact vendor field names — and `locationLimit?: number`
+(default 50, 1-500). A listed part serves ONLY those fields (sent as
+`IncludeFields`, then picked client-side); an absent part keeps the full model,
+and without `fields` the call and result are unchanged. An unknown part key, an
+empty/non-array list or a field name unknown to the part's vendored field
+catalog is a typed `CONFIG_ERROR` before any request. `capped`, `absent` and
+`parts` semantics are unchanged; with `names: true` the siblings appear only for
+the id fields you kept.
+
 **Composite wiring (issue #77)**: the full-context composites
 (`tickets.fullContext`, `companies.fullProfile`,
 `configuration_items.profile`, `projects.getContext`) accept an
@@ -3152,12 +3247,12 @@ returns the contract's reconciled P&L over a date window:
   `effect: 'read'`, `dryRun: false`, the closed-bag `inputSchema` (the
   signature-audited arg map in `scripts/lib/args-derive.mjs`); the emitted
   method delegates to the hand-written special module
-  (`src/resources/special/contracts.ts`). The MCP projection serves
+  (`src/resources/special/contracts/profitability.ts` and its `profitability.*.ts` siblings). The MCP projection serves
   `autotask_contract_profitability` (catalog + manifest); the N8N
   manifests legitimately EXCLUDE the op — `contracts` is not an n8n
   curated entity (the curation rule is evidence-based: the daily support
   subset is ticket/contact/company/resource/time_entry only).
-- **Test pins.** `test/resources/contracts.profitability.test.ts`: the
+- **Test pins.** `test/resources/contracts.profitability.*.test.ts` (revenue, rate-ladder, cost-ladder, bounds, warnings): the
   hand-computed 2-month synthetic fixture (every figure derived from the
   fixture rows; `wires.issued = 20` with the exact queue; every wire pinned
   in issue order; the structural exclusions + zero-mutating recorded paths;
@@ -3174,7 +3269,7 @@ returns the contract's reconciled P&L over a date window:
   charge cost/period-type/line-type classifiers, the Block Hours
   `contract_blocks` path, T&M unposted pricing + the time-referenced old
   ticket, the exclusive window ends, the month-level `coverage_gaps`).
-  `test/resources/profitability-degradation.test.ts`: the empty-tenant
+  `test/resources/contracts.profitability.degradation.test.ts`: the empty-tenant
   13-wire suite (every part degrades, zero tool failure), the dangling
   customer FK, the non-404 customer fault (`absent`), a bounded-part fault
   (`absent` + `coverage_gaps`, the call resolves), the resources blind-list get-fallback (rung 3 from the

package/docs/N8N-ADAPTER.md

@@ -16,11 +16,11 @@ knowledge**:
 | entity catalog (138 entity metadata entries, 121 resource dirs) | `constants/entities.ts` + `resources/<dir>/description.ts` | the SDK's 128 resource accessors + the capability registry (`capabilities.json`) |
 | per-entity operations (get/getMany/count/create/update/delete + specials) | `resources/<dir>/execute.ts` switch cases | SDK primitive + helper operations, one per registry row |
 | auth (3 headers + optional impersonation) | `helpers/http/headers.ts` | `src/auth.ts` (swagger casing) + fail-closed config |
-| zone catalog (23 zones) | the node credential definition | `src/config.ts` `ZONE_CATALOG` |
+| zone catalog (23 zones) | the node credential definition | `src/config/zones.ts` `ZONE_CATALOG` |
 | pagination (nextPageUrl cursor walk, `PAGINATION.MAX_PAGES` = 1000) | `helpers/pagination.ts` | `src/pagination.ts` (same cursor-follow walk — POST the filter to the absolute `nextPageUrl`, rebased to the client base URL — + 1000-page guard) |
 | filter grammar (13 operators + and/or, caps) | `constants/filters.ts` | `src/query.ts` |
-| envelopes (item/page/operation/count unwrapping) | `helpers/request.ts` + per-op unwrapping | `src/http.ts` + the pinned envelopes in the registry |
-| error mapping | `errorHandler` + `error.constants` | `src/errors.ts` (the class → code → status hierarchy) |
+| envelopes (item/page/operation/count unwrapping) | `helpers/request.ts` + per-op unwrapping | `src/http/envelope.ts` + the pinned envelopes in the registry |
+| error mapping | `errorHandler` + `error.constants` | `src/errors/` (the class → code → status hierarchy) |
 | dry-run / stale / audit guards | inline per operation | `src/operations/invoke.ts` governor + the pinned `DryRunResult` envelope |
 
 What remains in the node is the **n8n wiring**: credential UI, trigger

package/examples/mcp/errors.ts

@@ -0,0 +1,135 @@
+/**
+ * errors.ts — result shaping: the structured success/DRY results and the
+ * typed error payload (the SDK AutotaskError contract, served verbatim).
+ */
+import type { AutotaskError } from 'node-autotask';
+import { unknownKeysRefusal } from 'node-autotask/operations';
+import {
+  UNTRUSTED_CLOSE,
+  UNTRUSTED_CLOSE_NEUTRALISED,
+  UNTRUSTED_OPEN,
+  UNTRUSTED_OPEN_NEUTRALISED,
+  wrapUntrusted,
+} from 'node-autotask/untrusted';
+import type { ToolReturn } from './types.js';
+
+export const DRY_NOTE = 'No Autotask credentials in the environment (set AUTOTASK_TRACKING_IDENTIFIER, AUTOTASK_USERNAME, AUTOTASK_SECRET, optionally AUTOTASK_ZONE). The call was validated and NOT issued.';
+
+/** A successful structured result. `outputSchema` describes `structuredContent`. */
+export function ok(text: string, structuredContent: Record<string, unknown>): ToolReturn {
+  return { content: [{ type: 'text', text }], structuredContent };
+}
+
+/** A DRY-mode structured result (no request was issued). */
+export function dryResult(opId: string): ToolReturn {
+  return ok(`DRY mode — "${opId}" was NOT issued (no credentials in the environment).`, { dry_mode: true, operation: opId, note: DRY_NOTE } satisfies Record<string, unknown>);
+}
+
+/** Surface the SDK error contract so a model can self-correct: what failed, whether to retry, what to do next. Credentials never appear in an error message.
+ *
+ * `details` is passed through verbatim (issue #9/#14): the additive
+ * machine-checked extras — the typed `emptyReason` / `pointerNote` on a
+ * plan-pinned op's failure, the `operations.recovery` refusal payload
+ * (`candidateIds` / marker info), the #13 shape-drift extras — ride the
+ * served payload exactly as they do on the typed client's `AutotaskError`.
+ * The content is plan-derived (or the caller's own echoed token): never a
+ * credential, never free vendor prose beyond the already-published notes.
+ *
+ * Issue #24: `details.bodySnippet` is the ONE host-sourced free-text value
+ * that can ride the details (a host-supplied baseUrl can serve arbitrary HTML
+ * as the UNEXPECTED_CONTENT_TYPE snippet) — when `untrustedWrap` is on,
+ * exactly that value is wrapped in `<untrusted_content>`; the rest of the
+ * details stays verbatim (machine-checked / plan-derived).
+ *
+ * `vendorError` (issue #33): the deep-redacted vendor body rides the served
+ * payload (it is set upstream by `errorFromStatus` — redaction already ran
+ * before the payload is built). A STRING body is host-sourced free text and
+ * gets the SAME `<untrusted_content>` treatment as `details.bodySnippet`
+ * (wrapped when `untrustedWrap` is on, served raw when off); a parsed
+ * (non-string) body is a redacted copy — served structured, and with
+ * `untrustedWrap` on its string leaves get the SAME marker neutralisation
+ * `wrapUntrusted` applies, so a vendor body cannot forge a wrapper boundary.
+ * Absent or empty body → NO `vendorError` key: the unpinned payload stays
+ * byte-identical on the wire (an undefined key drops out of the JSON text).
+ */
+/**
+ * Issue #33 QA minor: a parsed (non-string) vendor body is served structured, so
+ * `wrapUntrusted` cannot wrap it as a whole. With `untrustedWrap` on, apply the
+ * same marker neutralisation to every string leaf instead — a vendor body
+ * containing the literal wrapper markers cannot forge a boundary.
+ */
+function neutraliseParsedMarkers(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value
+      .split(UNTRUSTED_OPEN)
+      .join(UNTRUSTED_OPEN_NEUTRALISED)
+      .split(UNTRUSTED_CLOSE)
+      .join(UNTRUSTED_CLOSE_NEUTRALISED);
+  }
+  if (Array.isArray(value)) return value.map(neutraliseParsedMarkers);
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) out[k] = neutraliseParsedMarkers(v);
+    return out;
+  }
+  return value;
+}
+
+export function errorContent(err: unknown, untrustedWrap = false): ToolReturn {
+  const e = err as Partial<AutotaskError> | undefined;
+  const message = err instanceof Error ? err.message : String(err);
+  let details = e?.details;
+  if (
+    untrustedWrap &&
+    details !== undefined &&
+    details !== null &&
+    typeof (details as Record<string, unknown>).bodySnippet === 'string'
+  ) {
+    details = {
+      ...(details as Record<string, unknown>),
+      bodySnippet: wrapUntrusted((details as Record<string, unknown>).bodySnippet),
+    };
+  }
+  // issue #33: the redacted vendor body under a fixed key (absent/empty →
+  // undefined → no key on the wire — see the doc block).
+  const vendorErrorRaw = e?.vendorError;
+  const vendorError: unknown =
+    typeof vendorErrorRaw === 'string'
+      ? vendorErrorRaw === ''
+        ? undefined
+        : untrustedWrap
+          ? wrapUntrusted(vendorErrorRaw)
+          : vendorErrorRaw
+      : vendorErrorRaw !== undefined && vendorErrorRaw !== null
+        ? untrustedWrap
+          ? neutraliseParsedMarkers(vendorErrorRaw)
+          : vendorErrorRaw
+        : undefined;
+  const payload = {
+    error: true,
+    code: e?.code,
+    category: e?.category,
+    retryable: e?.retryable,
+    httpStatus: e?.httpStatus,
+    operation: e?.operation,
+    vendorError,
+    suggestedAction: e?.suggestedAction,
+    correlationId: e?.correlationId,
+    resourceIds: e?.resourceIds,
+    details,
+    message,
+  };
+  return { content: [{ type: 'text', text: JSON.stringify(payload) }], isError: true };
+}
+
+/**
+ * The handler-side typed refusal for a tool call (issue #3). Runs the
+ * SDK's shared closed-set check (`unknownKeysRefusal`) against the tool's
+ * valid top-level keys and, on a refusal, serves the full error contract
+ * through the same `errorContent` path the rest of the refusals use.
+ * Returns null when every key is known (no refusal).
+ */
+export function closedArgsError(raw: unknown, validKeys: readonly string[]): ToolReturn | null {
+  const refusal = unknownKeysRefusal(raw, validKeys, 'argument');
+  return refusal === null ? null : errorContent(refusal);
+}