node-autotask 0.69.1 → 0.70.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/API.md CHANGED
@@ -1208,6 +1208,51 @@ be cross-mode-refused.
1208
1208
  **Harness approval policy (recommended).** Require approval on every tool whose MCP annotation is `readOnlyHint !== true` — today exactly **252 tools**: the 250 dedicated write/delete tools (194 `effect=write` + 56 `effect=destructive`, every one of them has a dedicated tool) + `autotask_write` + `autotask_delete`. The remaining **611 tools** (the 598 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). Refined class for the highest-risk ops: the **57 tools with `destructiveHint: true`** (56 dedicated delete tools + `autotask_delete`) additionally require `confirm === <operation key>` even inside `autotask_delete`. The approval-gated writes (`configuration_items.moveConfigurationItem`, `contacts.moveToCompany`) require the same confirm inside `autotask_write`. Migration: `autotask_invoke` is REPLACED by `autotask_read`/`autotask_write`/`autotask_delete` — update harness config and remove any `autotask_invoke` entry. The rule is derivable from the registry `effect` column and the mode tools’ fixed annotations; it never needs a hand-maintained name list.
1209
1209
  <!-- END GENERATED:approval-policy -->
1210
1210
 
1211
+ ### 7.4a `invokeReadPages` — governed bounded page consumption
1212
+
1213
+ `invokeReadPages(client, operation, args, onPage, opts?)` is an additive utility from
1214
+ `node-autotask/operations` for primitive query operations with an explicit
1215
+ `walk.maxRows`. It uses the same invocation admission and bounded pagination engine
1216
+ as `invokeRead`; existing collected reads retain their result shape.
1217
+
1218
+ ```ts
1219
+ import type { AutotaskClient } from 'node-autotask';
1220
+ import { invokeReadPages } from 'node-autotask/operations';
1221
+
1222
+ async function exportTickets(
1223
+ client: AutotaskClient,
1224
+ companyId: number,
1225
+ writeRows: (items: readonly unknown[]) => Promise<void>,
1226
+ ) {
1227
+ return invokeReadPages(client, 'tickets.query', [{
1228
+ filter: [{ field: 'companyID', op: 'eq', value: companyId }],
1229
+ limit: 500,
1230
+ walk: { maxRows: 10_000 },
1231
+ }], async ({ items }) => {
1232
+ await writeRows(items);
1233
+ });
1234
+ }
1235
+ ```
1236
+
1237
+ Each callback receives `{ items, page }`, with served rows and a page ordinal. The
1238
+ SDK awaits the callback before fetching another page, so the consumer controls
1239
+ backpressure. Rows already carry the bounded walk's per-page names and requested
1240
+ note truncation. The fulfilled promise is the terminal bounded summary without
1241
+ `items`, retaining fetched/page counts, incompleteness and applicable scope, name,
1242
+ relation or blind/empty evidence. A row cap is not proof of a complete result;
1243
+ inspect the returned summary.
1244
+
1245
+ Unsupported operations, non-walk queries, `latest`, invalid callbacks and unsupported
1246
+ holders are refused before query wire. Field-name authority, scope preflight,
1247
+ continuation bodies, host checks and transport thread/hourly limits remain in their
1248
+ existing owners. This is not a new MCP registry operation or a raw iterator bypass.
1249
+
1250
+ Keep the caller's signal active for the entire promise, including callback work.
1251
+ An error or cancellation, including during the final callback, cannot resolve a
1252
+ successful completion summary. The consumer owns cleanup of partially written
1253
+ files or other output. Ordinary `invokeRead`, direct iterators and `latest` retain
1254
+ their existing contracts; general query/report response caching is not added.
1255
+
1211
1256
  ### 7.5 the `create` dry-run delete-boundary warning (issue #9)
1212
1257
 
1213
1258
  The delete-boundary reality (§11.1, §11.9): the vendored spec defines NO
