node-autotask 0.18.0 → 0.19.0

package/ARCHITECTURE.md

@@ -539,14 +539,21 @@ 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.
+   - **Maintenance-window wait (weekly window):** a NON-JSON body whose first
+     256 bytes read as a maintenance notice is waited out at any status
+     (`2xx`/`4xx`/`5xx` — issue #114; a JSON body never enters) for up to
+     `maintenanceMaxWaitMs` (default 1 h; the observed ceiling is 4 h, exported as
+     `MAINTENANCE_WINDOW_MAX_MS`, polled every `maintenancePollMs` = 30 s) from the
+     first such page. A non-JSON `2xx` page is waited out for reads AND writes (edge-
+     served before execution). A non-JSON `4xx`/`5xx` page only for calls safe to
+     re-send (`retriable5xx`: GET / explicitly idempotent-flagged) — an unflagged
+     mutation makes ONE send and carries `details.maintenanceDetected`, because a
+     proxy can serve that page after forwarding the write. 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 non-JSON page
+     that does not read as maintenance (a wrong `baseUrl`) never enters the loop and
+     stamps `details.maintenancePatternMiss` (snippet at `debug`).
    - **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