node-autotask 0.13.0 → 0.15.0

package/ARCHITECTURE.md

@@ -304,7 +304,7 @@ export interface AutotaskConfig {
   pageSize?: number;
   /** HTTP timeout in ms (whole-call budget). Default 30_000. */
   timeoutMs?: number;
-  /** Retry budget for idempotent requests on 429/5xx. Default 3 (0 disables). */
+  /** The client's retry budget (default 3; 0 disables auto-retry). Three legs, two rules (issues #105/#109): the 429 leg retries on the pre-#105 retriable set (GET/PUT/DELETE + idempotent-flagged calls); the 5xx/network leg and the non-JSON-2xx (#24) leg retry GET + idempotent-flagged calls only. A per-call override rides `InvokeOptions.maxRetries` / `MutationOpts.maxRetries`. */
   maxRetries?: number;
   /** Optional request log sink. Default: no-op. */
   logger?: Logger;
@@ -510,10 +510,36 @@ export interface RequestOptions {
    - `2xx` → parse JSON (if body present); empty body → resolve `undefined`.
    - non-2xx → throw via `errorFromStatus(status, body, url, operation)` (§10).
    - network/AbortError → `AutotaskNetworkError` / `AutotaskTimeoutError`.
-6. **Retries**: on `429`/`5xx`, retry up to `maxRetries` with exponential backoff + jitter
-   (base 200 ms, cap 30 s, honour `Retry-After`). Only **idempotent** methods are retried:
-   `GET`, `PUT`, `DELETE`; `POST`/`PATCH` are NOT (the parent-scoped `GET .../Approve` is a
-   `GET` and therefore retried like any GET; the `POST .../Reject` is not).
+6. **Retries** (issues #105/#109 — three legs, two rules, retry up to `maxRetries` with
+   exponential backoff + jitter, base 200 ms, cap 30 s, honouring `Retry-After`):
+   - **429 leg — UNCHANGED by #105.** A `429` is a **pre-processing refusal** (the
+     vendor rate limiter rejected the call before executing it); it is retried on the
+     pre-#105 retriable set — `GET`/`PUT`/`DELETE` + explicitly idempotent-flagged
+     calls (`IDEMPOTENT_METHODS`, kept exported for the public-surface baseline). A
+     429 on an unflagged `POST`/`PATCH` surfaces at once, exactly as before #105.
+   - **5xx / network leg — FLIPPED by #105.** Only `GET` and explicitly
+     idempotent-flagged calls retry; a mutation (`POST`/`PUT`/`PATCH`/`DELETE`) makes
+     exactly one send — the write-outcome is unknown once the body was written (the
+     #104 classifier: never blindly resend). An explicit `idempotent: true` on a
+     transport-level `RequestOptions` (not exposed on the mutation helpers) opts
+     back into the pre-#105 auto-retry on both legs. The parent-scoped
+     `GET .../Approve` is a `GET` and therefore retried like any GET; the
+     `POST .../Reject` is never retried on either leg — it is an unflagged `POST`, so a
+     `429` surfaces at once as well (`time_off_requests.reject` lists no retryable
+     statuses in the registry).
+   - **`#24` leg (non-JSON `2xx`, an edge maintenance page) — follows the write
+     rule (issue #109).** A `GET` / explicitly idempotent-flagged call retries; a
+     mutation makes ONE send and throws `UNEXPECTED_CONTENT_TYPE` with the residue
+     `suggestedAction`. The transport no longer assumes the edge served the page —
+     that premise is unprovable from the response, and the #104 classifier pins this
+     code as `unknown` for a write (never blindly resend). `idempotent: true` /
+     `maxRetries` remain the explicit opt-ins.
+   - **Per-call budget override:** `InvokeOptions.maxRetries` / `MutationOpts.maxRetries`
+     threads the transport's per-request override through a mutation (and its
+     auxiliary reads, e.g. a partial-update merge read); `0` = exactly one send per
+     request the call performs (default: the client's configured `maxRetries`). The
+     optional stale-object guard's verification read (only with a
+     `lastModifiedDate` token) keeps the client budget.
 7. **Concurrency guard**: an in-process semaphore bounds concurrent in-flight requests to
    `maxConcurrent` (default 10 — the API's limit; the node self-limits to 3 per endpoint
    under post-2023.1 guidance — the SDK default is the API limit and is configurable).
@@ -673,8 +699,12 @@ export function isAutotaskError(err: unknown): err is AutotaskError;
   GETs) return 200 with `{ item: null }`. The SDK converts that to `NotFoundError`
   (`category: not_found`, `httpStatus: 200`, `resourceIds: [id]`). This is the vendor's
   not-found signal and must not be surfaced as a successful empty record.
-- **Agent decision mapping** (fields, not string parsing): retry on `retryable: true`;
-  change input on `category: 'validation'` (`suggestedAction` names the field); ask the
+- **Agent decision mapping** (fields, not string parsing): retry on `retryable: true`
+  **for reads**; for a WRITE decide with `classifyWriteOutcome` (docs/API.md §2.2) — its
+  `unknown` state is never retryable and is resolved with a read-back (issues #105/#107:
+  the transport's `retryable` on a plain 5xx `ServerError` serves the read path, not the
+  writer); change input on `category: 'validation'` (`suggestedAction` names the field);
+  ask the
   user on `category: 'resolution'` with candidates in `resourceIds`; resolve a parent
   first on `category: 'validation'` with the missing parent in `resourceIds`; request
   approval on the registry's `flags.requiresApproval` / `effect: 'destructive'`; stop on
@@ -1118,6 +1148,12 @@ Floor (plan rows pre-declare it; G6 implements):
   candidates per resource).
 
 ### 19.3 Mutation safety