@@ -42,7 +42,7 @@ Two sources in, markdown table out: the node repo (the ops column is re-derived
42
42
  | `checklistLibraries` | ChecklistLibrary | no | create, update, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
43
43
  | `checklistLibraryChecklistItems` | ChecklistLibraryChecklistItem | yes | create, update, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, update |
44
44
  | `classificationIcons` | ClassificationIcon | no | get, getMany, count | — | count, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search |
45
- | `companies` | Company | no | create, update, get, getMany, count, searchByIdentity, searchByDomain | searchByDomain → `companies.searchByDomain`; searchByIdentity → `companies.searchByIdentity` | count, create, fullProfile, get, getContext, getEntityInfo, getFieldInfo, getUdfInfo, prepareCrmWrite, query, resolve, search, searchByDomain, searchByIdentity, unbilledWork, update |
45
+ | `companies` | Company | no | create, update, get, getMany, count, searchByIdentity, searchByDomain | searchByDomain → `companies.searchByDomain`; searchByIdentity → `companies.searchByIdentity` | count, create, fullProfile, get, getContext, getEntityInfo, getFieldInfo, getUdfInfo, prepareCrmWrite, query, resolve, search, searchByDomain, searchByIdentity, searchFuzzy, unbilledWork, update |
46
46
  | `companyAlerts` | CompanyAlert | yes | create, update, delete, get, getMany, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, update |
47
47
  | `companyLocations` | CompanyLocation | yes | create, get, getMany, update, delete, count | — | count, create, delete, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
48
48
  | `companyNotes` | CompanyNote | yes | create, update, get, getMany, count | — | count, create, get, getEntityInfo, getFieldInfo, getUdfInfo, query, resolve, search, update |
@@ -0,0 +1,92 @@
1
+ # Cache evaluation and derived metadata
2
+
3
+ Round 3 evaluates retention separately from repeated CPU work. A warm metadata read already avoids
4
+ vendor wire, but cloning the full catalog and rebuilding the same field or picklist projections can
5
+ still dominate local work. Entry-owned derived views address that cost without extending freshness.
6
+
7
+ ## Retention decisions
8
+
9
+ | Channel | Existing policy | Round-3 decision |
10
+ | --- | --- | --- |
11
+ | Ordinary record GETs | Five-minute default; successful redacted values only; fresh bypass and mutation epoch | Retain existing behavior |
12
+ | Selected reference GETs | BillingCodes, Countries, Departments, Phases, Roles and Services use at least one hour | Retain the existing allowlist and TTL; no additional entity or longer window is justified |
13
+ | Entity/field/UDF metadata | Five-minute default; nonempty successful metadata only; entity invalidation on drift | Reuse derived work only within the same live entry |
14
+ | Company name index | Separate existing bounded cache and explicit incomplete-index disclosure | Preserve its current owner, retention and cache-off semantics |
15
+ | Query/report results | No general response cache | Defer; do not introduce an opt-in flag without a complete freshness contract |
16
+
17
+ Ordinary records retain their existing default too. A reference label may be changed externally,
18
+ even for an entity that usually changes slowly. Local mutation invalidation cannot observe an
19
+ administrator, another integration or a permission change. Extending retention would lengthen the
20
+ existing stale window; a synthetic warm-cache benchmark does not establish an acceptable new one.
21
+ No production hit-rate trace or external-update frequency was supplied to justify that tradeoff.
22
+
23
+ `cache: false` disables every cache channel. Explicit fresh mutation, drift and verification reads
24
+ remain fresh. Pooled credential/origin/impersonation isolation and the existing entry bounds still
25
+ apply. A cached financial result must never be presented as newly collected completeness or budget
26
+ evidence; this round does not cache those results.
27
+
28
+ ## Derived-work ownership
29
+
30
+ Derived metadata belongs to the exact retained cache entry, rather than a second TTL map. Stable
31
+ internal projectors define bounded variants; metadata kind and label options must distinguish
32
+ different projections. Caller-specific fields, compact formatting and byte trimming remain
33
+ per-call reductions unless their entire option set is represented by a variant.
34
+
35
+ Refreshing, replacing, evicting, expiring or invalidating an entry drops its retained derived work.
36
+ An old in-flight subscriber still receives its original result; it cannot borrow a newer entry's
37
+ index after an intervening refresh. Failed or empty reads are not retained. Cancellation, private
38
+ quota recovery and report-specific error observation remain in the common subscriber adapter.
39
+
40
+ For retained cache entries, projection builders receive an isolated value, and mutable returned
41
+ views remain independent of the cache and each other. Fake or overridden metadata readers retain
42
+ their original value semantics; their ephemeral projections are not retained or newly cloned.
43
+ Older SDK/cache copies without the explicit projected-read capability use ordinary cloned reads
44
+ and ephemeral derivation. The immutable vendored model-field index is separate: live metadata and
45
+ current live-only/UDF exemptions still decide runtime field authority.
46
+
47
+ ## What would justify a query/report cache later
48
+
49
+ First collect a representative hit-rate trace and define which external changes may remain stale.
50
+ The key would need the full canonical request, credential and impersonation scope, permissions,
51
+ time window, row/wire caps, projection and label options. Partial, failed or budget-limited results
52
+ need an explicit policy, as do mutation invalidation, externally changed records, eviction and
53
+ cancellation. Completeness, collection times and consumed-budget evidence must remain truthful.
54
+ Until those decisions and measurements exist, caching a result to improve a toy repeated-query
55
+ benchmark is not sufficient evidence to ship it.
56
+
57
+ ## Measurement scope
58
+
59
+ The baseline uses synthetic metadata with a fixed field count and repeated warm reads. It measures
60
+ raw metadata, filtered/labelled and compact catalog views, validation and ticket-status consumers;
61
+ cold/warm wire counts, retained entries, output equality, CPU and memory are separate observations.
62
+ Warm metadata should keep zero vendor wire; a derived cache is useful only if it also removes
63
+ meaningful repeated work. Timings are fixture measurements, never a production latency guarantee.
64
+
65
+ Paired runs used synthetic metadata with 500 fields and 200 warm calls per workload. Median local
66
+ elapsed times were:
67
+
68
+ | Consumer | Before, ms | After, ms |
69
+ | --- | --- | --- |
70
+ | Live field validation | 206.68 | 35.20 |
71
+ | Ticket-status semantics | 202.14 | 5.10 |
72
+ | Composite picklist labels | 255.47 | 63.55 |
73
+ | Full catalog without values | 249.33 | 141.42 |
74
+ | Filtered catalog with values | 279.22 | 235.48 |
75
+ | Filtered compact catalog with byte cap | 240.19 | 225.72 |
76
+
77
+ Outputs matched in every workload. Each cold case made one metadata request and retained one raw
78
+ entry; warm calls made no vendor requests. An unchanged raw-read control varied between runs, so
79
+ the modest compact-catalog difference is not a reliable production speedup claim.
80
+
81
+ Derived views trade retained memory for CPU. In a separate forced-GC diagnostic, 50 independent
82
+ clients each warmed all applicable views over the same synthetic metadata. Heap growth was about
83
+ 8.43 MB before versus 37.48 MB after; RSS growth was about 46.79 MB versus 120.46 MB. Raw serialized
84
+ data was unchanged, with approximately 13.53 MB of additional serialized views. These are decimal
85
+ megabytes and process observations, not exact object-size or production-memory guarantees.
86
+ This deliberately exercises every variant, rather than a single common read path.
87
+
88
+ The cache keeps a hard bound on variants per entry, creates their storage lazily and retains no
89
+ extra projection map for ordinary reads that do not use it. Changing request field filters does
90
+ not create new variants. A tested catalog-base alternative reduced retained views but repeatedly
91
+ regressed catalog CPU; the selected implementation keeps the measured tradeoff explicit. This
92
+ optimization does not claim lower metadata-cache memory or longer freshness.
@@ -40,7 +40,15 @@ can delay newer callers. No second capacity pool is created to avoid that delay.
40
40
  The static model-field membership helper indexes only immutable vendored schema
41
41
  names. It exposes no mutable set and allocates nothing for unknown resources. Live
42
42
  metadata, cache generations and current record exemptions are not stored in this
43
- index. Tenant-derived projection caching remains a separate evaluation in #459.
43
+ index. Tenant-derived views are tied to their own live cache entry rather than this
44
+ static schema index; [cache evaluation and ownership](performance-caching.md) records
45
+ the retention decisions and their limits.
46
+
47
+ `invokeReadPages` supplies governed bounded page consumption for export consumers.
48
+ It shares invocation admission and the bounded walk with collected reads, awaits
49
+ each page callback and returns terminal completeness evidence without retaining all
50
+ rows. Raw iterators are not substituted for the governed path. The callback controls
51
+ backpressure; consumers remain responsible for partial-output cleanup on failure.
44
52
 
45
53
  ## Measurement scope
46
54
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-autotask",
3
- "version": "0.69.1",
3
+ "version": "0.70.0",
4
4
  "description": "Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime dependencies. Built for building MCP servers and integrations.",
5
5
  "type": "module",
6
6
  "sideEffects": false,