node-autotask 0.13.0 → 0.14.0

package/docs/API.md

@@ -81,12 +81,19 @@ flow.
 Native global `fetch` (Node >= 24) — zero runtime dependencies across the
 whole package. `HttpClient.request<T>(opts): Promise<T>` is the single
 transport primitive (`RequestOptions { method, path, query?, body?, headers? }`):
-JSON bodies, retry with backoff on 429/5xx for idempotent requests (budget
-`maxRetries`), a concurrency guard (`maxConcurrent`, default 10 — the API
+JSON bodies, retries with backoff (budget `maxRetries`) in two legs (issue
+#105): a 429 (a pre-processing refusal — the vendor rejected the call before
+executing it) is retried per `Retry-After` on the pre-#105 retriable set
+(GET/PUT/DELETE + idempotent-flagged calls — an unflagged POST/PATCH surfaces
+a 429 at once, as before #105), while 5xx/network errors are auto-retried only
+for GET and idempotent-flagged calls: a mutation makes exactly one send on a
+5xx or network error (the write-outcome is unknown once the body was written);
+an explicit `idempotent: true` on a mutation opts back into the pre-#105
+auto-retry on both legs — plus a concurrency guard (`maxConcurrent`, default 10 — the API
 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/PUT/DELETE; set on the `/query` and `/query/count` POST reads, never on real writes). `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 — retried per policy on idempotent methods); 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 — retried per policy on the pre-#105 retriable set: GET/PUT/DELETE + idempotent-flagged calls); 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.
@@ -165,9 +172,13 @@ The issue-#1 projection helper as a standalone subpath
 (`import { markUntrusted } from 'node-autotask/untrusted'`) — ZERO runtime
 imports, so an MCP server (or any other consumer) can wrap vendor free text
 without pulling the SDK in. `wrapUntrusted(value)` returns
-`<untrusted_content>value</untrusted_content>` (idempotent — an already
-wrapped string is returned as-is; empty / non-string / null are untouched;
-the redaction marker `[REDACTED]` is never wrapped). `markUntrusted(record,
+`<untrusted_content>value</untrusted_content>` (idempotent — an exactly
+wrapped string, outer tags with a tag-free interior, is returned as-is;
+empty / non-string / null are untouched; the redaction marker `[REDACTED]`
+is never wrapped). Since issue #103 a pre-wrapped-LOOKING string whose
+interior contains wrapper tags is neutralised and wrapped exactly once —
+the old shape-based pass-through (which let vendor text pre-wrap itself and
+skip neutralisation) is gone. `markUntrusted(record,
 fields)` deep-copies one record and wraps ONLY the named top-level fields
 (`UNTRUSTED_OPEN` / `UNTRUSTED_CLOSE` are exported for exactness).
 `deepMarkUntrusted(value, fields)` walks an arbitrary tree (objects, arrays,
@@ -194,6 +205,21 @@ NEVER the values). The report is typed + JSON-serialisable; its messages
 are fixed templates (status codes, machine codes, zone names/hosts, counts)
 — never a vendor body, never a credential.
 
+### 1.11 `write-outcome.ts` — write-outcome classifier (issue #104)
+
+`classifyWriteOutcome(error: unknown): WriteOutcome` is the single documented,
+tested primitive that answers the question every unattended writer must answer
+after a failed write: did the write `fail` (definitely not applied — `notSent`
+local refusals, pre-send SDK-side refusals with no wire answer, 4xx, 429, a 500
+with a parseable non-empty vendor `errors[]`), is its outcome `unknown` (it may
+have been applied — timeouts,
+network errors, caller aborts, blocked edge redirects, 5xx without a parseable
+`errors[]`, unreadable 2xx bodies), and is it safe to retry (`unknown` is
+NEVER retryable). The Autotask vendor API has no idempotency-key support —
+every mutating operation is non-idempotent on the vendor side, so an
+`unknown` outcome is resolved by a read-back, never a blind resend. Full
+contract + row table: section 2.2.
+
 ## 2. Error hierarchy
 
 Every class throws with its stable machine code; the table maps class →
@@ -216,7 +242,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; idempotent methods retry per policy, a write makes ONE call — 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; the `#24` leg keeps the pre-#105 retriable set — an unflagged `PUT`/`DELETE` write CAN be auto-retried here, `POST`/`PATCH` make ONE call — section 2.1) |
 | `EmptyResponseError` | `EMPTY_RESPONSE` | server | 2xx (empty body, `expectBody`) | a blank 2xx on a call that expects a result (non-DELETE by default — section 2.1); `details = { httpStatus, method }` — retryable for non-DELETE (advisory: the loop never retries 2xx) |
 | `CircuitBreakerError` | `CIRCUIT_BREAKER_OPEN` | policy | — (call not sent) | the host circuit breaker (issue #26, opt-in) is open — refused LOCALLY before the request (zero upstream calls, no hourly stamp) — `notSent: true`, `retryAfter` = remaining open seconds — **retryable: true** (the deliberate divergence from #6's not-retryable cooldown refusal: the open period is bounded and advertised; section 3.2.2) |
 | `ResolutionError` | `RESOLUTION_AMBIGUOUS` / `RESOLUTION_TRUNCATED` / `NOT_FOUND` | resolution | — | `resolve`: multiple exact matches (candidates in `resourceIds`); a cap-tripped bounded client scan (`resolution.scanOnMiss` only; never a silent `null`); a numeric-id miss |
@@ -284,14 +310,17 @@ transport reads the header:
 | JSON-ish (`application/json*`, a plus-json suffix) | `INVALID_RESPONSE` (status quo — the #13/W-A7 shape-drift key; a wrong-shape 2xx is a shape-level failure, not a transport one) |
 | ABSENT | `INVALID_RESPONSE` (status quo — conservative; the maintenance-page premise carries a header) |
 
-Retry leg: a non-JSON 2xx on an IDEMPOTENT method (GET/PUT/DELETE + the
+Retry leg: a non-JSON 2xx on a pre-#105 retriable call (GET/PUT/DELETE + the
 idempotent-flagged `/query` POSTs) retries per the existing policy (same
 `Retry-After` / backoff / wait-budget rules as the 5xx leg) — the maintenance
-page is served by the EDGE, so the vendor never processed the request. A
-non-idempotent call (a create) makes ONE call and throws at once; its
-`suggestedAction` states the write may have taken effect (the #13 residue
-concern — writes are never auto-retried). An `INVALID_RESPONSE` 2xx (JSON-ish
-or header-less) is never retried — a real contract break is not transient.
+page is served by the EDGE, so the vendor never processed the request. This
+leg DELIBERATELY keeps the legacy set — issue #105 flips only the 5xx and
+network legs, so an unflagged `PUT`/`DELETE` write CAN be auto-resent here
+(its `suggestedAction` still notes the write may have taken effect — the #13
+residue concern; the residual tension with the #104 classifier, which pins
+`UNEXPECTED_CONTENT_TYPE` as unknown, is tracked in issue #109). An unflagged `POST`/`PATCH` call (a create) makes ONE call
+and throws at once. An `INVALID_RESPONSE` 2xx (JSON-ish or header-less) is
+never retried — a real contract break is not transient.
 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
@@ -333,6 +362,64 @@ with types, required and `maxLength`). Any other 5xx body is byte-identical to b
 per policy, `retryable: true`) — the phrase list is a heuristic over wording
 seen on real responses; widen it only with new live evidence.
 
+### 2.2 The write-outcome classifier (issue #104)
+
+`classifyWriteOutcome(error: unknown): WriteOutcome` (`src/write-outcome.ts`,
+exported from the package root — `import { classifyWriteOutcome } from
+'node-autotask'`) answers the question every unattended writer must answer
+after a failed write: did the write **fail** (definitely not applied), is its
+outcome **unknown** (it may have been applied), and is it safe to **retry**?
+Each consumer re-deriving the mapping from `notSent` / `httpStatus` /
+`retryable` risks getting it wrong — duplicate or lost writes. This is the one
+reviewed implementation, and the one place to update when vendor behaviour
+changes.
+
+```ts
+type WriteOutcome = {
+  state: 'failed' | 'unknown';
+  retryable: boolean;
+  code: string;
+  httpStatus?: number;
+};
+```
+
+Rows — evaluated in this order (`notSent` first, so a local 429 refusal that
+carries `notSent: true` is row 1, not row 3):
+
+| # | condition | state | retryable | why |
+|---|-----------|-------|-----------|-----|
+| 1 | `notSent === true` (the cooldown gate's / circuit breaker's local refusal) | `failed` | the error's own flag | the request never reached the vendor; the breaker's refusal retries the same call after the wait, the cooldown's is `retryable: false` (wait, then narrow the query first) |
+| 2 | `httpStatus` in 400..499 except 429 | `failed` | `false` | the vendor answered; the write is definitely not applied |
+| 3 | `httpStatus === 429` | `failed` | `true` | a pre-processing refusal — retry once the cooldown / Retry-After allows |
+| 4 | `httpStatus === 500` and `parseVendorErrors(vendorError)` returns a non-empty array | `failed` | `false` | a deterministic business-rule rejection — the same body fails identically on retry |
+| 5 | `code === 'TIMEOUT'` | `unknown` | `false` | the whole-call budget expired mid-flight |
+| 6 | `code === 'NETWORK_ERROR'` | `unknown` | `false` | conservative — the SDK cannot prove whether the body reached the vendor |
+| 7 | `code === 'ABORTED'` | `unknown` | `false` | the wire state at caller abort is unproven (the request may have been mid-flight) |
+| 8 | `code === 'REDIRECT_BLOCKED'` | `unknown` | `false` | the request left the client; an edge redirected before any vendor answer |
+| 9 | `httpStatus` 500..599 without a parseable non-empty `errors[]` | `unknown` | `false` | the vendor may have processed the write |
+| 10 | `code` in { `INVALID_RESPONSE`, `UNEXPECTED_CONTENT_TYPE`, `EMPTY_RESPONSE` } (an unreadable 2xx body) | `unknown` | `false` | the vendor answered but the result is unreadable — the outcome is unprovable |
+| 11 | a typed error with NO `httpStatus` that matches no row above (READ AS a pre-send LOCAL refusal: SDK-side validation / policy / confirmation / stale-object / boundary refusals, the client-side limiter) | `failed` | the error's own flag | the request never left the client — the write is DEFINITELY not applied; a limiter-style refusal frees later, a shape/policy refusal cannot be retried as-is. Note: a compound op can throw a status-less typed error AFTER an earlier send (e.g. `openWithNoteAndAssign`'s merge-read `NotFoundError`) — for a compound op resolve the outcome with a read-back instead of trusting `failed` |
+| 12 | not an `AutotaskError` (or a typed error no row above recognised) | `unknown` | `false` | conservative; `code` from the typed error's machine `code`, else the `Error.name`, else `UNKNOWN` |
+
+Invariants (pinned by `test/write-outcome.test.ts`): `unknown` implies
+`retryable === false`; the classifier never throws on arbitrary input
+(`null`, `undefined`, plain objects, plain `Error`, strings); it never
+mutates the error.
+
+**Non-idempotency (read before building a retry loop).** The Autotask vendor
+API has NO idempotency-key support and no conditional-write header. ALL
+mutating operations (every resource's create/update/delete, including the
+composite write ops) are NON-IDEMPOTENT on the vendor side. An `unknown`
+outcome MUST be resolved by a READ-BACK (GET the record, or query by a unique
+field), never by a blind resend — a blind resend of an applied write
+duplicates it.
+
+**Stricter than the error's own flag.** The classifier's `retryable` is the
+WRITER's decision surface and is intentionally STRICTER than the error's own
+`retryable` (which also serves read-path transport policy — e.g. a plain 5xx
+`ServerError` keeps `retryable: true` for the transport even though the
+classifier says unknown / never-retry for a write).
+
 ## 3. Configuration reference
 
 ### 3.1 Zone catalog (23 zones)
@@ -364,7 +451,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 | — | 429/5xx, idempotent requests only; 0 disables |
+| `maxRetries` | 3 | — | the client's retry budget, overridable per call (`InvokeOptions.maxRetries` / `MutationOpts.maxRetries`; `0` = exactly one send per request the call performs). The budget caps two legs (issue #105): the 429 leg (retried on GET/PUT/DELETE + flagged calls — unchanged) and the 5xx/network leg (GET + flagged only) |
 | `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 |
 | `maxResponseBytes` | 67 108 864 (64 MiB) | — | largest response body read; above it the call throws `RESPONSE_TOO_LARGE` (non-retryable) |
@@ -814,8 +901,9 @@ the mode pinned (§7.4). The governor rules (pinned):
 
 Dispatch calls the SAME typed method the SDK publishes, with the caller's
 `args` in positional order; for writes the governed `{ dryRun,
-lastModifiedDate? }` bag is appended as the method's final `MutationOpts`
-argument. Every guard that path has (bounded scans, the stale check, the
+lastModifiedDate?, maxRetries? }` bag is appended as the method's final
+`MutationOpts` argument (`maxRetries` = the per-call retry budget — see the
+§3.2 `maxRetries` row and the §2.2 classifier). Every guard that path has (bounded scans, the stale check, the
 dry-run envelope) is that path's — not a second implementation.
 `needsConfirmation(record)` exposes the refusal predicate.
 
@@ -824,8 +912,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: 926 read / 198 write / 54
-destructive of the 1178 ops). `invoke()` itself is UNCHANGED — the
+registry `effect`, verified one-to-one: 961 read / 198 write / 54
+destructive of the 1213 ops). `invoke()` itself is UNCHANGED — the
 programmatic escape hatch, its mode derived from the record, so it can never
 be cross-mode-refused.
 
@@ -841,7 +929,7 @@ be cross-mode-refused.
   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 1168 ops × 3 modes, zero wire).
