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/CHANGELOG.md +11 -0
- package/MCP_TOOL_CATALOG.json +1 -1
- package/README.md +6 -0
- package/capabilities.json +4 -4
- package/dist/capabilities-data.js +3 -3
- package/dist/{chunk-FK37JXSJ.js → chunk-3RANR2RY.js} +408 -161
- package/dist/{chunk-EWXRFHPP.cjs → chunk-GVP2WW47.cjs} +175 -175
- package/dist/{chunk-MMGO3SFL.js → chunk-MN5VLBCI.js} +1 -1
- package/dist/{chunk-64BMSXWT.js → chunk-TYUTIZWB.js} +2 -2
- package/dist/{chunk-WFVLF7EW.cjs → chunk-YQX45JBG.cjs} +30 -30
- package/dist/{chunk-CLHDTYWO.cjs → chunk-YRRTE2NF.cjs} +408 -160
- package/dist/{index-Coe7LFLY.d.ts → index-By9Zw2Oc.d.ts} +8 -2
- package/dist/{index-BT_0tTPS.d.cts → index-CGW80Uzc.d.cts} +8 -2
- package/dist/index.cjs +83 -83
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +4 -4
- package/dist/operations/index.cjs +53 -49
- package/dist/operations/index.d.cts +22 -4
- package/dist/operations/index.d.ts +22 -4
- package/dist/operations/index.js +1 -1
- package/dist/pool.cjs +11 -11
- package/dist/pool.js +3 -3
- package/dist/resources/index.cjs +26 -26
- package/dist/resources/index.d.cts +1 -1
- package/dist/resources/index.d.ts +1 -1
- package/dist/resources/index.js +2 -2
- package/docs/API.md +45 -0
- package/docs/N8N-ADAPTER.md +1 -1
- package/docs/performance-caching.md +92 -0
- package/docs/performance-reads.md +9 -1
- package/package.json +1 -1
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
|
package/docs/N8N-ADAPTER.md
CHANGED
|
@@ -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
|
|
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.
|
|
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,
|