node-autotask 0.68.1 → 0.69.1
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 +26 -0
- package/MCP_TOOL_CATALOG.json +2 -2
- package/README.md +51 -10
- package/capabilities.json +7 -7
- package/dist/capabilities-data.js +6 -6
- package/dist/capabilities.cjs +4 -4
- package/dist/capabilities.js +1 -1
- package/dist/{chunk-LOLWHPTJ.js → chunk-64BMSXWT.js} +3 -30
- package/dist/{chunk-XKIRTR37.cjs → chunk-CLHDTYWO.cjs} +1405 -488
- package/dist/{chunk-2D2KJOX2.cjs → chunk-EWXRFHPP.cjs} +236 -222
- package/dist/{chunk-YYHCZRUH.js → chunk-FK37JXSJ.js} +1398 -483
- package/dist/{chunk-SGH7F2CH.cjs → chunk-KAZE4WC7.cjs} +3 -3
- package/dist/{chunk-S6HEIGGM.js → chunk-MMGO3SFL.js} +80 -66
- package/dist/{chunk-JCMXQUIC.js → chunk-SCFB5MF3.js} +3 -3
- package/dist/{chunk-KRQONGLD.cjs → chunk-WFVLF7EW.cjs} +30 -57
- package/dist/{index-mIsdpO5d.d.cts → index-BT_0tTPS.d.cts} +19 -12
- package/dist/{index-DQ08uOH0.d.ts → index-Coe7LFLY.d.ts} +19 -12
- package/dist/index.cjs +92 -85
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +14 -7
- package/dist/operations/index.cjs +50 -50
- package/dist/operations/index.d.cts +2 -2
- package/dist/operations/index.d.ts +2 -2
- package/dist/operations/index.js +2 -2
- package/dist/pool.cjs +12 -12
- package/dist/pool.js +4 -4
- package/dist/resources/index.cjs +27 -27
- package/dist/resources/index.d.cts +1 -1
- package/dist/resources/index.d.ts +1 -1
- package/dist/resources/index.js +3 -3
- package/docs/API.md +85 -16
- package/docs/LIVE-TESTING.md +16 -2
- package/docs/VENDOR-QUIRKS.md +39 -0
- package/docs/performance-finance.md +35 -0
- package/docs/performance-reads.md +63 -0
- package/examples/mcp-env-config.ts +3 -4
- package/package.json +1 -1
package/docs/API.md
CHANGED
|
@@ -88,11 +88,69 @@ a 429 at once, as before #105), while 5xx/network errors are auto-retried only
|
|
|
88
88
|
for GET and idempotent-flagged calls: a mutation makes exactly one send on a
|
|
89
89
|
5xx or network error (the write-outcome is unknown once the body was written);
|
|
90
90
|
an explicit `idempotent: true` on a mutation opts back into the pre-#105
|
|
91
|
-
auto-retry on all legs — plus a concurrency guard
|
|
92
|
-
|
|
91
|
+
auto-retry on all legs — plus a per-client aggregate concurrency guard
|
|
92
|
+
(`maxConcurrent`, default 10, permitting parallel work across different objects),
|
|
93
|
+
a shared per-object thread gate (below), one correlation id per request (surfaced on every
|
|
93
94
|
error and to `onAudit`), and the opt-in client-side hourly budget tracker
|
|
94
|
-
(`rateLimit.perHour`, default off — a sliding one-hour window that waits for a slot within the call deadline, else throws `RateLimitError` with `retryAfter`; the
|
|
95
|
+
(`rateLimit.perHour`, default off — a sliding one-hour window that waits for a slot within the call deadline, else throws `RateLimitError` with `retryAfter`; the database-wide vendor threshold is 10,000 req/hour across all integrations). The optional tracker is PER CLIENT: it counts only this client's attempts and cannot see other instances or integrations on the tenant (`thresholdInformation.get()` is the only cross-integration signal; the local count is `client.hourlyBudget()`, section 3.2.1). Under the `agent` config profile the exhaustion `suggestedAction` says stop or narrow the query — never raise the limit.
|
|
95
96
|
Redirects are never followed (a 3xx throws `REDIRECT_BLOCKED`, so auth headers cannot leave the configured origin). Retry waits are capped at 60 s and never outlast the call deadline: a larger `Retry-After` (or one that exceeds the remaining budget) throws the `RateLimitError` immediately. `RequestOptions` adds `signal` (caller `AbortSignal`, combined with the deadline; aborting throws `AutotaskAbortError`, code `ABORTED`, and cancels retry sleeps) and `idempotent` (retry a non-GET method on 5xx/network errors; set on the `/query` and `/query/count` POST reads; on a mutation it is the issue #105 opt-back into the pre-#105 auto-retry — never set on real writes by the SDK). `client.withSignal(signal, () => ...)` applies a caller `AbortSignal` to every request (and retry wait) made inside the callback — the way to propagate MCP request cancellation through `invoke` without a signal parameter on each method. A real write clears the read cache. A non-JSON 2xx body is typed by the response `Content-Type` (section 2.1): a non-JSON-ish header throws the retryable `UNEXPECTED_CONTENT_TYPE` (the edge/maintenance page — a maintenance notice is waited out up to `maintenanceMaxWaitMs`, default 1 h, for reads and writes; the same wait recognises the page at any status for calls safe to re-send (a GET or an explicitly idempotent-flagged call — an unflagged mutation makes ONE send with `details.maintenanceDetected`): section 2.1; otherwise a GET or idempotent-flagged call retries and a write makes one call); a JSON-ish or ABSENT header keeps `INVALID_RESPONSE` (the #13/W-A7 shape-drift key); JSON under any other header still decodes (the decode attempt is unconditional). A blank 2xx on a call that expects a result (every method but `DELETE` by default — `RequestOptions.expectBody`) throws the typed `EMPTY_RESPONSE` (`DELETE` and 204 keep returning `undefined`). A response above `maxResponseBytes` throws `RESPONSE_TOO_LARGE`; HTTP 412 maps to `ConflictError` (category `conflict`).
|
|
97
|
+
The per-object thread gate is independent of `maxConcurrent`: active requests
|
|
98
|
+
with the same normalized origin, hashed tracking identifier and canonical object
|
|
99
|
+
share a fixed ceiling of 3. It applies to every HTTP verb and normalizes query,
|
|
100
|
+
count, metadata, cursor and global/scoped aliases to the same object. API user,
|
|
101
|
+
secret rotation, impersonation and `cache: false` do not create extra capacity.
|
|
102
|
+
The registry is shared by ESM and CJS loads in the same JavaScript realm;
|
|
103
|
+
worker realms do not share it. Entries are removed after active and queued work settles.
|
|
104
|
+
The permit remains held through response-body consumption. `ZoneInformation`
|
|
105
|
+
is exempt. The SDK does not offer a higher-capacity override for older integrations.
|
|
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
|
+
|
|
115
|
+
Vendor thread limits are scoped to the object and tracking identifier within an
|
|
116
|
+
Autotask instance; integrations developed after the 2023.1 release have a limit
|
|
117
|
+
of 3, while integrations from before 2022.1 can retain higher measured limits.
|
|
118
|
+
The documented thread-latency tier starts at 3 concurrent requests to an object.
|
|
119
|
+
Use lower configured concurrency and coordinate shared-identifier traffic when
|
|
120
|
+
leaving room or avoiding that tier matters. The live performance harness uses an
|
|
121
|
+
aggregate cap of 2. The SDK's in-process coordination cannot account for external
|
|
122
|
+
integrations, other processes, worker realms or different origins
|
|
123
|
+
serving the same database. It does not guarantee safety against that traffic.
|
|
124
|
+
Source: [API thread limiting](https://www.autotask.net/help/developerhelp/content/apis/General/ThreadLimiting.htm).
|
|
125
|
+
|
|
126
|
+
The separate shared hourly guard is always on: each normalized request origin
|
|
127
|
+
has a 10,000-attempt trailing-hour ceiling across all SDK clients and tracking
|
|
128
|
+
identifiers in the same JavaScript realm, including ESM/CJS loads. Actual sends
|
|
129
|
+
of every verb, retries and failed attempts count. Cache hits, zero-wire dry runs
|
|
130
|
+
and pre-send refusals do not; actual reads used to build a dry-run diff still count. Both this ceiling and any lower per-client quota are
|
|
131
|
+
checked atomically immediately before fetch. A quota wait releases local and
|
|
132
|
+
object-thread permits, observes the original deadline/cancellation and reacquires
|
|
133
|
+
admission before sending. The guard retains hourly history across client churn;
|
|
134
|
+
expired histories are pruned lazily, without timers or disk state.
|
|
135
|
+
|
|
136
|
+
`rateLimit.perHour` remains the optional per-client quota. **`null` disables only
|
|
137
|
+
that local quota**, including under the agent profile; it cannot disable the
|
|
138
|
+
shared ceiling. `client.hourlyBudget()` still reports only the optional local
|
|
139
|
+
quota and remains `undefined` when it is disabled. A shared refusal uses the typed
|
|
140
|
+
`RATE_LIMITED` error with `details.budgetScope: 'process_origin'`; a local quota
|
|
141
|
+
refusal has scope `'client'`. `notSent` is true only when the whole call made no
|
|
142
|
+
wire attempt. Neither the shared error nor its guidance suggests raising the
|
|
143
|
+
hard ceiling. Origins are a conservative grouping: unrelated databases on one
|
|
144
|
+
origin share this allowance, and the SDK cannot observe another process,
|
|
145
|
+
worker realm, origin for the same database, or external integration.
|
|
146
|
+
|
|
147
|
+
The optional unauthenticated zone-discovery request also consumes the shared
|
|
148
|
+
quota of its service origin. If that quota is exhausted, discovery remains best
|
|
149
|
+
effort and returns no result without sending or waiting; no extra probe is added.
|
|
150
|
+
`ThresholdInformation` bypasses the cooldown gate only: it consumes and obeys
|
|
151
|
+
local/shared hourly admission and applicable object-thread admission. Read it
|
|
152
|
+
while headroom remains; neither informational endpoint bypasses the hourly guard.
|
|
153
|
+
|
|
96
154
|
Per-tenant 429 cooldown gate (`cooldown`, ON by default): once a 429 surfaces from the transport (retries spent, a `Retry-After` too long to wait out, or a non-retriable method), the client records a cooldown deadline for that tenant (lowercased `UserName` + lowercased host — impersonation does not change the key), and every further call for that tenant fails LOCALLY — before the semaphore, the hourly limiter and fetch, with zero upstream calls — with a `RateLimitError` (`code: 'RATE_LIMITED_COOLDOWN'`, `notSent: true`, `retryAfter` = remaining seconds; no credentials appear in the message) until the deadline passes. Duration is `Retry-After` clamped to `cooldown.maxMs` (default 15 minutes), or `cooldown.defaultMs` (default 60 s) when the header is missing or unparseable; the thread-threshold 429 (vendor code `Itgenatr005`, which clears in seconds) arms only a short window: min(`Retry-After`, 10 s), default 5 s. A 2xx from a call that got through clears the gate early; expiry is lazy (the first call after the deadline deletes the entry and proceeds); a hostile `Retry-After` (huge, zero, negative, non-numeric) is clamped to the cap or falls back to the default, so a lock-out is always bounded. `thresholdInformation.get()` bypasses the gate so a throttled tenant can still read its own headroom (a 2xx from it clears the gate; a 429 re-arms it). The state is one in-process map shared by every client instance (expired entries are swept when a new cooldown is armed); `cooldown: { enabled: false }` disables the gate. Gated calls emit an audit event marked `notSent` and do not count toward `rateLimit.perHour`. Limits worth knowing: the gate is per process — other processes and integrations on the same tenant are invisible to it (`thresholdInformation` is the only cross-integration signal); it can mask early recovery if the vendor window clears before `Retry-After`; a process that loads both the ESM and the CJS build gets two maps (deliberately not anchored on `globalThis`).
|
|
97
155
|
|
|
98
156
|
Credential-shaped fields are redacted in audit payloads by default.
|
|
@@ -507,10 +565,10 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
|
|
|
507
565
|
| `maxRetries` | 3 | — | the client's retry budget, overridable per call (`InvokeOptions.maxRetries` / `MutationOpts.maxRetries`; `0` = exactly one send per request the call performs). The budget caps three legs (issues #105/#109): the 429 leg (retried on GET/PUT/DELETE + flagged calls — unchanged) and the 5xx/network + non-JSON 2xx legs (GET + flagged only) |
|
|
508
566
|
| `maintenanceMaxWaitMs` | 3 600 000 (1 h) | — | **maintenance-window auto-retry** (weekly Autotask window): when the first 256 bytes of a non-JSON body read as a maintenance notice, the transport waits `maintenancePollMs` and retries for up to this long from the FIRST such page. A `2xx` page is waited out for reads AND writes (edge-served before execution); a `4xx`/`5xx` page only for calls safe to re-send (GET / explicitly idempotent-flagged) — an unflagged mutation makes ONE send and carries `details.maintenanceDetected` (a proxy can serve the page after forwarding). JSON bodies never enter. Does not consume `maxRetries`; each post-wait attempt gets a fresh `timeoutMs`. `0` disables the wait. A non-matching HTML-ish page stamps `details.maintenancePatternMiss`. Observed ceiling 4 h: `MAINTENANCE_WINDOW_MAX_MS` (19 windows: 30–240 min, median ≈ 2 h) |
|
|
509
567
|
| `maintenancePollMs` | 30 000 | — | poll interval while waiting out a maintenance page, and the maintenance gate's probe interval (section 3.2.2) |
|
|
510
|
-
| `maxConcurrent` | 10 |
|
|
568
|
+
| `maxConcurrent` | 10 | — | positive integer; per-client aggregate bound across objects; the separate shared gate caps each object/tracking-identifier group at 3 |
|
|
511
569
|
| `profile` | `library` | — | `library` = today's defaults (changes nothing); `agent` = the conservative `AGENT_PROFILE` limits for LLM-driven workloads (below). Resolution: explicit config > profile > library default |
|
|
512
570
|
| `maxResponseBytes` | 67 108 864 (64 MiB) | — | largest response body read; above it the call throws `RESPONSE_TOO_LARGE` (non-retryable) |
|
|
513
|
-
| `rateLimit.perHour` | off | 10 000 (vendor) | opt-in client-side hourly limiter (sliding window; waits within the call deadline, else `RateLimitError`). `null` is the explicit "disabled" value (beats the profile). The
|
|
571
|
+
| `rateLimit.perHour` | off | 10 000 (vendor) | opt-in client-side hourly limiter (sliding window; waits within the call deadline, else `RateLimitError`). `null` is the explicit "disabled" value (beats the profile). The optional quota is **per client** — it cannot see other instances or integrations on the tenant; the fixed shared origin ceiling also applies (`thresholdInformation.get()` is the tenant-wide readout; `client.hourlyBudget()` is the local one) |
|
|
514
572
|
| `cooldown` | on | 15 min (`cooldown.maxMs`) | per-tenant 429 cooldown gate (issue #6) — after a surfaced 429, further calls for that tenant (lowercased username + host) fail locally (`RATE_LIMITED_COOLDOWN`, `notSent: true`) until the deadline; `enabled: false` disables; `defaultMs` is the missing-`Retry-After` window (60 s) |
|
|
515
573
|
| `resolution.maxScanRecords` | 500 | — | bounded client-scan cap (section 7, `resolve`) |
|
|
516
574
|
| `resolution.maxScanPages` | 4 | — | bounded client-scan cap |
|
|
@@ -528,11 +586,11 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
|
|
|
528
586
|
`profile: 'agent'` switches the
|
|
529
587
|
resolvable limits to conservative values for LLM-driven workloads — a looping
|
|
530
588
|
agent can use up the tenant's ~10,000 req/hour vendor budget (shared across
|
|
531
|
-
every integration),
|
|
589
|
+
every integration), create excess concurrent load, and every retry spends
|
|
532
590
|
budget because the limiter counts each attempt. The values (to be tuned
|
|
533
|
-
against real traffic): `rateLimit.perHour` **8,000** (80% of the vendor
|
|
534
|
-
|
|
535
|
-
agent-mode CAP of **100** (an explicit `pageSize` above the cap is clamped,
|
|
591
|
+
against real traffic): `rateLimit.perHour` **8,000** (80% of the vendor allowance;
|
|
592
|
+
this local setting cannot reserve headroom for other integrations), `pageSize`
|
|
593
|
+
**25** with an agent-mode CAP of **100** (an explicit `pageSize` above the cap is clamped,
|
|
536
594
|
not rejected; library mode is uncapped at the vendor max), `timeoutMs`
|
|
537
595
|
**20,000**, `maxRetries` **1**, `maxConcurrent` **3**, `maxResponseBytes`
|
|
538
596
|
**4 MiB**, `resolution` **200 records / 2 pages**. Resolution order:
|
|
@@ -541,14 +599,14 @@ runs on the final values. `profile: 'library'` (the default, and absent)
|
|
|
541
599
|
resolves exactly as before — the library defaults are unchanged.
|
|
542
600
|
`rateLimit: { perHour: null }` is the explicit "disabled" value: an ABSENT
|
|
543
601
|
`perHour` means "use the profile/default" (the agent profile's 8,000), while
|
|
544
|
-
`null` turns the
|
|
602
|
+
`null` turns the local quota off even under the agent profile; the shared origin ceiling remains on. When the LOCAL
|
|
545
603
|
budget is exhausted the call fails fast with `RateLimitError`
|
|
546
604
|
(`retryAfter` = the blocked window in seconds); under the agent profile the
|
|
547
605
|
`suggestedAction` tells the caller to STOP or narrow the query — never to
|
|
548
606
|
raise the limit (raising it just burns more of the tenant's shared vendor
|
|
549
607
|
budget). The remaining budget is readable in-process: `client.hourlyBudget()`
|
|
550
608
|
returns `{ perHour, used, remaining }` for the LOCAL sliding window
|
|
551
|
-
(`undefined` when the
|
|
609
|
+
(`undefined` when the local quota is off); the tenant-wide count is
|
|
552
610
|
`thresholdInformation.get()`.
|
|
553
611
|
|
|
554
612
|
#### 3.2.1b Credential shape at construction (the 2026-10-07 incident class)
|
|
@@ -954,14 +1012,25 @@ read). Through the governed path pass `invokeRead(client, 'companies.get',
|
|
|
954
1012
|
refuses pre-request (zero wire). It affects the one read only: it never clears
|
|
955
1013
|
other entries (unlike `http.readCache.clear()`).
|
|
956
1014
|
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
1015
|
+
Concurrent ordinary record reads for the same path share a cold request,
|
|
1016
|
+
including equivalent global, parent-scoped and context reads. Each caller
|
|
1017
|
+
receives its own copy. With `cache: false`, reads remain independent requests.
|
|
1018
|
+
Every `fresh` call starts a new request, never joins an older flight and
|
|
1019
|
+
supersedes that flight's pending cache write. A subscriber's cancellation
|
|
1020
|
+
rejects only its own call; the shared request is cancelled when no subscriber
|
|
1021
|
+
remains. Pre-aborted callers neither start a read nor consume a warm entry.
|
|
1022
|
+
If a shared leader refuses solely because its private client quota is exhausted
|
|
1023
|
+
before any send, an eligible joiner checks the warm cache and tries its own loader
|
|
1024
|
+
once under its own quota. Vendor failures, the shared origin ceiling and failures
|
|
1025
|
+
after an actual send remain shared; this exception adds no vendor-429 retry loop.
|
|
1026
|
+
|
|
1027
|
+
Stale-response safety: a read in flight across a write
|
|
960
1028
|
through the same cache (including the pool's shared per-tenant cache, whose
|
|
961
1029
|
epoch the write bumps) has its late store discarded, so a pre-write response is
|
|
962
1030
|
never re-cached; the in-flight caller itself still receives the response it
|
|
963
|
-
asked for.
|
|
964
|
-
|
|
1031
|
+
asked for. Explicit cache invalidation likewise detaches pending loads so
|
|
1032
|
+
their answers cannot restore invalidated entries. Not covered: a write on a
|
|
1033
|
+
client whose cache is private (pool `sharedReadCache: false`) is invisible to
|
|
965
1034
|
the other client's cache — use `fresh` there.
|
|
966
1035
|
|
|
967
1036
|
## 7. Operations surface (`./operations` subpath)
|
package/docs/LIVE-TESTING.md
CHANGED
|
@@ -10,6 +10,20 @@ prefix per value (shorter values print neither).
|
|
|
10
10
|
The scripts FAIL CLOSED without credentials (exit 2) — a green exit is never
|
|
11
11
|
a false pass.
|
|
12
12
|
|
|
13
|
+
Performance probes use an aggregate concurrency cap of **2**, including work
|
|
14
|
+
started by helpers, to leave room under the vendor's per-object limit and avoid
|
|
15
|
+
intentionally entering its latency tier at 3 concurrent requests. Keep live work
|
|
16
|
+
bounded and coordinate other users of the tracking identifier; neither this
|
|
17
|
+
setting nor the SDK's shared per-object gate can account for other processes or
|
|
18
|
+
external integrations. The separate hourly threshold is database-wide across all
|
|
19
|
+
integrations; a planned probe budget does not establish available headroom.
|
|
20
|
+
Check `ThresholdInformation` headroom before bounded performance probes without
|
|
21
|
+
logging its returned usage totals. That read is itself counted and obeys both
|
|
22
|
+
hourly admission and its object-thread admission; only cooldown is bypassed.
|
|
23
|
+
The fixed SDK origin-wide hourly guard remains on even when a local quota is disabled.
|
|
24
|
+
See [API thread limiting](https://www.autotask.net/help/developerhelp/content/apis/General/ThreadLimiting.htm)
|
|
25
|
+
and [REST thresholds](https://www.autotask.net/help/developerhelp/content/apis/REST/General_Topics/REST_Thresholds_Limits.htm).
|
|
26
|
+
|
|
13
27
|
## 0. Preconditions
|
|
14
28
|
|
|
15
29
|
- Node >= 24 (the floor covers the MCP examples' >= 20 need). This machine: v24.18.0.
|
|
@@ -150,8 +164,8 @@ the cache) = the plan-honest total. WIRE-HONEST: the dry-run verification
|
|
|
150
164
|
reads ride on top — delete current-record GETs + scoped-create parent-verify
|
|
151
165
|
GETs + getContext part GETs + special-op reads — giving the wire-honest worst
|
|
152
166
|
case. The 1600 --max-calls cap bounds the row-based plan; the wire count
|
|
153
|
-
cannot exceed plan + the stated verification set
|
|
154
|
-
|
|
167
|
+
cannot exceed plan + the stated verification set. That bound does not include
|
|
168
|
+
other traffic against the database's shared hourly threshold. ZERO mutating requests: every mutation travels
|
|
155
169
|
`dryRun: true` (the sweep flag + the SDK governor's dry-run-first default,
|
|
156
170
|
double-locked; pinned per-resource in the generated test suite), and EVERY
|
|
157
171
|
destructive/approval-gated row — the delete dry-runs included — routes through `operations.invoke` with `confirm === <op key>`:
|
package/docs/VENDOR-QUIRKS.md
CHANGED
|
@@ -2061,3 +2061,42 @@ name reads per call, so a plain read returns raw ids), through the same
|
|
|
2061
2061
|
- Headroom on the verified tenant: active definitions at roughly 40% of the 200-active cap; list items of the same order as the definition count. Every UDF read cost one vendor call, ~0.4–1.0 s at the MCP layer.
|
|
2062
2062
|
- Write-path URLs registry-verified, zero wire: `POST /V1.0/UserDefinedFieldDefinitions`, `PUT|PATCH /V1.0/UserDefinedFieldDefinitions`, `POST|PUT|PATCH /V1.0/UserDefinedFields/{parentId}/ListItems`. Dry-run create/update previews under the operator governance returned an allow decision plus a plan, the no-DELETE warning and the account-wide hazard, with zero vendor writes. The live write round-trip ran the same day after owner go-ahead: the test definition + item were created (the parent-scoped create and update proven live on `UserDefinedFields/{parentId}/ListItems`), the item's label was updated and read back, and both were then deactivated and left in place — anything created is permanent (no DELETE); the active-definition count was unchanged after deactivation.
|
|
2063
2063
|
- Live-proven create field sets (issue #437; `operations.createGuidance` serves them as `liveProvenPrefix`, kind `ok`): `UserDefinedFieldDefinitions` POST accepted `name`, `udfType`, `dataType` (a List-type definition); `UserDefinedFields/{parentId}/ListItems` POST accepted `valueForDisplay`, `valueForExport`, with `udfFieldId` supplied by the path, not the body. Both answered an item id and read back with the posted values. The definition request also carried `valueForDisplay` / `valueForExport`, which are not definition-model properties: the create still succeeded and the returned record has no such keys (consistent with the unknown-field no-op of §11.3), so they are not part of the proven set.
|
|
2064
|
+
|
|
2065
|
+
|
|
2066
|
+
### 11.32 Object-scoped thread limits and the separate hourly budget (documentation checked 2026-11-17)
|
|
2067
|
+
|
|
2068
|
+
Primary sources: [API thread limiting](https://www.autotask.net/help/developerhelp/content/apis/General/ThreadLimiting.htm)
|
|
2069
|
+
and [REST supportability, query thresholds and latency](https://www.autotask.net/help/developerhelp/content/apis/REST/General_Topics/REST_Thresholds_Limits.htm).
|
|
2070
|
+
This entry records the published vendor contract, not a tenant-specific load test.
|
|
2071
|
+
|
|
2072
|
+
- Thread admission is scoped to a tracking identifier and object endpoint in an
|
|
2073
|
+
Autotask instance, across all HTTP methods. The documented limit for integrations
|
|
2074
|
+
developed after 2023.1 is 3. Integrations created before 2022.1 may retain higher
|
|
2075
|
+
limits that the vendor adjusts over time; the SDK conservatively caps both at 3
|
|
2076
|
+
and supplies no override to raise that ceiling. `ZoneInformation` is exempt.
|
|
2077
|
+
- Thread latency begins at 3 simultaneous requests to an object. The live
|
|
2078
|
+
performance harness caps aggregate concurrency at 2; it does not deliberately
|
|
2079
|
+
load an endpoint to discover a higher limit.
|
|
2080
|
+
- SDK clients sharing a normalized origin and hashed tracking identifier share
|
|
2081
|
+
the per-object gate across API users, secret rotation and impersonation. Query,
|
|
2082
|
+
count, metadata, cursors and equivalent global/scoped routes consume the same
|
|
2083
|
+
canonical object's permits, held through response-body consumption. The library
|
|
2084
|
+
default `maxConcurrent: 10` is only a client's aggregate bound across objects,
|
|
2085
|
+
never an allowance to run 10 requests against one object.
|
|
2086
|
+
- The 10,000-calls/hour threshold is separate and covers all integrations against
|
|
2087
|
+
the database. In-process SDK gates cannot coordinate external integrations,
|
|
2088
|
+
other processes, worker realms or other origins for the same
|
|
2089
|
+
database. Lower configured concurrency and coordinate budgets when sharing;
|
|
2090
|
+
these gates provide no guarantee about unknown external traffic.
|
|
2091
|
+
|
|
2092
|
+
The SDK also applies a fixed 10,000-attempt trailing-hour guard per normalized
|
|
2093
|
+
origin, shared across clients and tracking identifiers within one JavaScript
|
|
2094
|
+
realm. It supplements the optional per-client quota; explicit `perHour: null`
|
|
2095
|
+
disables only that local quota. The guard counts actual sends and retries,
|
|
2096
|
+
including failed and informational requests; queued cancellations and local
|
|
2097
|
+
refusals consume no slot. Lower quotas and the shared guard admit atomically,
|
|
2098
|
+
without holding thread permits during hourly waits. Unrelated databases on one
|
|
2099
|
+
origin conservatively share an allowance, so this is a protective approximation,
|
|
2100
|
+
not a measurement of vendor-wide remaining headroom. `ThresholdInformation`
|
|
2101
|
+
bypasses cooldown only and remains counted; best-effort zone discovery skips
|
|
2102
|
+
its existing request when the service origin has no shared hourly capacity.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Finance read scheduling
|
|
2
|
+
|
|
3
|
+
Financial reports use the same internal bounded read executor as client batches and resource composites.
|
|
4
|
+
The HTTP client retains the wire concurrency and rate limits; report budgets charge synchronously before
|
|
5
|
+
request admission. Results and folds retain input order regardless of response order. No server cache or
|
|
6
|
+
new report response cache is involved.
|
|
7
|
+
|
|
8
|
+
`contracts.profitability` reads its contract root before scheduling other stages. Contract state, billing,
|
|
9
|
+
time, open tickets and configuration-item subscriptions are independent branches. Ticket activity and
|
|
10
|
+
resource costs reuse the time promise; expenses and the miscoding probe wait for ticket activity and open
|
|
11
|
+
tickets. Each branch owns its request counters, window truncation facts and notes until an ordered merge.
|
|
12
|
+
The expense join receives time truncation facts before it runs. With one worker, the original depth-first
|
|
13
|
+
wire plan is retained; multiple workers admit independent roots before dependency waiters.
|
|
14
|
+
|
|
15
|
+
`revenueRollup` overlaps independent field catalogs and sizing counts. Its estimate still passes before
|
|
16
|
+
streams start, and each invoice chunk retains its exact count-to-stream integrity gate. Contract, company
|
|
17
|
+
and organizational association joins overlap; organizational level lookups wait for associations.
|
|
18
|
+
|
|
19
|
+
`recurringRevenue` overlaps the contract and subscription sizing counts, then the independent service-unit
|
|
20
|
+
and charge counts. Its floor and full estimate still pass before the corresponding streams. Sized units,
|
|
21
|
+
charges and subscriptions overlap; subscription catalogs and configuration-item joins overlap after the
|
|
22
|
+
subscription IDs are known. Report folds and source separation remain unchanged.
|
|
23
|
+
|
|
24
|
+
`wipHours` and `nonChargeableWork` overlap contract record and contract-type catalog reads only after the
|
|
25
|
+
existing label budget gate. Their count, stream, posted-state and scope gates remain dependencies.
|
|
26
|
+
`arAging` retains its count → invoice stream → companies → currencies chain because each stage derives the
|
|
27
|
+
next stage's IDs. `portfolioMargin` retains selector validation before scope sizing, shared expense sizing
|
|
28
|
+
before contract fan-out, and its fatal budget/rate-limit latch. A latched fatal error cancels queued HTTP
|
|
29
|
+
requests and the operation drains started work before reporting the original error.
|
|
30
|
+
|
|
31
|
+
The finance concurrency tests use deferred barriers and routed mock vendor responses to prove overlap,
|
|
32
|
+
count gates, draining, stable outputs and unchanged wire counts. The older FIFO profitability fixtures run
|
|
33
|
+
with one worker; routed tests exercise parallel scheduling independently of response order. Synthetic
|
|
34
|
+
latency measurements compare worker settings with an injected per-request delay; they are scheduling
|
|
35
|
+
measurements, not production Autotask latency claims.
|
|
@@ -0,0 +1,63 @@
|
|
|
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 projection caching remains a separate evaluation in #459.
|
|
44
|
+
|
|
45
|
+
## Measurement scope
|
|
46
|
+
|
|
47
|
+
Deferred tests prove overlap, ordering, draining, limits and output equality. Synthetic
|
|
48
|
+
routed-vendor comparisons use fixed latency and compare serial/parallel execution:
|
|
49
|
+
exact resolution and uncapped search overlap their independent resources; bulk reads
|
|
50
|
+
retain the query/fallback dependency. Cold/warm wire counts remain equal between
|
|
51
|
+
scheduling modes. These measurements demonstrate scheduling gains, not production
|
|
52
|
+
latency guarantees.
|
|
53
|
+
|
|
54
|
+
An offline admission backlog comparison reduced the time to grant and release 20,000
|
|
55
|
+
leases from about 79 seconds to 0.36 seconds after indexed scheduling. Work-count
|
|
56
|
+
regressions cover shared-object, shared-client and mixed backlogs without relying on
|
|
57
|
+
wall-clock thresholds. No vendor request is made by this benchmark.
|
|
58
|
+
|
|
59
|
+
A synthetic repeated field-authority workload reduced median CPU time from about
|
|
60
|
+
23 ms to 8 ms per 5,000 checks after static indexing, with identical results. Required
|
|
61
|
+
result cloning and live metadata authority remain intact. Real API validation uses
|
|
62
|
+
read-only bounded probes with separate timings and call counts; it does not increase
|
|
63
|
+
vendor limits to obtain overlap.
|
|
@@ -75,17 +75,16 @@ export function readEnvOverrides(env: Env = process.env): Partial<AutotaskConfig
|
|
|
75
75
|
if (perHourRaw !== undefined) {
|
|
76
76
|
const trimmed = perHourRaw.trim();
|
|
77
77
|
if (trimmed === 'off') {
|
|
78
|
-
// Explicit disable (issue #4)
|
|
79
|
-
// budget is now unprotected by this process; say so on stderr.
|
|
78
|
+
// Explicit local-quota disable (issue #4); the shared origin ceiling remains on.
|
|
80
79
|
console.error(
|
|
81
|
-
`${ENV_RATE_LIMIT_PER_HOUR}=off — the client
|
|
80
|
+
`${ENV_RATE_LIMIT_PER_HOUR}=off — the per-client hourly quota is DISABLED; the shared origin ceiling remains enabled and cannot account for external traffic`,
|
|
82
81
|
);
|
|
83
82
|
out.rateLimit = { perHour: null };
|
|
84
83
|
} else {
|
|
85
84
|
const n = parseStrictInt(perHourRaw, ENV_RATE_LIMIT_PER_HOUR);
|
|
86
85
|
if (n === 0) {
|
|
87
86
|
console.error(
|
|
88
|
-
`${ENV_RATE_LIMIT_PER_HOUR}=0 — the client
|
|
87
|
+
`${ENV_RATE_LIMIT_PER_HOUR}=0 — the per-client hourly quota is DISABLED; the shared origin ceiling remains enabled and cannot account for external traffic`,
|
|
89
88
|
);
|
|
90
89
|
out.rateLimit = { perHour: null };
|
|
91
90
|
} else if (n === undefined || n < 1) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "node-autotask",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.69.1",
|
|
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,
|