node-autotask 0.69.0 → 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.
@@ -1,5 +1,5 @@
1
1
  import '../chunk-YL6HXU33.js';
2
- export { AuthenticateResource, ConfigurationItemsResource, ContactsResource, EntityInformationResource, InventoryProductsResource, ModulesResource, QuotesResource, ResourceTimeOffAdditionalResource, ResourceTimeOffBalancesResource, ResourcesResource, ServiceCallsResource, ThresholdInformationResource, TicketChargesResource, TicketsResource, TimeOffRequestsResource, VersionInformationResource, VersionResource, ZoneInformationResource } from '../chunk-AH6WAGPS.js';
3
- export { CompaniesResource, ContractsResource, GenericResource, InvoicesResource, SIMPLE_RESOURCES, TimeEntriesResource } from '../chunk-QDBJCGQD.js';
2
+ export { AuthenticateResource, ConfigurationItemsResource, ContactsResource, EntityInformationResource, InventoryProductsResource, ModulesResource, QuotesResource, ResourceTimeOffAdditionalResource, ResourceTimeOffBalancesResource, ResourcesResource, ServiceCallsResource, ThresholdInformationResource, TicketChargesResource, TicketsResource, TimeOffRequestsResource, VersionInformationResource, VersionResource, ZoneInformationResource } from '../chunk-MN5VLBCI.js';
3
+ export { CompaniesResource, ContractsResource, GenericResource, InvoicesResource, SIMPLE_RESOURCES, TimeEntriesResource } from '../chunk-3RANR2RY.js';
4
4
  import '../chunk-SCFB5MF3.js';
5
5
  import '../chunk-7NKB4UXV.js';
package/docs/API.md CHANGED
@@ -104,6 +104,14 @@ worker realms do not share it. Entries are removed after active and queued work
104
104
  The permit remains held through response-body consumption. `ZoneInformation`
105
105
  is exempt. The SDK does not offer a higher-capacity override for older integrations.
106
106
 
107
+ Transport admission reserves client and object capacity together. A request
108
+ waiting for a busy object holds no client slot, and a request waiting for its
109
+ client holds no object slot. Among requests whose two capacities are available,
110
+ the oldest queued request is admitted first, including across clients.
111
+ Already-loaded SDK 0.69 copies keep their existing object permits and FIFO
112
+ waiters; those legacy waiters retain priority, so sustained legacy traffic can
113
+ delay newer callers. No second object pool is created to bypass that traffic.
114
+
107
115
  Vendor thread limits are scoped to the object and tracking identifier within an
108
116
  Autotask instance; integrations developed after the 2023.1 release have a limit
109
117
  of 3, while integrations from before 2022.1 can retain higher measured limits.
@@ -1200,6 +1208,51 @@ be cross-mode-refused.
1200
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.
1201
1209
  <!-- END GENERATED:approval-policy -->
1202
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
+
1203
1256
  ### 7.5 the `create` dry-run delete-boundary warning (issue #9)
1204
1257
 
1205
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.
@@ -0,0 +1,71 @@
1
+ # Shared read scheduling
2
+
3
+ The transport owns wire admission. `mapReadTasks` and `readTasks` bound task starts,
4
+ inherit ambient cancellation, return results in input order, stop queued work after
5
+ a terminal failure and drain started tasks. Their consumers share these primitives:
6
+
7
+ | Consumer | Independent work | Required ordering |
8
+ | --- | --- | --- |
9
+ | `resolveAny` | Exact lookups across resources | Every exact outcome precedes a clean-miss contains fallback |
10
+ | `searchAcrossResources` | Searches without `totalLimit` | A total limit retains request-order quota allocation and `notSearched` semantics |
11
+ | `fieldCatalog` | Resource/kind reads after validation and cap checks | Fresh invalidation precedes reads; row/error/counter reduction follows declared order |
12
+ | `fetchByIds` | Group query phases, then individual fallback GETs | Group query authority and chunks settle before fallback; final projections follow original inputs |
13
+ | `labelFetchResults` | Groups whose name targets are all disjoint | Any shared target retains serial traversal for warming budgets and fatal-error order; notes/reasons merge in resource order |
14
+ | Relation filters | Flat OR parent lookups | AND and nested short-circuit paths stay ordered; empty parents can suppress child wire |
15
+
16
+ Label groups use the same FK plan as label reads to identify dependencies. If any
17
+ target is shared, the call retains its original serial traversal: a name read by an
18
+ earlier group is free in a later group's budget, and a later disjoint failure cannot
19
+ hide an earlier dependent failure. Fully disjoint groups use the common bounded
20
+ executor. Relation-query reuse is local to
21
+ one rewrite and keyed by the normalized request; it is discarded at return and is
22
+ not a response cache.
23
+
24
+ `cachedRecordGet` and `cachedMetadataGet` share `cachedRead` and `TtlCache.load`.
25
+ Metadata subscribers receive separate values/errors and cancel independently;
26
+ invalidation detaches old flights, and empty metadata is returned without retention.
27
+ The base metadata readers and ticket-status field reads use the same keys. Cache-off
28
+ keeps direct reads, and report-specific failure observation and private quotas remain
29
+ attached to each subscriber.
30
+
31
+ `acquireTransport` grants a request only when both its client allowance and shared
32
+ object semaphore have capacity. Waiting requests hold neither. Every actual attempt
33
+ still passes hourly admission immediately before fetch, and leases last through body
34
+ consumption. Indexed client/object queues reconsider affected front waiters, without
35
+ scanning the whole backlog; shared signal listeners batch cancellation cleanup.
36
+ The authoritative v1 object registry is retained across SDK copies;
37
+ older queued callers keep their original FIFO priority and sustained legacy traffic
38
+ can delay newer callers. No second capacity pool is created to avoid that delay.
39
+
40
+ The static model-field membership helper indexes only immutable vendored schema
41
+ names. It exposes no mutable set and allocates nothing for unknown resources. Live
42
+ metadata, cache generations and current record exemptions are not stored in this
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.
52
+
53
+ ## Measurement scope
54
+
55
+ Deferred tests prove overlap, ordering, draining, limits and output equality. Synthetic
56
+ routed-vendor comparisons use fixed latency and compare serial/parallel execution:
57
+ exact resolution and uncapped search overlap their independent resources; bulk reads
58
+ retain the query/fallback dependency. Cold/warm wire counts remain equal between
59
+ scheduling modes. These measurements demonstrate scheduling gains, not production
60
+ latency guarantees.
61
+
62
+ An offline admission backlog comparison reduced the time to grant and release 20,000
63
+ leases from about 79 seconds to 0.36 seconds after indexed scheduling. Work-count
64
+ regressions cover shared-object, shared-client and mixed backlogs without relying on
65
+ wall-clock thresholds. No vendor request is made by this benchmark.
66
+
67
+ A synthetic repeated field-authority workload reduced median CPU time from about
68
+ 23 ms to 8 ms per 5,000 checks after static indexing, with identical results. Required
69
+ result cloning and live metadata authority remain intact. Real API validation uses
70
+ read-only bounded probes with separate timings and call counts; it does not increase
71
+ vendor limits to obtain overlap.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-autotask",
3
- "version": "0.69.0",
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,