+  all 1213 ops × 3 modes, zero wire).
 
 **Harness approval policy (recommended).** Require approval on every tool
 whose MCP annotation is `readOnlyHint !== true` — today exactly **254
@@ -1093,7 +1181,7 @@ const fold = await aggregate(client, 'time_entries.query', [{ field: 'dateWorked
 ## 8. Resource surface (128 resources)
 
 <!-- BEGIN GENERATED:api-per-entity -->
-Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page guarded), `queryBounded` (server-side pagination — one call walks the cursor until `limit` TOTAL records, default 500 / max 2500, with a `hasMore` flag; the MCP `query` surface, routed by `invoke`), `queryAll` (collect → `T[]` — the unbounded raw walk), `count`, `get` (id → record; `item: null` → `NotFoundError`), `create` / `update` / `delete` (where the vendor defines them — mutations take a `MutationOpts` bag: `{ dryRun, lastModifiedDate? }`), plus the helper floor where the plan declares it: `resolve` (all 121), `search` (40 — bounded contains on the resource text field), `getContext` (5 workflow resources), `findBy<Field>` (3), `createIfNotExists` (14). Entity metadata on every resource: `getEntityInfo`, `getFieldInfo`, `getUdfInfo` (UDF-capable 15). Parent-scoped children take `(parentId, id)` on the CRUD methods and require `parentId` on `createIfNotExists` (the scoped create POSTs the scoped collection; the dedup query stays global); `query`/`count`/`resolve`/`search` stay global (narrow with a `parentField` filter). Scoped `update` PATCHes the collection (the vendor keys the record by the id in the body).
+Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page guarded), `queryBounded` (server-side pagination — one call walks the cursor until `limit` TOTAL records, default 500 / max 2500, with a `hasMore` flag; the MCP `query` surface, routed by `invoke`), `queryAll` (collect → `T[]` — the unbounded raw walk), `count`, `get` (id → record; `item: null` → `NotFoundError`), `create` / `update` / `delete` (where the vendor defines them — mutations take a `MutationOpts` bag: `{ dryRun, lastModifiedDate?, maxRetries? }` (issue #105: `maxRetries` overrides the configured retry budget for every request the mutation issues; `0` = exactly one send per request)), plus the helper floor where the plan declares it: `resolve` (all 121), `search` (40 — bounded contains on the resource text field), `getContext` (5 workflow resources), `findBy<Field>` (3), `createIfNotExists` (14). Entity metadata on every resource: `getEntityInfo`, `getFieldInfo`, `getUdfInfo` (UDF-capable 15). Parent-scoped children take `(parentId, id)` on the CRUD methods and require `parentId` on `createIfNotExists` (the scoped create POSTs the scoped collection; the dedup query stays global); `query`/`count`/`resolve`/`search` stay global (narrow with a `parentField` filter). Scoped `update` PATCHes the collection (the vendor keys the record by the id in the body).
 
 | resource key | apiEntity | kind | tier | parent | standard ops present | special ops | mcpTool |
 |--------------|-----------|------|------|--------|----------------------|-------------|---------|

package/docs/LIVE-TESTING.md

@@ -218,7 +218,7 @@ Shutdown: SIGTERM (or Ctrl-C) — verified clean exit 0.
 | UNAUTHORIZED (401) | bad credentials, or AUTOTASK_ZONE not your tenant's zone | re-check the three exports verbatim against Admin > API User Security (in .env, SINGLE-QUOTE values containing $ — a shell-sourced double-quoted value expands $VAR and silently mangles the credential); confirm the zone with one `GET /V1.0/ZoneInformation?user=<username>` call (SDK: `client.zoneInformation.get()`) — every zone host forwards to the user's real zone |
 | FORBIDDEN (403) | the integration lacks the permission / impersonation not allowed | check Autotask admin settings; drop or fix AUTOTASK_IMPERSONATION_ID |
 | RATE_LIMITED (429) | vendor hourly/secondly budget (10k req/hour) | the SDK retries idempotent calls honoring Retry-After; if it persists, stop and wait |
-| SERVER_ERROR (5xx) / TIMEOUT / NETWORK_ERROR | vendor or flaky network | SDK retries GET/PUT/DELETE 3x (backoff + jitter); POST/PATCH never retried; re-run later |
+| SERVER_ERROR (5xx) / TIMEOUT / NETWORK_ERROR | vendor or flaky network | post-#105 the SDK auto-retries only GET + idempotent-flagged calls 3x on 5xx/network (backoff + jitter); mutations (POST/PATCH/PUT/DELETE) make one send — read back / verify before resending; the 429 leg is unchanged (GET/PUT/DELETE + flagged retry per `Retry-After`) |
 | NOT_FOUND | id absent, or wrong tenant/zone | verify the id exists in this tenant; verify the zone |
 | CONFIG_ERROR | zone typo, bad param shape, a shape the SDK refuses | read the message — it names the fix (unknown zone lists the 23; a bare conditions array says: wrap as { filter: [...] }) |
 | PAGINATION_LIMIT | a raw queryAll-style walk exceeded 1000 pages | the live scripts never issue raw walks (all reads are queryBounded); if you see it, it is your own code — use queryBounded with a small limit |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.13.0",
+  "version": "0.14.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 @@
     "lint:fix": "eslint src test --fix",
     "verify": "npm run typecheck && npm run lint && npm run generate:check && npm run build && node scripts/check-capabilities.mjs --ship && npm run mcp:project:check && npm run n8n:project:check && npm run catalog:check && npm run mcp:check-surface && npm run public-surface && npm run verify:pack && npm test",
     "plan:derive": "node scripts/derive-plan.mjs",
-    "generate:check": "node scripts/generate-batch.mjs --check",
+    "generate:check": "node scripts/generate-batch.mjs --check && node scripts/generate-batch.mjs --check --group B",
     "capabilities:build": "node scripts/generate-capabilities.mjs",
     "capabilities:check": "node scripts/check-capabilities.mjs",
     "clean": "rimraf dist coverage",