node-autotask 0.12.1 → 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 |
 |--------------|-----------|------|------|--------|----------------------|-------------|---------|
@@ -2608,7 +2696,9 @@ the plan change — a new registry op — is a minor at publish). One call
 returns the contract's reconciled P&L over a date window:
 
 - **`contracts.profitability(contractId, opts)` — the closed opts bag.**
-  `dateFrom`/`dateTo` are required (`YYYY-MM-DD`, `dateTo >= dateFrom`) and
+  `opts` itself is required (0.13.0 — the signature and the registry arg map
+  agree; a call without it is a pre-request `CONFIG_ERROR` naming the bag and
+  its `dateFrom`/`dateTo`). `dateFrom`/`dateTo` are required (`YYYY-MM-DD`, `dateTo >= dateFrom`) and
   the window is capped at 36 calendar months (the per-month windowing budget
   stays bounded; OQ1). `labourCostMethod` (default
   `billing_item_our_cost`; the closed 4-set
@@ -2627,7 +2717,8 @@ returns the contract's reconciled P&L over a date window:
   1..500) caps the ticket join set fed to the expenses + miscoding probe
   (sorted, first N, the `N of M` note) and the time-referenced ticket ids;
   `limit` (default 50, clamped 500) is
-  every part's `MaxRecords` + the capped lists. Validation collects the
+  every part's `MaxRecords` + the capped lists; `includeRows` (default
+  false, boolean) selects the output shape (below). Validation collects the
   COMPLETE problem list and throws ONE typed `CONFIG_ERROR` pre-request —
   zero wire on any malformed bag (the refusal table is house style: every
   message names the key + the valid values).
@@ -2745,13 +2836,17 @@ returns the contract's reconciled P&L over a date window:
   lands in its start month in one lump) ·
   `revenue_expected_unbilled = max(0, expected − the month's invoiced
   SERVICE lines)` (labour and charges never mask a missed recurring
-  invoice) · `unposted_time { entries, hours, value, absent? }` (billable
-  time with no billing item yet — derived from the billing join, never
-  getPosted/getUnposted; `value` = Σ `hoursToBill ×
+  invoice) · `unposted_time { entries, hours, hoursAbsent?, value, absent? }`
+  (billable time with no billing item yet — derived from the billing join,
+  never getPosted/getUnposted; `hours` = Σ `max(0, hoursToBill)`, or `null`
+  + `hoursAbsent: 'HOURS_TO_BILL_MISSING'` when any of the month's unposted
+  entries carries no numeric `hoursToBill` — unknown, never a summed 0; a
+  deliberate `hoursToBill: 0` stays 0; `value` = Σ `hoursToBill ×
   internalCurrencyContractHourlyRate` (fallback `contractHourlyRate`) on
   Time & Materials contracts only, else `null` + `absent:
   'NOT_TIME_AND_MATERIALS_CONTRACT'`, `'CONTRACT_TYPE_UNKNOWN'`, or
-  `'NO_CONTRACT_RATE'` when a role has no contract rate) · `labour_hours`
+  `'NO_CONTRACT_RATE'` when a role has no contract rate, or
+  `'HOURS_TO_BILL_MISSING'` on a T&M contract when the hours are unknown) · `labour_hours`
   (Σ `hoursWorked` over positive entries — the same rule as the cost) ·
   `labour_cost { total, unresolvedHours, rateSources }` (the per-month
   mirror of the ladder audit) · `tooling_cost { vendor, caller_supplied }`
@@ -2854,6 +2949,25 @@ returns the contract's reconciled P&L over a date window:
   rows with the divisions refused (`margin: null`, `break_even_hours:
   null`, `tooling_cost.vendor: null`, `revenue_expected: null`), all 11
   warnings at `count: 0`, zero tool failure.
+- **Summary-first output (0.13.0).** By default each of the 16 per-part
+  containers (`contractServices` … `subscriptions`) is a
+  `ProfitabilityPartDigest`: every stamp (`status`, `capped`, `hasMore`,
+  `note`, `blindSurface`, `emptyReason`, `absent`) plus `rows_fetched` (the
+  row count), WITHOUT the raw `items` array. Every computed figure is
+  returned either way — `monthly` (incl. `coverage_gaps`), `contract_type`,
+  `included_hours`, `currency`, the activity/costliest-ticket/miscoding/
+  renewal folds, `data_quality_warnings`, `costRateResolution`, `parts`,
+  `wires` — as are the `contract` and `customer` records. `includeRows: true`
+  returns the full `ProfitabilityPart<T>` containers (the pre-0.13.0 shape,
+  `items` included, no `rows_fetched`); the wire is identical in both modes.
+  The part fields are typed `ProfitabilityPart<T> | ProfitabilityPartDigest`
+  (both exported from the package root with the other option/result types):
+  narrow with `'items' in part` before reading rows, e.g.
+  `const rows = 'items' in res.billingItems ? res.billingItems.items : [];`.
+  On the 2-month test fixture the serialised result is 8,657 bytes without
+  rows vs 15,060 with them (−43%); the fixture rows are trimmed to a few
+  fields, so real vendor rows over a 12-month window make the rows the bulk
+  of the payload and the saving much larger.
 - **0.12.1 corrections.** The 0.12.0 folds counted the charge
   `billableAmount` (sell price) as recurring cost, read service `units` as
   included hours, joined every company CI's subscriptions and added a
@@ -2875,14 +2989,18 @@ returns the contract's reconciled P&L over a date window:
   subset is ticket/contact/company/resource/time_entry only).
 - **Test pins.** `test/resources/contracts.profitability.test.ts`: the
   hand-computed 2-month synthetic fixture (every figure derived from the
-  fixture rows; `wires.issued = 18` with the exact queue; every wire pinned
+  fixture rows; `wires.issued = 20` with the exact queue; every wire pinned
   in issue order; the structural exclusions + zero-mutating recorded paths;
   the ladder audit incl. the per-month `rateSources`; the 11 checks with
   exact counts/samples; the activity/highest-cost/miscoding/renewal folds;
   the per-month windowing (exact extra month queries, id-dedup, the
   still-full month note; `wires.issued` counts the expansion); the
   join-set/`limit` caps; the malformed-bag refusal table (one complete
-  problem list, zero wire); the contract NOT_FOUND; the 0.12.1 pins: the
+  problem list, zero wire); the contract NOT_FOUND; the summary-first pins
+  (the default digest = the full container minus `items` plus the
+  hand-counted `rows_fetched` per part, every computed figure equal across
+  modes, a non-boolean `includeRows` and a missing opts bag refused with
+  zero wire); the 0.12.1 pins: the
   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`).

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.12.1",
+  "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",