node-autotask 0.14.0 → 0.16.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;
-  /** The client's retry budget (default 3; 0 disables auto-retry). Two legs (issue #105): the 429 leg retries on the pre-#105 retriable set (GET/PUT/DELETE + idempotent-flagged calls) and the 5xx/network leg retries GET + idempotent-flagged calls only. A per-call override rides `InvokeOptions.maxRetries` / `MutationOpts.maxRetries`. */
+  /** 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,7 +510,7 @@ 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** (issue #105 — two legs, two rules, retry up to `maxRetries` with
+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
@@ -527,6 +527,21 @@ export interface RequestOptions {
      `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.
+   - **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/README.md

@@ -397,9 +397,11 @@ 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 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
    vendor field-validation 500 matching the documented phrases (`exceeds

package/dist/capabilities.d.cts

@@ -76,11 +76,12 @@ interface CapabilityRecord {
         maxScanRecords: number;
         maxScanPages: number;
     } | null;
-    /** From the actual transport (src/http.ts; issue #105 — two legs): the
-     *  429 (a pre-processing refusal) leg auto-retries per Retry-After on the
-     *  pre-#105 retriable set (GET/PUT/DELETE + idempotent-flagged ops; an
-     *  unflagged POST/PATCH surfaces at once); on 5xx/network errors only reads
-     *  and idempotent-flagged ops auto-retry (exponential backoff, equal
+    /** From the actual transport (src/http.ts; issues #105/#109 — three legs,
+     *  two rules): the 429 (a pre-processing refusal) leg auto-retries per
+     *  Retry-After on the pre-#105 retriable set (GET/PUT/DELETE +
+     *  idempotent-flagged ops; an unflagged POST/PATCH surfaces at once); on
+     *  5xx/network errors AND on a non-JSON 2xx (#24) only reads and
+     *  idempotent-flagged ops auto-retry (exponential backoff, equal
      *  jitter, base 200ms, cap 30s, max 3 retries, Retry-After honoured) — a
      *  mutation's outcome is unknown once its body was written. The vendor
      *  offers no idempotency pass-through. */

package/dist/capabilities.d.ts

@@ -76,11 +76,12 @@ interface CapabilityRecord {
         maxScanRecords: number;
         maxScanPages: number;
     } | null;
-    /** From the actual transport (src/http.ts; issue #105 — two legs): the
-     *  429 (a pre-processing refusal) leg auto-retries per Retry-After on the
-     *  pre-#105 retriable set (GET/PUT/DELETE + idempotent-flagged ops; an
-     *  unflagged POST/PATCH surfaces at once); on 5xx/network errors only reads
-     *  and idempotent-flagged ops auto-retry (exponential backoff, equal
+    /** From the actual transport (src/http.ts; issues #105/#109 — three legs,
+     *  two rules): the 429 (a pre-processing refusal) leg auto-retries per
+     *  Retry-After on the pre-#105 retriable set (GET/PUT/DELETE +
+     *  idempotent-flagged ops; an unflagged POST/PATCH surfaces at once); on
+     *  5xx/network errors AND on a non-JSON 2xx (#24) only reads and
+     *  idempotent-flagged ops auto-retry (exponential backoff, equal
      *  jitter, base 200ms, cap 30s, max 3 retries, Retry-After honoured) — a
      *  mutation's outcome is unknown once its body was written. The vendor
      *  offers no idempotency pass-through. */

package/dist/{chunk-2ZZOTJ2C.js → chunk-GWALLMAM.js}

@@ -127,13 +127,13 @@ import {
   VersionInformationResource,
   VersionResource,
   ZoneInformationResource
-} from "./chunk-IYN2BHVW.js";
+} from "./chunk-NB254T3F.js";
 import {
   AutotaskConfigError,
   HttpClient,
   resolveConfig,
   runWithSignal
-} from "./chunk-KA6UU26H.js";
+} from "./chunk-U6JUHHMB.js";
 
 // src/client.ts
 var AutotaskClient = class {