node-autotask 0.17.0 → 0.19.0

package/ARCHITECTURE.md

@@ -396,8 +396,13 @@ The only total is `count()` (`/query/count`); "more rows exist" is `nextPageUrl
 The node follows `pageDetails.nextPageUrl` (an absolute vendor URL, POSTing the
 filter to it), and the SDK does the same: the walk is the fetcher
 (`BaseResource.fetchPage`), which POSTs the `QueryModel` body to
-`/V1.0/<E>/query` for page 1 (`MaxRecords = pageSize`) and POSTs the preserved
-filter to the ABSOLUTE cursor for every later page. The cursor is rebased to
+`/V1.0/<E>/query` for page 1 (`MaxRecords = pageSize`) and POSTs the SAME body
+(`buildQueryBody` — `MaxRecords`, `IncludeFields` with the `id` append, the
+preserved `filter`) to the ABSOLUTE cursor for every later page (issue #118:
+before the fix the continuation carried `{ filter }` alone and returned the
+full vendor model). Live-verified 2026-10-19: the vendor HONOURS
+`IncludeFields` on a continuation and IGNORES `MaxRecords` (its own 500-row
+page; the walk slices to its limit). The cursor is rebased to
 the client base URL (`cursorToPath`): same-origin cursors are stripped of the
 base and used verbatim, cross-origin ones are re-based onto the client base —
 mirroring the node's custom-zone behaviour. A page reports `hasMore` when
@@ -534,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
@@ -993,8 +1005,9 @@ export const NoopLogger: Logger = {};
   envelope pass-through, per-envelope unwrap errors, error mapping per status (vendor error
   body formatting), retry/backoff on 429 with `Retry-After`, `Itgenatr005` as retryable
   `RateLimitError`, `AbortSignal` timeout, concurrency guard.
-- **Pagination (`pagination.test.ts`)**: multi-page cursor-follow walk (POST the filter
-  to the absolute `nextPageUrl`, rebased to the client base URL), early stop on short
+- **Pagination (`pagination.test.ts`)**: multi-page cursor-follow walk (POST the same
+  `QueryModel` body to the absolute `nextPageUrl`, rebased to the client base URL;
+  issue #118 pins the continuation's `IncludeFields`/`MaxRecords`), early stop on short
   page, **1000-page guard** (`PaginationLimitError`), `collectAll` equivalence.
 - **Query (`query.test.ts`)**: filter builder (13 operators, and/or wrapping, UDF flag),
   cap enforcement (500 OR-conditions, 1 UDF/query), GET-length measurement.