node-autotask 0.39.4 → 0.41.0

package/README.md

@@ -4,8 +4,8 @@ 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 (1281 operations across the 121-entity
-MVP set), a mechanical MCP substrate (registry → manifest → overrides → core tier +
+section 19): a generated capability registry (one record per operation, across the entity
+registry in `capabilities.json`), 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
 secret fields (`password`, `secretKey`, `secret`) always, personal and
@@ -219,29 +219,23 @@ The reference MCP servers (`examples/mcp-server.ts`,
 (0 disables retries). Unset = the profile's value; an invalid value stops
 startup with an `AutotaskConfigError` naming the variable.
 
-## Optional per-host circuit breaker (issue #26)
-
-`circuitBreaker: { enabled: true }` opts into the circuit breaker at the
-transport (OFF by default — nothing changes unless opted in). It counts
-SERVICE-FAILURE outcomes per HOST (the lowercased host of the base URL — a
-zone outage hits every tenant on that zone) and, once 5 counted failures
-land inside a 10-second window, refuses further calls for that host
-LOCALLY — zero upstream calls, no hourly-limiter stamp — as a
-`CircuitBreakerError` (`code: 'CIRCUIT_BREAKER_OPEN'`, `notSent: true`,
-`retryAfter` = the remaining open seconds; `retryable: true` — the open
-period is bounded and advertised, so retry the SAME call after the wait;
-the deliberate divergence from the #6 cooldown refusal's `retryable:
-false`). After 30 seconds open, up to `halfOpenProbes` probes go
-upstream; 2 probe successes close the circuit, a probe failure re-arms it.
-The default predicate counts `NETWORK_ERROR`, `TIMEOUT`, a vendor 429, a
-5xx except the deterministic field-validation 500, and
-`UNEXPECTED_CONTENT_TYPE` — never a caller's cancellation, a 4xx, or a
-local refusal. On a shared host (one host, many credential tuples) one
-tenant's outage opens the circuit for the others — the documented
-consequence of the host-only key. `thresholdInformation.get()` bypasses
-the refusal (its outcome is still recorded); a custom `CircuitBreakerStore`
-and failure predicate are injectable (details:
-[`docs/API.md`](./docs/API.md) section 3.2.2).
+## Maintenance gate (issue #285)
+
+Autotask takes each zone down for a weekly maintenance window, during which the
+edge serves an HTML maintenance page. The first call that sees that page opens a
+process-wide gate for the zone (always on). While it is open, every other call on
+the zone fails at once with `MaintenanceError` (`code: 'MAINTENANCE'`,
+`notSent: true`, `retryAfter` = seconds to the next probe, `details.since`), with
+zero upstream calls. One call per `maintenancePollMs` (default 30 s) goes upstream
+as the probe, and the first non-maintenance response closes the gate. The call
+that saw the page waits the window out for up to `maintenanceMaxWaitMs` (default
+1 h); `maintenanceMaxWaitMs: 0` fails fast instead (the gate still opens). A
+call that receives the page and does not wait it out throws the same
+`MaintenanceError` (with `httpStatus` set, no `notSent`), so consumers map one
+code. Only the
+page's text is recognised: a non-matching HTML page (for example a wrong
+`baseUrl`) never opens the gate. Details: [`docs/API.md`](./docs/API.md)
+section 3.2.2.
 
 ## Subpaths
 
@@ -265,7 +259,7 @@ import { markUntrusted, stripUntrustedDeep } from 'node-autotask/untrusted';
 // tuple (multi-tenant gateways: one client per tenant — limiter state and
 // read cache persist across a tenant's requests, never across tenants)
 import { createClientPool } from 'node-autotask/pool';
-// createClientPool({ maxSize = 128, idleTtlMs?, factory? })
+// createClientPool({ maxSize = 128, sharedReadCache? })
 //   -> { get(config), delete(config), clear(), size }
 
 // Errors (the class → code → status hierarchy)
@@ -284,9 +278,8 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    `staleCheck` hash-pins). Generated from `capabilities.plan.json` (the single source
    of truth) — never hand-edited.
 2. **Manifest** — [`MCP_TOOL_MANIFEST.md`](./MCP_TOOL_MANIFEST.md): the mechanical
-   projection (`npm run mcp:project`) — 804 entity-first tool names
-   (`autotask_<entity>_<verb>`; the five META tools bring the full surface to
-   809), descriptions = registry purpose + a mechanical
+   projection (`npm run mcp:project`) — entity-first tool names
+   (`autotask_<entity>_<verb>`, plus the five META tools), descriptions = registry purpose + a mechanical
    bounds/flags sentence, `dry_run` affordance on mutating tools, `confirm` on
    destructive ones; the plan-derived `untrustedFields` read tools additionally
    carry the untrusted-content sentence + the field list as the `x-untrusted`
@@ -352,7 +345,7 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    whose MCP annotation is `readOnlyHint !== true` — today exactly **267
    tools**: the 265 dedicated write/delete tools (209 `effect=write` + 56
    `effect=destructive`, every one of them has a dedicated tool) +
-   `autotask_write` + `autotask_delete`. The remaining **635 tools** (the 622 dedicated read tools + the 10 core read tools + `autotask_read` +
+   `autotask_write` + `autotask_delete`. The remaining **634 tools** (the 621 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). Refined class for the
@@ -448,7 +441,8 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    that the MCP servers wrap as untrusted host text; a maintenance notice is waited
    out for up to `maintenanceMaxWaitMs` (default 1 h; `MAINTENANCE_WINDOW_MAX_MS`
    = 4 h, the observed ceiling) for reads and writes; the same wait recognises the
-   page at ANY status — `2xx`/`4xx`/`5xx`, issue #114 — but a `4xx`/`5xx` page is
+   page at ANY status — `2xx`/`4xx`/`5xx`, issue #114 — and the page opens the
+   zone's maintenance gate (see "Maintenance gate" above) — but a `4xx`/`5xx` page is
    waited out only for calls safe to re-send (a `GET` or an explicitly
    `idempotent`-flagged call): an unflagged mutation makes ONE send and says the
    write may have taken effect (`details.maintenanceDetected`); a non-matching
@@ -512,7 +506,7 @@ Semantics, pinned by `test/resources/collection-update-merge.test.ts` (mock fetc
 
 [`docs/N8N-ADAPTER.md`](./docs/N8N-ADAPTER.md) proves the thin-importer thesis: how
 `n8n-nodes-autotask` v2.29.4 keeps zero Autotask knowledge after the port — the
-generated 121-row operation mapping (node dir → node ops → SDK methods), the global-op
+generated operation mapping (node dir → node ops → SDK methods), the global-op
 mapping (searchFilter/tool/aiHelper/apiThreshold), the swagger-gap table (87
 node-parity paths the vendored swagger lacks, all UNVERIFIED-live this run), and the
 5-line rewrite recipe.
@@ -531,7 +525,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 1281 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 <= 1227 plan-honest / <= 1382 wire-honest worst case) |
+| `npm run live-coverage` | `scripts/live-coverage.mjs` — the live coverage sweep over all 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 <= 1227 plan-honest / <= 1382 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) |
@@ -573,8 +567,7 @@ without credentials; a green exit is never a false pass.
 
 ## Testing
 
-Strict TDD against mocked HTTP (no live calls in CI): 2685 tests / 215 files on
-this build. Every registry record pins the plan + source + test file hashes
+Strict TDD against mocked HTTP (no live calls in CI): see `npm test` for the current suite. Every registry record pins the plan + source + test file hashes
 (`staleCheck`), and `capabilities:check` re-derives them at the gate. Coverage
 thresholds: 90/90/80/90 (lines/functions/branches/statements). The public API
 surface baseline (`test/__fixtures__/public-surface.json`) proves "additive only":
@@ -602,8 +595,7 @@ suites are the release gate, the live scripts are the ground-truth check.
   env rename to the official Autotask terms, the swagger-required
   `zoneInformation` `user` param, and the always-sent query `filter` (node
   parity) — all live-verified against AU03/ww29.
-- **v0.1.0** — the node's 121-entity MVP set: 128 resources
-  (121 entities + 7 integration endpoints), 1167 registry operations, the agent
+- **v0.1.0** — the node's MVP entity set and integration endpoints, the agent
   execution layer (helper floor, bounded scans, mutation safety), the MCP substrate
   (registry → manifest → overrides → core tier + catalog), and the docs surface.
 - **Full 3003-operation spec** — the vendored swagger's complete op set (3003