node-autotask 0.68.1 → 0.69.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.
Files changed (37) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/MCP_TOOL_CATALOG.json +2 -2
  3. package/README.md +51 -10
  4. package/capabilities.json +7 -7
  5. package/dist/capabilities-data.js +6 -6
  6. package/dist/capabilities.cjs +4 -4
  7. package/dist/capabilities.js +1 -1
  8. package/dist/{chunk-2D2KJOX2.cjs → chunk-24GRFW55.cjs} +236 -222
  9. package/dist/{chunk-LOLWHPTJ.js → chunk-2BB7OASJ.js} +3 -30
  10. package/dist/{chunk-S6HEIGGM.js → chunk-AH6WAGPS.js} +80 -66
  11. package/dist/{chunk-KRQONGLD.cjs → chunk-DPRY3CUJ.cjs} +30 -57
  12. package/dist/{chunk-XKIRTR37.cjs → chunk-JLBSUZ5B.cjs} +919 -344
  13. package/dist/{chunk-SGH7F2CH.cjs → chunk-KAZE4WC7.cjs} +3 -3
  14. package/dist/{chunk-YYHCZRUH.js → chunk-QDBJCGQD.js} +912 -339
  15. package/dist/{chunk-JCMXQUIC.js → chunk-SCFB5MF3.js} +3 -3
  16. package/dist/{index-DQ08uOH0.d.ts → index-CxBU31jT.d.ts} +16 -9
  17. package/dist/{index-mIsdpO5d.d.cts → index-WZ3A8nG6.d.cts} +16 -9
  18. package/dist/index.cjs +92 -85
  19. package/dist/index.d.cts +3 -3
  20. package/dist/index.d.ts +3 -3
  21. package/dist/index.js +14 -7
  22. package/dist/operations/index.cjs +50 -50
  23. package/dist/operations/index.d.cts +2 -2
  24. package/dist/operations/index.d.ts +2 -2
  25. package/dist/operations/index.js +2 -2
  26. package/dist/pool.cjs +12 -12
  27. package/dist/pool.js +4 -4
  28. package/dist/resources/index.cjs +27 -27
  29. package/dist/resources/index.d.cts +1 -1
  30. package/dist/resources/index.d.ts +1 -1
  31. package/dist/resources/index.js +3 -3
  32. package/docs/API.md +77 -16
  33. package/docs/LIVE-TESTING.md +16 -2
  34. package/docs/VENDOR-QUIRKS.md +39 -0
  35. package/docs/performance-finance.md +35 -0
  36. package/examples/mcp-env-config.ts +3 -4
  37. package/package.json +1 -1
