node-autotask 0.34.0 → 0.37.0

package/docs/API.md

@@ -270,6 +270,7 @@ status → what the vendor does that triggers it.
 | `DeleteBoundaryError` | `DELETE_BOUNDARY` | policy | — | `operations.recovery` `action: 'delete'` on a resource the vendored spec defines no DELETE for — refused PRE-SEARCH (zero wire; the boundary is the spec-derived plan audit, never a raw vendor 405; issue #9) |
 | `MarkerUnsafeIdError` | `MARKER_UNSAFE_ID` | policy | — | a `operations.recovery` match whose id is beyond `Number.MAX_SAFE_INTEGER` (unaddressable through the typed delete surface) — refused with the typed code, never a silent skip (issue #9, P1) |
 | `RecoveryTruncatedError` | `RECOVERY_TRUNCATED` | policy | — | the `operations.recovery` marker search tripped its match cap (more matches than `limit`) — refused instead of a silent truncation / silent empty (issue #9) |
+| `AutotaskError` | `BUDGET_EXCEEDED` | policy | — (the call that would exceed it is not sent) | `operations.revenueRollup`: the pre-walk estimate exceeds `maxVendorCalls` (refused before any stream; `details: { phase: 'estimate', estimate, budget, suggestions }`) or the counting wrapper reached the budget mid-walk (`phase: 'walk'`; the partial fold is discarded) — `suggestedAction` names the narrowing (issue #234) |
 
 Retryable by contract: `NETWORK_ERROR`, `TIMEOUT`, `RATE_LIMITED`,
 `SERVER_ERROR` (429/5xx) — with ONE exception: a deterministic vendor
@@ -1106,13 +1107,13 @@ be cross-mode-refused.
   and the `confirm === <op key>` gate (all 54 deletes; the 3 approval-gated
   writes — inside `autotask_write` too) apply exactly as in `invoke`.
   Pinned by the full-surface suite (`test/operations/invoke/modes.test.ts`:
-  all 1275 ops × 3 modes, zero wire).
+  all 1281 ops × 3 modes, zero wire).
 
 **Harness approval policy (recommended).** Require approval on every tool
 whose MCP annotation is `readOnlyHint !== true` — today exactly **267
    tools**: the 265 dedicated write/delete tools (209 `effect=write` + 56
    `effect=destructive`, every one of them has a dedicated tool) +
-`autotask_write` + `autotask_delete`. The remaining **634 tools** (the 621 dedicated read tools + the 10 core read tools + `autotask_read` +
+`autotask_write` + `autotask_delete`. The remaining **635 tools** (the 622 dedicated read tools + the 10 core read tools + `autotask_read` +
 `autotask_catalog` + `autotask_describe`) all carry `readOnlyHint: true`
 and are safe ungated: every op they can route is `effect=read` (zero
 mutating requests — pinned by the test inventory, §6 of the split design).
@@ -1563,10 +1564,201 @@ The secondary read re-applies the open filter client-side, and `limit` is not
 validated (it does not apply). With `scope` `primary`/`secondary` only that side is
 read and `both` is 0.
 
+### 7.14 `revenueRollup(client, opts)` — revenue by dimension, budgeted (issues #234, #235, #236)
+
+One read call answers "revenue for Recurring Service + Fixed Price contracts
+over a window, by account vertical": the registry op `operations.revenueRollup`
+(MCP tool `autotask_revenue_rollup`, tier extended).
+
+- **Scope** (exactly one, REQUIRED — no scope is refused with zero wire):
+  `companyIDs` | `ownerResourceID` (resolved to company ids by one projected
+  `companies` query) | `contractIDs` | `tenantWide: true`. A company scope
+  filters on the LINE's `companyID` (attribution is by the line's company).
+- **Window**: `dateFrom` / `dateTo` (`YYYY-MM-DD`, both REQUIRED, inclusive,
+  whole UTC days, at most 36 months), invoice-date basis.
+  The window is whole calendar days sent to the vendor as bare `YYYY-MM-DD`
+  bounds; that was verified on a tenant ahead of UTC only, and tenants behind
+  UTC are unverified.
+- **Revenue** = Σ `billing_items.internalCurrencyTotalAmount` (ex-tax, internal
+  currency) over the lines of NON-VOIDED invoices (`isVoided eq false`
+  server-side) in the window, folded in integer cents.
+  `includedValue` = Σ(`internalCurrencyExtendedPrice` − total) is
+  informational and never added to revenue. Credits (negative lines) are
+  netted and also reported per row. A line whose `internalCurrencyTotalAmount`
+  / `internalCurrencyExtendedPrice` is missing or null falls back to the
+  local-currency `totalAmount` / `extendedPrice` (as contract profitability
+  does), everywhere those fields are read (revenue, `includedValue`, the
+  non-chargeable class and value); never silently: one
+  `coverage.blindSurfaces` entry gives the count of such lines.
+- **`contractTypes`** (ids or exact labels) default to the live picklist
+  labels that START with `Recurring` or `Fixed` (case-insensitive,
+  `/^\s*(recurring|fixed)\b/i`: `Non-Recurring` does not match); the resolved map is echoed in
+  `coverage.contractTypeMap`. No match is a `CONFIG_ERROR` listing the live
+  labels and ids. `contractCategories` filters the same way, and when given
+  its resolved map is echoed in `coverage.contractCategoryMap` (`{ "<id>":
+  label }`, absent otherwise). A label shared by several live picklist ids
+  selects every one of them.
+- **`groupBy`** (default `['vertical', 'contractType']`): `vertical`
+  (`companies.marketSegmentID`), `contractType`, `contractCategory`,
+  `company`, `month` (the invoice month), `billingItemKind`, and the join
+  dimensions (#235):
+  - `contract` — `{ id, name }` (`contractName` joins the contract fetch).
+  - `lineOfBusiness` — per billing line (`organizationalLevelAssociationID`;
+    no contract-pointer fallback): three batch `id in` fetches (associations,
+    level1s, level2s) give `{ id: associationId, name: level2Name (the Line of
+    Business), division: level1Name }`. Lines without a pointer form their own
+    row `{ id: null, label: 'no LOB assigned' }`, and
+    `coverage.lineOfBusiness = { noPointer: { amount, lines }, note }` carries
+    their amount (LOB figures are floors). A row's `contracts` is "contracts
+    with at least one line in this LOB", so per-LOB counts can sum to more than
+    `totals.contracts`.
+  - `resource` — labour lines only (`billingItemType` Labor / Labor
+    Adjustment, or the FK fallback): `timeEntryID` → time entry → resource,
+    `{ id: resourceID, name: 'First Last' }`. Non-labour lines, and labour
+    lines with no time entry (e.g. an adjustment), are `{ id: null, label: 'n/a' }`.
+  - `billingCode` — `billingCodeID` → billing code `{ id, name }`; a line
+    without one is `{ id: null, label: 'none' }`.
+
+  Each row key is `{ id, label?, name?, division? }`: picklist text in
+  `label`; vendor entity text (untrusted — company, contract, LOB level2,
+  resource and billing-code names) in `name`, and the LOB division (level1
+  name, also untrusted) in `division`. Missing values get their own row
+  (`unassigned`, `uncategorised`, `no LOB assigned`, `n/a`, `none`); a value
+  the picklist does not serve stays id-only and is listed in
+  `coverage.blindSurfaces`. A join id the `id in` fetch does not return is
+  never guessed: the line goes to `coverage.excluded.unresolvedAssociations`
+  (association or its level1/level2), `unresolvedTimeEntries` (time entry or
+  its resource) or `unresolvedBillingCodes`, with its amount. These buckets
+  (and `coverage.lineOfBusiness`) appear only when their dimension is grouped;
+  the line projection grows by `organizationalLevelAssociationID`,
+  `timeEntryID` / the type fields and `billingCodeID` the same way.
+- **Rows** are sorted by revenue descending, then ids; `top` (default 100,
+  max 100) keeps the head and folds the tail into `rowsTruncated`. `totals`
+  always cover every row.
+- **`coverage.excluded`**: voided invoices (count + header amount; under a
+  company / owner scope only the voided invoices whose HEADER `companyID` is
+  in scope; omitted for a `contractIDs` scope, since an invoice header cannot
+  be attributed to a contract, and noted in `coverage.notes`), uncontracted
+  lines, other contract types (per label), other contract categories (per
+  label; a label shared by several live ids is keyed `label (id)`, so ids
+  are never merged) and
+  unresolved contracts / companies (ids the `id in` fetch did not return; an
+  unresolved contract is never counted as uncontracted), each with an amount
+  and a line count. Every line is in exactly one place, so `totals.revenue` +
+  Σ the excluded line buckets = Σ the lines fetched (lines are de-duplicated
+  by id before the fold).
+- **`coverage.zeroTotalInvoices`** `{ count, amount, lines }` is an
+  informational overlay, NOT an excluded bucket: the zero-total invoices in
+  scope (tenant-wide: all; company / owner scope: header company in scope or
+  carrying an in-scope line; `contractIDs`: carrying a scoped line) and the
+  amount / count of their lines. Those lines are still folded into rows or the
+  excluded buckets.
+- **`includeNonChargeable`** (#236, default `false`; when `false` the call,
+  its wire and its output are byte-identical to leaving it out): adds
+  `nonChargeable: { contractCovered: { value, hours, lines }, nonBillable:
+  { value, hours, lines } }` to every row and to `totals`. It is NEVER added to
+  `revenue` / `totals.revenue`. Classes per line: non-billable =
+  `nonBillable` true; contract-covered = billable with
+  `internalCurrencyExtendedPrice` > 0 and `internalCurrencyTotalAmount` = 0.
+  `value` = Σ `internalCurrencyExtendedPrice` (integer cents); `hours` = Σ
+  `quantity` on labour lines, Labor Adjustment (type 2) included (it adjusts
+  labour hours, and `billingLineType` already classes it as labour). The
+  invoiced part comes from the revenue line stream (+ `nonBillable`,
+  `quantity` and the type fields); the uninvoiced part is a second unsliced
+  stream `invoiceID notExist` with `itemDate` in the window (+ the same
+  scope). Uninvoiced lines have no invoice date, so they are windowed and
+  month-keyed on `itemDate` (stated in `coverage.notes`). They are keyed
+  through the same joins (one fetch over both streams, so only ids the
+  invoiced lines did not already need are added); uninvoiced lines that are
+  uncontracted or of another contract type / category are outside the
+  request. A non-chargeable line, invoiced or uninvoiced, whose row cannot be
+  resolved (an unresolved contract / company or a join miss) goes to
+  `coverage.excluded.unresolvedNonChargeable` (amount = Σ value); an invoiced
+  one is also in its revenue excluded bucket. The default `maxVendorCalls` becomes 150 (an explicit
+  value wins; cap 200).
+- **`coverage.reconciliation`**: header `invoiceTotal` vs Σ line `totalAmount`
+  per invoice (tolerance 0 cents; `totalAmount`, so a multi-currency tenant
+  gives no false delta). Tenant-wide it covers every invoice; a company scope
+  covers the invoices whose header company is in scope; a `contractIDs`
+  scope skips it (noted).
+- **Budget** (`maxVendorCalls`, default 90, max 200): every vendor call goes
+  through a counting wrapper. Before any stream the op counts the window's
+  non-voided invoices and the invoiced lines (`itemDate` in the window, a
+  proxy for the lines of those invoices) and estimates
+  `calls so far + 1 (voided; not for a contractIDs scope) + invoice pages + line pages (one per 500-invoice
+  chunk + overflow) + one line count per 500-invoice chunk (the per-chunk line gate) + uninvoiced pages (includeNonChargeable: its count is in
+  "calls so far", ≥ 1 page) + each join's id-fetch chunks`. A join's chunks
+  default to `ceil(min(lines + uninvoiced, invoices) / 500)` (contracts,
+  companies, LOB associations, billing codes); time entries use
+  `ceil((lines + uninvoiced) / 500)` (one per labour line, the labour share is
+  unknown pre-walk); LOB level1s / level2s and resources count one chunk each
+  (small org / staff tables). Over budget it REFUSES with `BUDGET_EXCEEDED`
+  (`details: { phase: 'estimate', estimate, budget, suggestions }`, the
+  message names the narrowings that apply: `maxVendorCalls: N` (while N is
+  within the cap), a later `dateFrom`, a scope, and, when raising the budget
+  cannot help (estimate past the cap), `includeNonChargeable: false`, fewer
+  `groupBy` dimensions, `contractIDs`, or a shorter id list (only for a list of
+  more than one id); at least one suggestion is always present. Only a raised
+  `maxVendorCalls` and a later `dateFrom` carry an estimate: the invoice
+  stream is tenant-wide in every scope and the line stream costs at least one
+  page and one count per chunk of 500 of those invoices, so a scope or shape
+  narrowing does not reduce that part, and when the refusal offers one its
+  message says it may still be refused; when nothing narrower exists the
+  only suggestion is the cap, and it says the call will be refused at that
+  estimate even at the cap). A budget
+  below the sizing overhead (the labels, owner query and count calls that run
+  before the estimate exists: at least 4 calls for the default shape, more with
+  `ownerResourceID`, `includeNonChargeable` or more picklist dimensions) is
+  the same refusal (`phase: 'estimate'`), with `estimate` = that minimum and
+  `suggestions: [{ maxVendorCalls }]`; the full estimate is named once the
+  call is sized.
+  Mid-walk the wrapper throws `BUDGET_EXCEEDED` (`phase: 'walk'`) before the
+  call that would exceed the budget. The wrapper counts LOGICAL requests: the
+  transport retries a 429 / 5xx internally (up to `maxRetries` each) below
+  it, and those retries are not counted in the budget, `vendorCalls` or
+  `tenantHourlyShare`. A 429 propagates as `RATE_LIMITED`. These fail as
+  `INVALID_RESPONSE`: a blind gate count (`reason: 'blind_count'`); the invoice
+  stream, each invoice-chunk line stream and the uninvoiced stream
+  (`includeNonChargeable`) whose DISTINCT ids differ from their gate count
+  (`reason: 'count_mismatch'`, `details.stream` names it: a page that repeats
+  one row and drops another is caught; each line chunk is counted on exactly
+  its stream's filter); and a line whose invoice is not among the streamed
+  invoices (`reason: 'orphan_line'`). Retry on a count race (data that changes
+  mid-walk). A repeated voided header is counted once, but a DROPPED voided
+  header is undetectable (there is no voided count call), so
+  `coverage.excluded.voidedInvoices` is a floor under vendor paging drift. Every fault discards the fold: a result is always
+  complete. `coverage.vendorCalls` is the exact logical-request count (joins
+  included; transport retries excluded); ~50
+  calls for a 12-month tenant-wide report on the reference tenant, ~115 with
+  `includeNonChargeable`. `resource` on 12 months tenant-wide adds ~15-25
+  calls and can refuse at the default 90 (the refusal names N).
+  An `ownerResourceID` that owns more than 100 companies is a `CONFIG_ERROR`
+  after at most one page past the 100th id (the resolution stops there).
+- **Limits**: amounts are rounded to cents per line (`Math.round(x * 100)`)
+  before summing, on the assumption that the vendor sends at most 2 decimals;
+  a 3-decimal amount can drift, and reconciliation (header vs line totals)
+  flags the delta. Non-chargeable `hours` are rounded to hundredths per line
+  before summing. A row that holds only non-chargeable work has revenue 0, so
+  it sorts above rows with negative revenue (net credits). The estimate costs
+  the voided stream as one page and assumes distinct contracts / companies
+  ≤ invoices; a window with more than 500 voided invoices, or (with
+  `includeNonChargeable`) many uninvoiced lines on contracts that never
+  invoiced in the window, can exceed it, and such a call fails mid-walk with
+  `BUDGET_EXCEEDED` (`phase: 'walk'`) rather than returning a partial result.
+
+```ts
+import { revenueRollup } from 'node-autotask/operations';
+const r = await revenueRollup(client, { tenantWide: true, dateFrom: '2025-07-01', dateTo: '2026-06-30' });
+// r.rows[0] → { keys: { vertical: { id: 12, label: 'Retail' }, contractType: { id: 7, label: 'Recurring Service' } }, revenue, credits, includedValue, contracts, items }
+const lob = await revenueRollup(client, { tenantWide: true, dateFrom: '2025-07-01', dateTo: '2026-06-30',
+  contractTypes: ['Recurring Service'], groupBy: ['vertical', 'lineOfBusiness'], includeNonChargeable: true });
+// lob.rows[i].keys.lineOfBusiness → { id: 7, name: '<level2>', division: '<level1>' } | { id: null, label: 'no LOB assigned' }
+```
+
 ## 8. Resource surface (135 resources)
 
 <!-- BEGIN GENERATED:api-per-entity -->
-Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page guarded), `queryBounded` (server-side pagination — one call walks the cursor until `limit` TOTAL records, default 500 / max 2500, with a `hasMore` flag; the MCP `query` surface, routed by `invoke`), `queryAll` (collect → `T[]` — the unbounded raw walk), `count`, `get` (id → record; `item: null` → `NotFoundError`), `create` / `update` / `delete` (where the vendor defines them — mutations take a `MutationOpts` bag: `{ dryRun, lastModifiedDate?, maxRetries? }` (issue #105: `maxRetries` overrides the configured retry budget for every request the mutation issues; `0` = exactly one send per request)), plus the helper floor where the plan declares it: `resolve` (all 121), `search` (40 — bounded contains on the resource text field), `getContext` (5 workflow resources), `findBy<Field>` (3), `createIfNotExists` (14). Entity metadata on every resource: `getEntityInfo`, `getFieldInfo`, `getUdfInfo` (UDF-capable 15). Parent-scoped children take `(parentId, id)` on the CRUD methods and require `parentId` on `createIfNotExists` (the scoped create POSTs the scoped collection; the dedup query stays global); `query`/`count`/`resolve`/`search` stay global (narrow with a `parentField` filter). Scoped `update` PATCHes the collection (the vendor keys the record by the id in the body).
+Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page guarded), `queryBounded` (server-side pagination — one call walks the cursor until `limit` TOTAL records, default 500 / max 2500, with a `hasMore` flag; the MCP `query` surface, routed by `invoke`), `queryAll` (collect → `T[]` — the unbounded raw walk), `count`, `get` (id → record; `item: null` → `NotFoundError`), `create` / `update` / `delete` (where the vendor defines them — mutations take a `MutationOpts` bag: `{ dryRun, lastModifiedDate?, maxRetries? }` (issue #105: `maxRetries` overrides the configured retry budget for every request the mutation issues; `0` = exactly one send per request)), plus the helper floor where the plan declares it: `resolve` (all 121), `search` (40 — bounded contains on the resource text field), `getContext` (5 workflow resources), `findBy<Field>` (3), `createIfNotExists` (14). Entity metadata on every resource: `getEntityInfo`, `getFieldInfo`, `getUdfInfo` (UDF-capable 16). Parent-scoped children take `(parentId, id)` on the CRUD methods and require `parentId` on `createIfNotExists` (the scoped create POSTs the scoped collection; the dedup query stays global); `query`/`count`/`resolve`/`search` stay global (narrow with a `parentField` filter). Scoped `update` PATCHes the collection (the vendor keys the record by the id in the body).
 
 | resource key | apiEntity | kind | tier | parent | standard ops present | special ops | mcpTool |
 |--------------|-----------|------|------|--------|----------------------|-------------|---------|
@@ -2141,6 +2333,64 @@ own. A match that `get(id)` would return can be invisible to the lookup, so a
 missed dedup can issue a duplicate create; treat dedup there as best-effort
 until the zone is re-verified.
 
+### 11.8a Structured `zoneFacts.quirks` entries (issue #253)
+
+The per-resource `quirks` on the `zoneFacts` block (§11.7) is structured, not
+free text — a `string[]` of campaign prose (dates, tenant names, operator
+advice) cannot ride to a model, but a clean statement + a filterable scope
+can. Each entry (`StructuredQuirk`):
+
+- `kind` — the closed 13-set (unknown kinds fail `capabilities:check`, clause
+  23, listing the valid set): `not-persisted` · `blind-surface` ·
+  `integer-picklist` · `wire-type` · `required-in-body` · `not-in-body` ·
+  `parent-scoped` · `field-constraint` · `vendor-managed-side-effect` ·
+  `cascade-delete` · `access-denied` · `unknown-field-noop` · `capability-note`
+  — four of the set are extensions forced by specific migrated strings:
+  `not-in-body` (the scoped-path-vs-body distinction), `field-constraint`
+  (live-verified VALUE constraints), `unknown-field-noop` (the vendor's
+  silent 200 on unknown fields), and `capability-note` (affirmative
+  capabilities).
+  Adding a kind later = one-line extension of the clause's `QUIRK_KINDS` + a
+  plan comment citing the issue; the clause id stays stable.
+- `ops` — the ops the fact applies to: the closed set `{count, create, query,
+  update, delete, all}` plus the host's own plan `specialOps` (membership
+  against the plan — the set never hard-codes what the plan already declares).
+  A server about to execute `billing_codes.count` keeps exactly the entries
+  whose `ops` include `count`. `archive` is deliberately not in the set (no
+  archive verb in the plan's op vocabulary).
+- `fields` — optional; the specific wire/model fields the fact constrains
+  (no membership check — names like `internalBillingCodeID` are by definition
+  outside the vendored spec).
+- `statement` — the clean model-facing sentence: tenant-neutral, date-free,
+  instruction-free.
+- `evidence` — the verbatim campaign string (the provenance home; frozen and
+  exempt from the hygiene gate — the same standing as `vendorEvidence` on the
+  same surface).
+
+**The clause 23 hygiene gate**
+(`scripts/lib/checks/clause23-structured-quirks.mjs`): a build clause that
+fails when a `statement` carries one of the enforced provenance pattern
+classes — clause 15's `PROVENANCE_PATTERNS` (campaign markers, tenant ids,
+branch names, ISO and short dates, 6+ digit ids, …) plus the #253 overrides
+(`live-verified` / `live-proven` / `proven` / `unproven`, `S9b`-style run
+codes, `UI-only`, `ask the operator|admin|vendor`, `australia-nz`, `node
+rule`, slash dates and month-name dates in both orders, `last`/`next`/`this`
++ a relative unit, ordinals like `the 21st`, `tenant` + a 5+ digit id,
+`cleanup`, and zone codes like `ww29` even mid-token) — or when an entry is
+shape-invalid (unknown kind, an op outside the closed set, an empty
+statement/evidence). The gate is a PATTERN FLOOR: it enforces the listed
+pattern classes; it is not a natural-language guarantee, so a well-formed
+date, tenant name or operator instruction in an unlisted shape can slip.
+`evidence` is NEVER gated. The 2026-10-28 migration replaced the old 11-host
+`string[]` in place: 28 raw strings → 28 structured entries, every old
+string preserved verbatim as its entry's `evidence`.
+
+**Consumer contract** (served via `relationshipMap(k).zoneFacts.quirks`,
+§9.1): filter entries on `ops`, feed `entry.statement` to the model, and
+treat `entry.evidence` with the same trust you already apply to
+`vendorEvidence` on this surface (plan-grade provenance, not model-facing
+prose). The old `string[]` shape is gone.
+
 ### 11.9 Delete-boundary awareness + the one-call recovery (issue #9)
 
 The §11.1 wall (7 live-verified 405 endpoints) is now a **spec-derived
@@ -2450,12 +2700,14 @@ metadata is (the `autotask_describe` channel, `capabilities.json`,
   condition is ever sent. The join is one `BillingItems` query per 250 ids;
   the entry read is capped at 500, so a call costs at most 1 read + 2 joins
   and a window with more than 500 entries returns the first 500 with
-  `hasMore` / `truncated` true. A 429 or vendor fault propagates as a typed
+  `hasMore` / `truncated` true and a `nextCursor` to continue from (or use
+  `countOnly` for the window's totals; see the paging bullet below). A 429 or vendor fault propagates as a typed
   error. The API user therefore needs BillingItems read permission; a permission fault propagates as a typed error.
 - **`time_entries.getPosted(opts?)` / `getUnposted(opts?)`** — `opts` is
-  `{ limit?, ticketID?, dateFrom?, dateTo? }` (`dateFrom`/`dateTo`:
+  `{ limit?, ticketID?, dateFrom?, dateTo?, cursor?, countOnly?, maxVendorCalls? }`
+  (the paging options: see the paging bullet below; `dateFrom`/`dateTo`:
   inclusive `dateWorked` days, `YYYY-MM-DD`, never tz-shifted). They return
-  `{ items, hasMore, window, approvedCount, unapprovedCount }` (a breaking
+  `{ items, hasMore, window, nextCursor, unconfirmed, approvedCount, unapprovedCount }` (a breaking
   change from the bare `TimeEntry[]`, 0.32.0): `getPosted` items are entries
   a billing item references; `getUnposted` items are entries none references.
   `approvedCount` / `unapprovedCount` are informational (items with / without
@@ -2468,7 +2720,7 @@ metadata is (the `autotask_describe` channel, `capabilities.json`,
   guard forbids Date positionals), one bounded read (`limit` 1-500, default
   500 — the hard cap, issue #128: a larger window needs `time_entries.query`
   with the same `dateWorked` filter, its 2500-row walk cap) returning
-  `{ items, postedCount, unpostedCount, window, truncated }`; the counts come
+  `{ items, postedCount, unpostedCount, window, nextCursor, unconfirmed, truncated }`; the counts come
   from the billing-item join (any billing item referencing the entry), `opts.posted` narrows client-side after the join
   (true = posted only, false = unposted only, omitted = both); the counts still split every entry read (before the narrowing), so `items.length` can differ from their sum and `ticketID` /
   `resourceID` narrow the read. Live evidence for the visibility class
@@ -2490,6 +2742,57 @@ metadata is (the `autotask_describe` channel, `capabilities.json`,
   but, since 0.24.0, it never shifts the bounds: `dateWorked` is a date-only
   value at 00:00 UTC, so `from`/`to` are the days (see §7.11). The same `tz`
   opt is on every date-window op — see §11.22.
+- **Paging past 500 entries and whole-window totals (issue #242)** — all four
+  ops (`getPosted`, `getUnposted`, `postedWithin`, `dateWorkedWindow`) take
+  three more options:
+  - `cursor?: string` — every rows result now carries `nextCursor: string | null`
+    (the vendor's next-page cursor for the entry read). Pass it back as
+    `opts.cursor` with the **same** window and filters to read the next page;
+    each call stays one entry page (the vendor's continuation page, up to 500
+    entries; `limit` sizes the first page only) plus at most 2 joins. Loop
+    until `nextCursor` is `null` to enumerate a busy window. An off-origin
+    cursor, or a same-origin cursor whose path is not the TimeEntries
+    continuation (`/V1.0/TimeEntries/query/next`), or a cursor longer than
+    2,048 characters, is refused (`RESPONSE_REJECTED`) before any request. Every rows result also carries
+    `unconfirmed: number`: the entries on this page whose billing-item join
+    page was truncated. They are withheld from `items` (getPosted /
+    getUnposted) and from both counts (postedWithin / dateWorkedWindow, which
+    also withhold them from `items` when `posted` is set; with `posted`
+    omitted they stay in `items`, unclassified), so a cursor loop does not
+    see them as posted or unposted; `unconfirmed` is 0 normally, and when it is
+    above 0 `hasMore` / `truncated` is also true. Sum it across a loop to know
+    how many entries went unclassified (or use `countOnly`, which refuses
+    instead).
+  - `countOnly?: true` — returns only the whole window's totals:
+    `{ window, total, postedCount, unpostedCount, vendorCalls, estimate, budget }`
+    (typed overloads select `TimeEntriesPostedCountResult`). One
+    `TimeEntries/query/count` call sizes the window; then every entry page is
+    read ids-only (`IncludeFields: ['id']`, following the vendor cursor) and
+    joined at 250 ids per join, and the window is counted again after the walk.
+    `total` = `postedCount + unpostedCount` (de-duplicated by id). The call
+    fails with `INVALID_RESPONSE` (`details: { reason: 'count_mismatch',
+    streamed, counted, recounted }`) when the distinct-id total equals NEITHER
+    the count before the walk NOR the count after it (a page repeated one entry
+    and dropped another); a total equal to either count is accepted, so a
+    window that grows or shrinks by the time the walk ends still succeeds, and
+    one that changes mid-walk can fail or pass depending on timing: retry.
+    `limit` and `posted` do not apply; `cursor` is rejected with `countOnly`
+    (CONFIG_ERROR).
+  - `maxVendorCalls?: number` — the `countOnly` budget (integer 1-200,
+    default 30). The estimate is `1 + max(1, ceil(n / 500)) + ceil(n / 250) + 1`
+    (the last 1 is the re-count) from the count `n` (the live week of 1,321 entries costs 11). The budget
+    and `vendorCalls` count logical requests; transport retries of a 429 /
+    5xx (up to `maxRetries` each) are not counted. Over budget
+    the call throws `BUDGET_EXCEEDED` (category `policy`, `details: { estimate,
+    budget, total, issued }`, a `suggestedAction` naming a narrower window or
+    `maxVendorCalls >= estimate`) after the count call and before any page
+    read. The same code stops a walk that needs more calls than estimated
+    (more entries than counted, or an extra page such as an empty
+    continuation page) before the call that would exceed the budget, the
+    closing re-count included; its `suggestedAction` names a narrower window
+    or a `maxVendorCalls` above the budget, never `>= estimate`. A
+    truncated join throws `RESOLUTION_TRUNCATED`, and a 429 propagates as
+    `RATE_LIMITED`: the total is complete or not returned.
 - **Drifted-create marker recovery (issue #13)** — where the plan pins a
   `responseDrift` row (the pinned resource: `ticket_checklist_libraries`,
   the W-A7 drift: the vendor answers 200 with a body that is not
@@ -2587,10 +2890,17 @@ there is no second entity-type table.
 parallel field system, and the served row states it rather than leaving it
 inferred. With the `udf` include, the row's `udf` list holds the UDF
 DEFINITIONS the vendor's `entityInformation/userDefinedFields` channel
-returns — `name`, `label`, `type`, `isRequired`, `isReadOnly`, `isPickList`,
-`isReference`, `referenceEntityType`, `picklistValues` (the values ride the
-`labels: true` opt, zero extra wire), `defaultValue`. A UDF definition never
-appears in the plan artifact (it is tenant-specific). The row also carries
+returns, projected to `name`, `label` (when non-empty), `type`, `isRequired`,
+`isReadOnly`, `filterable: 'udf-marker'`, `isPickList`, `maxLength`,
+`referenceEntityType`, `targetResource`, `targetEnumerable`, and
+`picklistValues` (the values ride the `labels: true` opt, zero extra wire;
+present only for a picklist that exposes values). The vendor's `isReference`
+and `defaultValue` are not projected. A UDF definition never
+appears in the plan artifact (it is tenant-specific). The row's `udfCapable`
+is the plan resource flag (16 resources), which every capability record also
+carries as `CapabilityRecord.udfCapable` (issue #254); every vendor entity has
+a `getUdfInfo` catalog endpoint, so that op's presence does not make a
+resource UDF-capable. The row also carries
 `udfFilter: 'udf-marker'` and `udfWriteShape: 'merge'` exactly when it is
 `udfCapable`: a filter on a UDF NAME is accepted by the vendor only with the
 `udf: true` marker, so a UDF field row serves `filterable: 'udf-marker'` and

package/docs/LIVE-TESTING.md

@@ -128,25 +128,25 @@ DRY-RUN-ONLY verdict (the only no-credentials path, exit 0).
 
       npm run live-coverage -- --only tickets          # one resource's ops
       npm run live-coverage -- --only configuration_item_ssl  # the cisan node-parity op
-      npm run live-coverage                             # FULL sweep: 1182 rows, --max-calls 1600
+      npm run live-coverage                             # FULL sweep: 1281 rows, --max-calls 1600
 
 Full-sweep budget (worst case, every table non-empty — the machine-readable
-number is the report's `budget` block): PLAN-HONEST 930 bounded op calls
+number is the report's `budget` block): PLAN-HONEST 1016 bounded op calls
 (every read/helper row = at most ONE bounded call — reads use
 `queryBounded` limit 2, a TOTAL cap; the served-artifact rows —
 operations.blindSurfaces (issue #11), operations.createGuidance (issue
 #12) — plan the op call at ZERO wire, but still count as one op call in
-this number: the budget counts ROW calls, not raw wire, so the 930 is the
-conservative row-based figure, 907 if the zero-wire rows are subtracted)
-+ <=77 best-effort update diff GETs
-+ <=121 cached limit-1 id reads (one per resource; the parent chain shares
-the cache) = <= 1128. WIRE-HONEST: the dry-run verification reads ride on
+this number: the budget counts ROW calls, not raw wire, so the 1016 is the
+conservative row-based figure)
++ <=82 best-effort update diff GETs
++ <=129 cached limit-1 id reads (one per resource; the parent chain shares
+the cache) = <= 1227. WIRE-HONEST: the dry-run verification reads ride on
 top — 54 delete current-record GETs + 63 scoped-create parent-verify GETs
-+ 20 getContext part GETs + <=15 special-op reads (incl. the issue #9
++ 20 getContext part GETs + <=18 special-op reads (incl. the issue #9
 `operations.recovery` dry-run find — ONE bounded query, zero mutating
-wire) = <=152 — so the worst case is <= 1280 raw wire requests. The 1600
---max-calls cap bounds the row-based plan (actualCalls <= 1128); the wire
-count cannot exceed plan + the stated verification set (and 1280 is far
+wire) = <=155 — so the worst case is <= 1382 raw wire requests. The 1600
+--max-calls cap bounds the row-based plan (actualCalls <= 1227); the wire
+count cannot exceed plan + the stated verification set (and 1382 is far
 under the API's 10k req/hour). ZERO mutating requests: every mutation travels
 `dryRun: true` (the sweep flag + the SDK governor's dry-run-first default,
 double-locked; pinned per-resource in the generated test suite), and EVERY

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.34.0",
+  "version": "0.37.0",
   "description": "Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime dependencies. Built for building MCP servers and integrations.",
   "type": "module",
   "sideEffects": false,