node-autotask 0.8.3 → 0.10.0

package/ARCHITECTURE.md

@@ -383,11 +383,13 @@ Autotask list reads are `GET|POST /V1.0/<E>/query` returning the pinned envelope
 
 ```json
 { "items": [ "<Model>", ... ],
-  "pageDetails": { "count": 10, "requestCount": 1234,
-                   "prevPageUrl": null, "nextPageUrl": null } }
+  "pageDetails": { "count": 10, "requestCount": 10,
+                   "prevPageUrl": null, "nextPageUrl": "<cursor>" } }
 ```
-(`QueryActionResult[<Model>,<Entity>]`; `requestCount` = total matching records, `count` =
-records on this page.) Single-record reads (`GET /V1.0/<E>/{id}`) and count/entityInfo reads
+(`QueryActionResult[<Model>,<Entity>]`; `count` = records on this page; `requestCount` is the
+vendor's echo of the requested `MaxRecords` (500 when omitted) — NOT a match count, live-verified
+2026-10-11: `MaxRecords: 5` over 13,220 matches → 5, a zero-match page → the MaxRecords asked.
+The only total is `count()` (`/query/count`); "more rows exist" is `nextPageUrl !== null`.) Single-record reads (`GET /V1.0/<E>/{id}`) and count/entityInfo reads
 **never** carry paging parameters.
 
 ### Page walk — cursor-follow on `pageDetails.nextPageUrl`
@@ -407,9 +409,9 @@ export interface Page<T> {
   items: T[];
   page: number;            // 1-based
   pageSize: number;        // default 10, max 500
-  requestCount: number;    // pageDetails.requestCount (total matches)
+  requestCount: number;    // pageDetails.requestCount verbatim (MaxRecords echo, not a total)
   hasMore: boolean;        // nextPageUrl !== null
-  totalPages: number;      // ceil(requestCount / pageSize)
+  totalPages: number;      // pages known so far: hasMore ? page + 1 : page (page - 1 when an empty page follows a full one; 0 when empty)
 }
 
 type PageFetcher<T> = (page: number, pageSize: number) => Promise<Page<T>>;
@@ -733,7 +735,7 @@ Concrete resources extend `BaseResource` and expose **narrowly-typed** public me
 | 2 | Version segment: swagger `/V1.0/` vs node runtime `/v1.0/` | SDK pins `/V1.0`; vendor tolerates both |
 | 3 | Page keys: public docs `Limit`/`Offset` vs wire `maxRecords`/`includeFields`/`filter` | Wire format is the POST `QueryModel` body; the doc names are aliases only |
 | 4 | GET query vs POST: vendor caps GET at 2048 chars; the node POSTs everything | SDK defaults to **POST-always**; GET opt-in with 2048 measurement (never silent) |
-| 5 | No total-pages in `PagingModel`; node derives `ceil(requestCount / pageSize)` | SDK derives it too; **1000-page guard** |
+| 5 | No total in `PagingModel`; node derives `ceil(requestCount / pageSize)`, but `requestCount` echoes `MaxRecords` (live-verified), so that is always 1 | SDK reports pages known so far (`totalPages` exact on the last page); a real total is `count()`; **1000-page guard** |
 | 6 | Thread limit: API 10 concurrent; node self-limits to 3/endpoint | SDK default guard = 10 (the API limit), configurable |
 | 7 | Count envelope is an OBJECT `{ queryCount }`, not a number | `count()` unwraps to a plain number |
 | 8 | Approve is **GET**, Reject is **POST** (method asymmetry) | Pinned as-is; no uniform-verb assumption anywhere |
@@ -1092,9 +1094,10 @@ Floor (plan rows pre-declare it; G6 implements):
   non-match returns `null`; ambiguity throws `RESOLUTION_AMBIGUOUS` (candidates in
   `resourceIds`); a cap-tripped scan throws `RESOLUTION_TRUNCATED` (never a silent `null`).
   Autotask filters every model field server-side, so `resolve` is **server-filter first**
-  — a client scan is only the fallback for fields the vendor does not index, bounded by the
-  client caps (`resolution: { maxScanRecords: 500, maxScanPages: 4 }`, configurable per
-  client).
+  and a zero-item filter answer is a complete non-match (`null`). The vendor gives no
+  "incomplete" signal (`pageDetails.requestCount` echoes `MaxRecords`), so the client scan
+  is opt-in (`resolution.scanOnMiss: true`): it re-checks a miss, bounded by the client caps
+  (`resolution: { maxScanRecords: 500, maxScanPages: 4 }`, configurable per client).
 - `findBy<Field>()` where the vendor filters it and callers actually look up by it
   (pre-declared in the MVP plan: `tickets.findByTicketNumber`,
   `configuration_items.findBySerial`, `contacts.findByEmail`); batch implementers may add