+- **Write outcome (issues #105/#107)**: a mutation makes EXACTLY ONE send on a
+  5xx/network error (two-leg retry policy, §8 "Behaviour" item 6 — a 429 is still retried on
+  the pre-#105 set). A writer classifying a write error uses
+  `classifyWriteOutcome` (docs/API.md §2.2): `failed` = definitely not
+  applied; `unknown` = outcome unprovable — resolve with a read-back, NEVER
+  a blind resend (the vendor offers no idempotency keys).
 - **Classification** (registry `effect` + `flags`, never one combined enum):
   `effect: read | write | destructive`; `flags: sensitive | idempotent | requiresApproval`.
   Plan defaults: `create` = write (non-idempotent), `update` = write + idempotent (PUT

package/MCP_TOOL_CATALOG.json

@@ -1,6 +1,6 @@
 {
   "generatedBy": "scripts/build-tool-catalog.mjs",
-  "generatedAt": "2026-10-16T10:52:08.623Z",
+  "generatedAt": "2026-10-17T13:48:44.078Z",
   "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
   "metaTools": [
     {

package/MCP_TOOL_MANIFEST.md

@@ -1,6 +1,6 @@
 # MCP Tool Manifest — node-autotask
 
-<!-- GENERATED by scripts/project-mcp-tools.mjs at 2026-10-16T10:55:23.945Z — do not hand-edit. -->
+<!-- GENERATED by scripts/project-mcp-tools.mjs at 2026-10-17T13:48:43.787Z — do not hand-edit. -->
 
 Mechanical MCP projection of the capability registry (generator-design section 7, ARCHITECTURE section 19.5).
 Tool names are the plan `mcpTool` columns (entity-first `autotask_<entity>_<verb>`); descriptions are the
@@ -947,7 +947,7 @@ singleton, so no helper tier is expected there; G8, 2026-09-26.)
 
 ## Meta
 
-- generatedAt: 2026-10-16T10:55:23.945Z
+- generatedAt: 2026-10-17T13:48:43.787Z
 - planHash: bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14
 - registry records: 1213
 - projected tools: 850

package/N8N_MCP_MANIFEST.json

@@ -1,6 +1,6 @@
 {
   "schema": "node-autotask n8n consumer mcp projection v1",
-  "generatedAt": "2026-10-16T10:52:08.458Z",
+  "generatedAt": "2026-10-17T13:48:43.907Z",
   "generator": "scripts/project-n8n-mcp.mjs",
   "inputs": {
     "capabilities": "capabilities.json (the capability registry — the single source of truth)",
@@ -3667,6 +3667,6 @@
     "approvalGatedWrites": 2,
     "destructiveExcluded": 3
   },
-  "capabilitiesHash": "9f78c2f6e0af82ae93710a8e024d3aefa54186b8c3b13178f856ac1120546244",
+  "capabilitiesHash": "fd92667b96dd9c74d9bbda2a34bf50b9791e2f236a6d2bb50b50a02a1d064882",
   "curationHash": "e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b"
 }

package/N8N_MCP_MANIFEST.md

@@ -1,6 +1,6 @@
 # N8N MCP Manifest — node-autotask (consumer projection)
 
-<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-16T10:52:08.458Z — do not hand-edit. -->
+<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-17T13:48:43.907Z — do not hand-edit. -->
 
 The n8n CONSUMER projection of the capability registry: the canonical source for what the
 n8n-side MCP tools must expose. The SDK is canonical — this is a projection of it, never a
@@ -282,6 +282,6 @@ only via a recorded change to `n8n-mcp.curation.json`.
 
 ## Meta
 
-- generatedAt: 2026-10-16T10:52:08.458Z
-- capabilitiesHash: 9f78c2f6e0af82ae93710a8e024d3aefa54186b8c3b13178f856ac1120546244
+- generatedAt: 2026-10-17T13:48:43.907Z
+- capabilitiesHash: fd92667b96dd9c74d9bbda2a34bf50b9791e2f236a6d2bb50b50a02a1d064882
 - curationHash: e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b

package/README.md

@@ -4,7 +4,7 @@ Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime
 dependencies. Built for building MCP servers and integrations.
 
 The SDK is also the **deterministic execution layer for agents** (ARCHITECTURE
-section 19): a generated capability registry (1177 operations across the 121-entity
+section 19): a generated capability registry (1213 operations across the 121-entity
 MVP set), a mechanical MCP substrate (registry → manifest → overrides → core tier +
 catalog meta-tool), and a write governor (dry-run-first, destructive
 confirmation). The SDK boundary also redacts response field values — the
@@ -397,9 +397,9 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    gains two server-category codes: `UNEXPECTED_CONTENT_TYPE` (a non-JSON 2xx
    whose `Content-Type` is not a JSON media type — the vendor maintenance
    page; `details` carries the content-type + a 256-byte truncated snippet
-   that the MCP servers wrap as untrusted host text; idempotent methods retry
-   per policy, a write makes ONE call and says the write may have taken
-   effect) and `EMPTY_RESPONSE` (a blank 2xx on a call that expects a result
+   that the MCP servers wrap as untrusted host text; a `GET` or an explicitly
+   `idempotent`-flagged call retries, a write makes ONE call and says the write
+   may have taken effect) and `EMPTY_RESPONSE` (a blank 2xx on a call that expects a result
    — `expectBody`, non-DELETE by default; `DELETE` / 204 keep `undefined` and
    the delete ops synthesize `{ id }` from the path id on a blank answer). A
    vendor field-validation 500 matching the documented phrases (`exceeds
@@ -477,7 +477,7 @@ node-parity paths the vendored swagger lacks, all UNVERIFIED-live this run), and
 | `npm run capabilities:check` | `scripts/check-capabilities.mjs` — the batch gate (missing/incomplete/stale records → exit 1) |
 | `npm run public-surface` | `scripts/public-surface.mjs` — capture (`--write`) / verify the public API surface baseline; default mode fails on unannounced removals, **and** checks the BUILT surface: every tsup entry has a matching `exports` key (and vice versa), every declared target was emitted and loads (ESM+CJS), and no runtime dependency leaks into `dist` |
 | `npm run live-smoke` | `scripts/live-smoke.mjs` — read-only live smoke: 5 vendor probes (5-6 wire calls worst case: 4 GET + 1 bounded query that may walk a 2nd, empty page) + a zero-network shape guard; `--dry` prints the plan with no calls (DRY-RUN-ONLY verdict, exit 0); live via `AUTOTASK_*` env — missing/partial credentials hard-fail exit 2 |
-| `npm run live-coverage` | `scripts/live-coverage.mjs` — the live coverage sweep over all 1172 registry ops (`--dry`: full call plan, no calls; live: bounded reads for real, mutations `dryRun: true` only — zero mutating requests, every governor-gated row (the 54 delete dry-runs included) routed through invoke with `confirm`; budget <= 1119 plan-honest / <= 1270 wire-honest worst case) |
+| `npm run live-coverage` | `scripts/live-coverage.mjs` — the live coverage sweep over all 1213 registry ops (`--dry`: full call plan, no calls; live: bounded reads for real, mutations `dryRun: true` only — zero mutating requests, every governor-gated row (the 54 delete dry-runs included) routed through invoke with `confirm`; budget <= 1159 plan-honest / <= 1311 wire-honest worst case) |
 | `npm run mcp:project` | `scripts/project-mcp-tools.mjs` — mechanical MCP projection → `MCP_TOOL_MANIFEST.md` (`:check` verifies) |
 | `npm run n8n:project` / `n8n:project:check` | `scripts/project-n8n-mcp.mjs` — the n8n consumer projection from the SAME registry → `N8N_MCP_MANIFEST.json`/`.md` (`--check` rebuilds and diffs; the gate is wired into `verify`) |
 | `npm run catalog:build` / `catalog:check` | `scripts/build-tool-catalog.mjs` — the catalog meta-tool row data → `MCP_TOOL_CATALOG.json` + mechanical CORE profile (`--check` verifies drift) |
@@ -526,9 +526,10 @@ thresholds: 90/90/80/90 (lines/functions/branches/statements). The public API
 surface baseline (`test/__fixtures__/public-surface.json`) proves "additive only":
 a captured name that disappears fails `public-surface`. The two live scripts
 (`live-smoke`, `live-coverage`) close the mocked-vs-live gap where credentials
-exist; this release both ran live against the AU03/ww29 tenant (live-smoke 6/6;
-full live-coverage sweep of all 1167 ops, 0 error rows) — the live path is
-VERIFIED-live for this release.
+exist; the live path has been verified end-to-end against a real tenant
+(live-smoke 6/6; a full live-coverage sweep with 0 error rows). Re-run both
+commands with your credentials to re-verify against your tenant — the mocked
+suites are the release gate, the live scripts are the ground-truth check.
 
 ## Roadmap