package/docs/API.md CHANGED
@@ -88,11 +88,61 @@ 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 (`maxConcurrent`, default 10 — the API
92
- allows <= 10 concurrent), one correlation id per request (surfaced on every
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 API allows 10,000 req/hour). The tracker is PER PROCESS: 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
+ (`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
+ Vendor thread limits are scoped to the object and tracking identifier within an
108
+ Autotask instance; integrations developed after the 2023.1 release have a limit
109
+ of 3, while integrations from before 2022.1 can retain higher measured limits.
110
+ The documented thread-latency tier starts at 3 concurrent requests to an object.
111
+ Use lower configured concurrency and coordinate shared-identifier traffic when
112
+ leaving room or avoiding that tier matters. The live performance harness uses an
113
+ aggregate cap of 2. The SDK's in-process coordination cannot account for external
114
+ integrations, other processes, worker realms or different origins
115
+ serving the same database. It does not guarantee safety against that traffic.
116
+ Source: [API thread limiting](https://www.autotask.net/help/developerhelp/content/apis/General/ThreadLimiting.htm).
117
+
118
+ The separate shared hourly guard is always on: each normalized request origin
119
+ has a 10,000-attempt trailing-hour ceiling across all SDK clients and tracking
120
+ identifiers in the same JavaScript realm, including ESM/CJS loads. Actual sends
121
+ of every verb, retries and failed attempts count. Cache hits, zero-wire dry runs
122
+ 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
123
+ checked atomically immediately before fetch. A quota wait releases local and
124
+ object-thread permits, observes the original deadline/cancellation and reacquires
125
+ admission before sending. The guard retains hourly history across client churn;
126
+ expired histories are pruned lazily, without timers or disk state.
127
+
128
+ `rateLimit.perHour` remains the optional per-client quota. **`null` disables only
129
+ that local quota**, including under the agent profile; it cannot disable the
130
+ shared ceiling. `client.hourlyBudget()` still reports only the optional local
131
+ quota and remains `undefined` when it is disabled. A shared refusal uses the typed
132
+ `RATE_LIMITED` error with `details.budgetScope: 'process_origin'`; a local quota
133
+ refusal has scope `'client'`. `notSent` is true only when the whole call made no
134
+ wire attempt. Neither the shared error nor its guidance suggests raising the
135
+ hard ceiling. Origins are a conservative grouping: unrelated databases on one
136
+ origin share this allowance, and the SDK cannot observe another process,
137
+ worker realm, origin for the same database, or external integration.
138
+
139
+ The optional unauthenticated zone-discovery request also consumes the shared
140
+ quota of its service origin. If that quota is exhausted, discovery remains best
141
+ effort and returns no result without sending or waiting; no extra probe is added.
142
+ `ThresholdInformation` bypasses the cooldown gate only: it consumes and obeys
143
+ local/shared hourly admission and applicable object-thread admission. Read it
144
+ while headroom remains; neither informational endpoint bypasses the hourly guard.
145
+
96
146
  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
147
 
98
148
  Credential-shaped fields are redacted in audit payloads by default.
@@ -507,10 +557,10 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
507
557
  | `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
558
  | `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
559
  | `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 | 10 (vendor) | concurrency guard |
560
+ | `maxConcurrent` | 10 | — | positive integer; per-client aggregate bound across objects; the separate shared gate caps each object/tracking-identifier group at 3 |
511
561
  | `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
562
  | `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 limiter is **per process** — it cannot see other instances or integrations on the tenant (`thresholdInformation.get()` is the tenant-wide readout; `client.hourlyBudget()` is the local one) |
563
+ | `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
564
  | `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
565
  | `resolution.maxScanRecords` | 500 | — | bounded client-scan cap (section 7, `resolve`) |
516
566
  | `resolution.maxScanPages` | 4 | — | bounded client-scan cap |
@@ -528,11 +578,11 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
528
578
  `profile: 'agent'` switches the
529
579
  resolvable limits to conservative values for LLM-driven workloads — a looping
530
580
  agent can use up the tenant's ~10,000 req/hour vendor budget (shared across
531
- every integration), hold all 10 concurrent threads, and every retry spends
581
+ every integration), create excess concurrent load, and every retry spends
532
582
  budget because the limiter counts each attempt. The values (to be tuned
533
- against real traffic): `rateLimit.perHour` **8,000** (80% of the vendor cap —
534
- 2,000/hr left for the tenant's other integrations), `pageSize` **25** with an
535
- agent-mode CAP of **100** (an explicit `pageSize` above the cap is clamped,
583
+ against real traffic): `rateLimit.perHour` **8,000** (80% of the vendor allowance;
584
+ this local setting cannot reserve headroom for other integrations), `pageSize`
585
+ **25** with an agent-mode CAP of **100** (an explicit `pageSize` above the cap is clamped,
536
586
  not rejected; library mode is uncapped at the vendor max), `timeoutMs`
537
587
  **20,000**, `maxRetries` **1**, `maxConcurrent` **3**, `maxResponseBytes`
538
588
  **4 MiB**, `resolution` **200 records / 2 pages**. Resolution order:
@@ -541,14 +591,14 @@ runs on the final values. `profile: 'library'` (the default, and absent)
541
591
  resolves exactly as before — the library defaults are unchanged.
542
592
  `rateLimit: { perHour: null }` is the explicit "disabled" value: an ABSENT
543
593
  `perHour` means "use the profile/default" (the agent profile's 8,000), while
544
- `null` turns the limiter off even under the agent profile. When the LOCAL
594
+ `null` turns the local quota off even under the agent profile; the shared origin ceiling remains on. When the LOCAL
545
595
  budget is exhausted the call fails fast with `RateLimitError`
546
596
  (`retryAfter` = the blocked window in seconds); under the agent profile the
547
597
  `suggestedAction` tells the caller to STOP or narrow the query — never to
548
598
  raise the limit (raising it just burns more of the tenant's shared vendor
549
599
  budget). The remaining budget is readable in-process: `client.hourlyBudget()`
550
600
  returns `{ perHour, used, remaining }` for the LOCAL sliding window
551
- (`undefined` when the limiter is off); the tenant-wide count is
601
+ (`undefined` when the local quota is off); the tenant-wide count is
552
602
  `thresholdInformation.get()`.
553
603
 
554
604
  #### 3.2.1b Credential shape at construction (the 2026-10-07 incident class)
@@ -954,14 +1004,25 @@ read). Through the governed path pass `invokeRead(client, 'companies.get',
954
1004
  refuses pre-request (zero wire). It affects the one read only: it never clears
955
1005
  other entries (unlike `http.readCache.clear()`).
956
1006
 
957
- Stale-response safety: the read cache does not coalesce concurrent reads (every
958
- miss and every `fresh` call issues its own request), so a `fresh` read never
959
- joins a read that started before a write. A read in flight across a write
1007
+ Concurrent ordinary record reads for the same path share a cold request,
1008
+ including equivalent global, parent-scoped and context reads. Each caller
1009
+ receives its own copy. With `cache: false`, reads remain independent requests.
1010
+ Every `fresh` call starts a new request, never joins an older flight and
1011
+ supersedes that flight's pending cache write. A subscriber's cancellation
1012
+ rejects only its own call; the shared request is cancelled when no subscriber
1013
+ remains. Pre-aborted callers neither start a read nor consume a warm entry.
1014
+ If a shared leader refuses solely because its private client quota is exhausted
1015
+ before any send, an eligible joiner checks the warm cache and tries its own loader
1016
+ once under its own quota. Vendor failures, the shared origin ceiling and failures
1017
+ after an actual send remain shared; this exception adds no vendor-429 retry loop.
1018
+
1019
+ Stale-response safety: a read in flight across a write
960
1020
  through the same cache (including the pool's shared per-tenant cache, whose
961
1021
  epoch the write bumps) has its late store discarded, so a pre-write response is
962
1022
  never re-cached; the in-flight caller itself still receives the response it
963
- asked for. Not covered: a write on a client whose cache is private (pool
964
- `sharedReadCache: false`) is invisible to
1023
+ asked for. Explicit cache invalidation likewise detaches pending loads so
1024
+ their answers cannot restore invalidated entries. Not covered: a write on a
1025
+ client whose cache is private (pool `sharedReadCache: false`) is invisible to
965
1026
  the other client's cache — use `fresh` there.
966
1027
 
967
1028
  ## 7. Operations surface (`./operations` subpath)
@@ -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 (both stay far under the
154
- API's 10k req/hour). ZERO mutating requests: every mutation travels
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>`:
@@ -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.
@@ -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) — the tenant's 10,000 req/hour vendor
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-side hourly limiter is DISABLED for this process (the tenant's 10,000 req/hour vendor budget is now unprotected by it)`,
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-side hourly limiter is DISABLED for this process (the tenant's 10,000 req/hour vendor budget is now unprotected by it)`,
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.68.1",
3
+ "version": "0.69.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,