node-autotask 0.15.0 → 0.17.0

package/ARCHITECTURE.md

@@ -534,6 +534,14 @@ export interface RequestOptions {
      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.
+   - **Maintenance-window wait (weekly window):** a non-JSON `2xx` that reads as a
+     maintenance notice is waited out for up to `maintenanceMaxWaitMs` (default 1 h,
+     polled every `maintenancePollMs` = 30 s) from the first such page — for reads
+     AND writes, because the edge answered before the vendor application saw the
+     request. It does not consume `maxRetries`, each post-wait attempt gets a fresh
+     `timeoutMs`, and the timer is re-armed around the wait. On exhaustion the error
+     carries `details.maintenance = { waits, waitedMs, maxWaitMs, exhausted }`. A page
+     that does not read as maintenance (a wrong `baseUrl`) never enters the loop.
    - **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

package/N8N_MCP_MANIFEST.json

@@ -1,6 +1,6 @@
 {
   "schema": "node-autotask n8n consumer mcp projection v1",
-  "generatedAt": "2026-10-17T13:48:43.907Z",
+  "generatedAt": "2026-10-18T23:23:18.804Z",
   "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": "fd92667b96dd9c74d9bbda2a34bf50b9791e2f236a6d2bb50b50a02a1d064882",
+  "capabilitiesHash": "26246eab57263743486ab1afda89379b7b26462c592c5b104e727e337de92886",
   "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-17T13:48:43.907Z — do not hand-edit. -->
+<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-18T23:23:18.804Z — 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-17T13:48:43.907Z
-- capabilitiesHash: fd92667b96dd9c74d9bbda2a34bf50b9791e2f236a6d2bb50b50a02a1d064882
+- generatedAt: 2026-10-18T23:23:18.804Z
+- capabilitiesHash: 26246eab57263743486ab1afda89379b7b26462c592c5b104e727e337de92886
 - curationHash: e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b

package/README.md

@@ -147,6 +147,42 @@ length and a two-character prefix per value — never a full value. See
 [`docs/LIVE-TESTING.md`](./docs/LIVE-TESTING.md) §0b.
 
 
+### The full variable set
+
+`.env.example` is the committed template; `.env*` is gitignored, so real values never enter git.
+
+```sh
+cp .env.example .env      # then fill in the three credentials
+```
+
+Optional settings are **commented out with a sample value** — uncomment a line to set it. For example
+`AUTOTASK_PROFILE=agent` selects the conservative agent profile (page 25, 8,000/hr, 20 s timeout,
+1 retry, 3 concurrent), and `AUTOTASK_MAX_RETRIES=1` is that profile's retry budget. Leave the five
+server-layer overrides unset rather than blank: an empty value is *invalid* for them by design
+(fail-closed), so a stray `AUTOTASK_MAX_RETRIES=` stops startup with an error naming the variable.
+
+| variable | read by | meaning |
+|---|---|---|
+| `AUTOTASK_TRACKING_IDENTIFIER` | `bin/doctor.js`, examples, live scripts | API tracking identifier (aliases: `AUTOTASK_API_CODE`, `AUTOTASK_API_INTEGRATION_CODE`) |
+| `AUTOTASK_USERNAME` | same | API user (alias: `AUTOTASK_USER`) |
+| `AUTOTASK_SECRET` | same | secret — see the single-quote contract above |
+| `AUTOTASK_ZONE` | doctor, examples, live scripts | **catalog name**, not a host (default `old-australian` = webservices6); `other` requires a base URL — the template lists all 23 |
+| `AUTOTASK_BASE_URL` | doctor, examples, live scripts | explicit REST base; **wins** over the zone; include `/atservicesrest` |
+| `AUTOTASK_IMPERSONATION_ID` | doctor, examples | optional `ImpersonationResourceId` header |
+| `AUTOTASK_PROFILE` | reference MCP servers | `library` (default) / `agent` — the agent profile's numbers are compared in the template and in *Agent profile* above |
+| `AUTOTASK_RATE_LIMIT_PER_HOUR` | reference MCP servers | hourly limiter: a positive integer, or `0` / `off` to disable |
+| `AUTOTASK_MAX_CONCURRENT` | reference MCP servers | concurrency guard (vendor max 10) |
+| `AUTOTASK_TIMEOUT_MS` | reference MCP servers | whole-call timeout |
+| `AUTOTASK_MAX_RETRIES` | reference MCP servers | retry budget (`0` disables) |
+| `AUTOTASK_UNTRUSTED_WRAP` | MCP servers | `on` (default) / `off` — the `<untrusted_content>` projection |
+| `AUTOTASK_GATEWAY_MODE` | `examples/mcp-server-http.ts` | `on` for multi-tenant gateway mode (per-request credentials) |
+| `PORT` | `examples/mcp-server-http.ts` | listen port (default 7437) |
+| `AUTOTASK_ENV_FILE` | live scripts | alternate `.env` path (shell variables always win) |
+
+The SDK itself never reads `process.env`: pass `apiIntegrationCode` / `userName` / `secret`
+explicitly, or call `loadAutotaskCredentialsFromEnv()`.
+
+
 ## Agent profile (conservative limits for LLM-driven servers)
 
 `profile: 'agent'` on the config switches the SDK to conservative limits for
@@ -397,8 +433,10 @@ 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; a `GET` or an explicitly
-   `idempotent`-flagged call retries, a write makes ONE call and says the write
+   that the MCP servers wrap as untrusted host text; a maintenance notice is waited
+   out for up to `maintenanceMaxWaitMs` (default 1 h — the weekly window is usually
+   under 30 min) for reads and writes, otherwise a `GET` or an explicitly
+   `idempotent`-flagged call retries and 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

package/capabilities.json

@@ -1,9 +1,9 @@
 {
-  "generatedAt": "2026-10-17T13:48:43.536Z",
+  "generatedAt": "2026-10-18T23:23:18.606Z",
   "groups": {
     "B": {
       "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-      "builtAt": "2026-10-17T13:48:43.535Z",
+      "builtAt": "2026-10-18T23:23:18.605Z",
       "records": [
         {
           "id": "appointments.count",
@@ -56168,7 +56168,7 @@
     },
     "A": {
       "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-      "builtAt": "2026-10-17T13:48:43.536Z",
+      "builtAt": "2026-10-18T23:23:18.606Z",
       "records": [
         {
           "id": "companies.count",
@@ -112388,7 +112388,7 @@
     },
     "operations": {
       "planHash": "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14",
-      "builtAt": "2026-10-17T13:48:43.536Z",
+      "builtAt": "2026-10-18T23:23:18.606Z",
       "records": [
         {
           "id": "operations.aggregate",

package/dist/capabilities.cjs

@@ -2,9 +2,9 @@
 
 
 
-var _chunkEWMG3HHUcjs = require('./chunk-EWMG3HHU.cjs');
+var _chunk5ZGXWS4Ecjs = require('./chunk-5ZGXWS4E.cjs');
 
 
 
 
-exports.CAPABILITIES = _chunkEWMG3HHUcjs.CAPABILITIES; exports.CAPABILITY_GROUPS = _chunkEWMG3HHUcjs.CAPABILITY_GROUPS; exports.CAPABILITY_PLAN_HASHES = _chunkEWMG3HHUcjs.CAPABILITY_PLAN_HASHES;
+exports.CAPABILITIES = _chunk5ZGXWS4Ecjs.CAPABILITIES; exports.CAPABILITY_GROUPS = _chunk5ZGXWS4Ecjs.CAPABILITY_GROUPS; exports.CAPABILITY_PLAN_HASHES = _chunk5ZGXWS4Ecjs.CAPABILITY_PLAN_HASHES;

package/dist/capabilities.js

@@ -2,7 +2,7 @@ import {
   CAPABILITIES,
   CAPABILITY_GROUPS,
   CAPABILITY_PLAN_HASHES
-} from "./chunk-JIDR3NPV.js";
+} from "./chunk-6SP6GJJR.js";
 export {
   CAPABILITIES,
   CAPABILITY_GROUPS,