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.
Files changed (38) hide show
  1. package/CHANGELOG.md +26 -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-LOLWHPTJ.js → chunk-64BMSXWT.js} +3 -30
  9. package/dist/{chunk-XKIRTR37.cjs → chunk-CLHDTYWO.cjs} +1405 -488
  10. package/dist/{chunk-2D2KJOX2.cjs → chunk-EWXRFHPP.cjs} +236 -222
  11. package/dist/{chunk-YYHCZRUH.js → chunk-FK37JXSJ.js} +1398 -483
  12. package/dist/{chunk-SGH7F2CH.cjs → chunk-KAZE4WC7.cjs} +3 -3
  13. package/dist/{chunk-S6HEIGGM.js → chunk-MMGO3SFL.js} +80 -66
  14. package/dist/{chunk-JCMXQUIC.js → chunk-SCFB5MF3.js} +3 -3
  15. package/dist/{chunk-KRQONGLD.cjs → chunk-WFVLF7EW.cjs} +30 -57
  16. package/dist/{index-mIsdpO5d.d.cts → index-BT_0tTPS.d.cts} +19 -12
  17. package/dist/{index-DQ08uOH0.d.ts → index-Coe7LFLY.d.ts} +19 -12
  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 +85 -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/docs/performance-reads.md +63 -0
  37. package/examples/mcp-env-config.ts +3 -4
  38. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.69.1] - 2026-11-17
11
+
12
+ ### Changed
13
+
14
+ - Reuse bounded ordered reads for independent exact resolution, uncapped cross-resource search, field-catalog kinds/resources, bulk group queries and fallback GETs (#458). Preserve capped-search quotas, exact-to-contains barriers, count/chunk dependencies, input order, typed failures and draining.
15
+ - Overlap fully disjoint label groups, retaining serial traversal when any target is shared so warming budgets and fatal-error order stay intact. Reuse identical normalized relation-parent queries within one invocation and overlap flat OR branches; AND and nested short-circuit paths remain ordered (#458).
16
+ - Admit transport requests only when client and shared-object capacity are both available, so queued work holds neither slot. Index waiters and share cancellation notifications to avoid quadratic backlog scans. Keep the shared object ceiling, atomic hourly accounting and response-body leases, including live v1 semaphores from older SDK copies; existing legacy waiters retain priority (#458).
17
+ - Compile immutable vendored field-membership lookups once for validation, projections and labels. Live tenant metadata and current live-only exemptions remain authoritative; no query/report response cache is introduced (#458).
18
+
19
+ ### Fixed
20
+
21
+ - Share metadata GETs through the record cache's subscriber adapter: isolate cancellation, values and typed failures, prevent stale in-flight repopulation, preserve report failure observation and private-quota isolation, and retain only nonempty metadata. Ticket-status metadata uses the same channel and keeps its retry policy (#458).
22
+ - Reject non-model inherited property names as bulk resources before any vendor request (#458).
23
+
24
+ ## [0.69.0] - 2026-11-17
25
+
26
+ ### Breaking
27
+
28
+ - Vendor-protection admission is always enabled: matching SDK clients share a three-request ceiling per object and tracking identifier, and SDK traffic in the same JavaScript realm shares a conservative origin-wide ceiling of 10,000 attempts in a trailing hour (#457). `maxConcurrent` remains the local aggregate bound across objects; `rateLimit.perHour: null` disables only the optional local quota. Independent processes, workers, origins and external integrations require separate coordination.
29
+
30
+ ### Changed
31
+
32
+ - Refresh capability test-evidence references for the changed warm-reference and rate-limit scheduling behavior (#457). Operation signatures are unchanged; the evidence update changes the immutable capability-plan hash and requires a minor release.
33
+ - Coalesce equivalent non-fresh record GETs in the SDK read cache, with independent caller cancellation, cloned results and protection against stale in-flight responses after writes or fresh reads (#457). Fresh reads and `cache: false` retain their bypass behavior.
34
+ - Reuse the bounded worker executor for independent composite, name-enrichment and finance branches (#457). Name budgets are reserved before scheduling, results retain input order, failed work drains before returning, and count/preflight guards remain ahead of the walks they authorize.
35
+
10
36
  ## [0.68.1] - 2026-11-17
11
37
 
12
38
  ### Changed
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "generatedBy": "scripts/build-tool-catalog.mjs",
3
- "generatedAt": "2026-11-17T07:46:23.435Z",
4
- "planHash": "04fb614dcdd035a01636e51cf38d8178aeef7c9a1b45faf4af6187875800bd70",
3
+ "generatedAt": "2026-11-17T15:37:46.446Z",
4
+ "planHash": "959981d335cfd184d8b4e58074d1ab6997b2db87a62683ed13e99c149f8cd4fa",
5
5
  "metaTools": [
6
6
  {
7
7
  "name": "autotask_catalog",
package/README.md CHANGED
@@ -175,7 +175,7 @@ server-layer overrides unset rather than blank: an empty value is *invalid* for
175
175
  | `AUTOTASK_IMPERSONATION_ID` | doctor, examples | optional `ImpersonationResourceId` header |
176
176
  | `AUTOTASK_PROFILE` | reference MCP servers | `library` (default) / `agent` — the agent profile's numbers are compared in the template and in *Agent profile* above |
177
177
  | `AUTOTASK_RATE_LIMIT_PER_HOUR` | reference MCP servers | hourly limiter: a positive integer, or `0` / `off` to disable |
178
- | `AUTOTASK_MAX_CONCURRENT` | reference MCP servers | concurrency guard (vendor max 10) |
178
+ | `AUTOTASK_MAX_CONCURRENT` | reference MCP servers | local aggregate concurrency limit; the SDK separately enforces the shared per-object limit |
179
179
  | `AUTOTASK_TIMEOUT_MS` | reference MCP servers | whole-call timeout |
180
180
  | `AUTOTASK_MAX_RETRIES` | reference MCP servers | retry budget (`0` disables) |
181
181
  | `AUTOTASK_UNTRUSTED_WRAP` | MCP servers | `on` (default) / `off` — the `<untrusted_content>` projection |
@@ -187,34 +187,75 @@ The SDK itself never reads `process.env`: pass `apiIntegrationCode` / `userName`
187
187
  explicitly, or call `loadAutotaskCredentialsFromEnv()`.
188
188
 
189
189
 
190
+ ## Concurrency and vendor budgets
191
+
192
+ `maxConcurrent` is a local aggregate bound per client (library default **10**),
193
+ allowing different objects to progress in parallel. It is not a vendor thread allowance.
194
+ The SDK also enforces a shared ceiling of **3** active requests per object and
195
+ tracking identifier. This gate covers every HTTP verb, query/count and metadata
196
+ reads, and equivalent global/scoped routes. Clients sharing the same normalized
197
+ origin and tracking identifier share the gate across API users, secret rotation
198
+ and impersonation; the tracking identifier is hashed in its internal key.
199
+ ESM and CJS clients share this registry within one JavaScript realm.
200
+ `ZoneInformation` is exempt. There is no setting that raises this ceiling.
201
+
202
+ The vendor applies thread limits to an object and tracking identifier within an
203
+ Autotask instance. New integrations have a limit of 3; some legacy integrations
204
+ may have higher limits. The SDK conservatively uses 3 for both. The vendor also
205
+ adds thread latency starting at 3 simultaneous requests to an object. For
206
+ latency-sensitive work or shared tracking identifiers, lower configured concurrency
207
+ and coordinate traffic with the other callers. The live performance harness uses
208
+ an aggregate cap of 2 to leave room and avoid intentionally entering that latency tier.
209
+ See the official [API thread limits](https://www.autotask.net/help/developerhelp/content/apis/General/ThreadLimiting.htm).
210
+
211
+ The separate **10,000 calls/hour** threshold covers all integrations accessing the
212
+ same database. An always-on SDK guard conservatively caps actual sends to each
213
+ normalized origin at 10,000 over a trailing hour, shared across clients, users,
214
+ tracking identifiers and ESM/CJS loads in the same JavaScript realm. It counts
215
+ retries and failed attempts; cache hits and locally refused work consume no slot.
216
+ The optional `rateLimit.perHour` remains a lower per-client quota;
217
+ `rateLimit: { perHour: null }` disables only that local quota, never the shared
218
+ ceiling. Local `hourlyBudget()` snapshots still describe the per-client quota.
219
+
220
+ An origin can host unrelated databases, so those clients may queue together.
221
+ SDK gates cannot coordinate other processes, worker realms,
222
+ other origins serving the same database, or external integrations, and cannot
223
+ guarantee headroom against that traffic. Check
224
+ `client.thresholdInformation.get()` while headroom remains and coordinate
225
+ deployment-wide budgets. That read bypasses cooldown only; it still obeys and
226
+ consumes hourly admission and the applicable object-thread limit.
227
+ The [vendor threshold reference](https://www.autotask.net/help/developerhelp/content/apis/REST/General_Topics/REST_Thresholds_Limits.htm)
228
+ describes that database-wide limit.
229
+
190
230
  ## Agent profile (conservative limits for LLM-driven servers)
191
231
 
192
232
  `profile: 'agent'` on the config switches the SDK to conservative limits for
193
233
  workloads driven by an LLM: a looping agent can use up the tenant's ~10,000
194
- req/hour vendor budget (shared across every integration), hold all 10
195
- concurrent threads (starving the other integrations), and every retry spends
196
- budget, because the limiter counts each attempt. The profile values (plain data): `rateLimit.perHour` **8,000** (80% of the vendor cap — 2,000/hr
197
- stay available for the tenant's other integrations), page size **25** (capped
234
+ req/hour database budget (shared across every integration), create excess
235
+ concurrent load, and spend budget on every retry, because the limiter counts
236
+ each attempt. The profile values (plain data): `rateLimit.perHour` **8,000**
237
+ (80% of the vendor allowance; this local setting does not reserve headroom for
238
+ other integrations), page size **25** (capped
198
239
  at **100** in agent mode — an explicit value above the cap is clamped, not
199
240
  rejected), `timeoutMs` **20,000**, `maxRetries` **1**, `maxConcurrent` **3**,
200
241
  `maxResponseBytes` **4 MiB**, resolution scan **200 records / 2 pages**.
201
242
  Resolution order: **explicit config > profile > library default** (the
202
243
  existing validation runs on the final values); `profile: 'library'` (the
203
- default) changes nothing, and `rateLimit: { perHour: null }` is the explicit
204
- "disabled" value that beats the profile's limiter (an absent `perHour` means
244
+ default) keeps its per-client defaults, and `rateLimit: { perHour: null }` is the
245
+ explicit local-quota "disabled" value that beats the profile's limiter (an absent `perHour` means
205
246
  "use the profile/default"). Library defaults are unchanged.
206
247
 
207
- The hourly limiter is **per process**: it counts only this client's calls and
248
+ The optional hourly quota is **per client**: it counts only this client's calls and
208
249
  cannot see other instances or integrations on the tenant. The local remaining
209
250
  budget is `client.hourlyBudget()` — `{ perHour, used, remaining }`, or
210
- `undefined` when the limiter is off; the tenant-wide count is
251
+ `undefined` when the local quota is off; the tenant-wide count is
211
252
  `client.thresholdInformation.get()`.
212
253
 
213
254
  The reference MCP servers (`examples/mcp-server.ts`,
214
255
  `examples/mcp-server-http.ts`) read env overrides through one shared helper
215
256
  (`examples/mcp-env-config.ts`; the SDK itself never reads `process.env`):
216
257
  `AUTOTASK_PROFILE` (`library` | `agent`), `AUTOTASK_RATE_LIMIT_PER_HOUR`
217
- (positive integer; `0` / `off` disables the limiter with a stderr warning),
258
+ (positive integer; `0` / `off` disables the local quota with a stderr warning),
218
259
  `AUTOTASK_MAX_CONCURRENT`, `AUTOTASK_TIMEOUT_MS`, `AUTOTASK_MAX_RETRIES`
219
260
  (0 disables retries). Unset = the profile's value; an invalid value stops
220
261
  startup with an `AutotaskConfigError` naming the variable.
package/capabilities.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
- "generatedAt": "2026-11-17T07:45:52.876Z",
2
+ "generatedAt": "2026-11-17T15:37:22.664Z",
3
3
  "groups": {
4
4
  "B": {
5
- "planHash": "04fb614dcdd035a01636e51cf38d8178aeef7c9a1b45faf4af6187875800bd70",
6
- "builtAt": "2026-11-17T07:45:52.855Z",
5
+ "planHash": "959981d335cfd184d8b4e58074d1ab6997b2db87a62683ed13e99c149f8cd4fa",
6
+ "builtAt": "2026-11-17T15:37:22.566Z",
7
7
  "records": [
8
8
  {
9
9
  "id": "appointments.count",
@@ -42786,8 +42786,8 @@
42786
42786
  ]
42787
42787
  },
42788
42788
  "A": {
42789
- "planHash": "04fb614dcdd035a01636e51cf38d8178aeef7c9a1b45faf4af6187875800bd70",
42790
- "builtAt": "2026-11-17T07:45:52.855Z",
42789
+ "planHash": "959981d335cfd184d8b4e58074d1ab6997b2db87a62683ed13e99c149f8cd4fa",
42790
+ "builtAt": "2026-11-17T15:37:22.566Z",
42791
42791
  "records": [
42792
42792
  {
42793
42793
  "id": "companies.count",
@@ -82294,8 +82294,8 @@
82294
82294
  ]
82295
82295
  },
82296
82296
  "operations": {
82297
- "planHash": "04fb614dcdd035a01636e51cf38d8178aeef7c9a1b45faf4af6187875800bd70",
82298
- "builtAt": "2026-11-17T07:45:52.855Z",
82297
+ "planHash": "959981d335cfd184d8b4e58074d1ab6997b2db87a62683ed13e99c149f8cd4fa",
82298
+ "builtAt": "2026-11-17T15:37:22.566Z",
82299
82299
  "records": [
82300
82300
  {
82301
82301
  "id": "operations.aggregate",
@@ -348,8 +348,8 @@ const CAPABILITY_DATA = {
348
348
  ],
349
349
  "groups": {
350
350
  "B": {
351
- "planHash": "04fb614dcdd035a01636e51cf38d8178aeef7c9a1b45faf4af6187875800bd70",
352
- "builtAt": "2026-11-17T07:45:52.855Z",
351
+ "planHash": "959981d335cfd184d8b4e58074d1ab6997b2db87a62683ed13e99c149f8cd4fa",
352
+ "builtAt": "2026-11-17T15:37:22.566Z",
353
353
  "records": [
354
354
  {
355
355
  "id": "appointments.count",
@@ -43132,8 +43132,8 @@ const CAPABILITY_DATA = {
43132
43132
  ]
43133
43133
  },
43134
43134
  "A": {
43135
- "planHash": "04fb614dcdd035a01636e51cf38d8178aeef7c9a1b45faf4af6187875800bd70",
43136
- "builtAt": "2026-11-17T07:45:52.855Z",
43135
+ "planHash": "959981d335cfd184d8b4e58074d1ab6997b2db87a62683ed13e99c149f8cd4fa",
43136
+ "builtAt": "2026-11-17T15:37:22.566Z",
43137
43137
  "records": [
43138
43138
  {
43139
43139
  "id": "companies.count",
@@ -82640,8 +82640,8 @@ const CAPABILITY_DATA = {
82640
82640
  ]
82641
82641
  },
82642
82642
  "operations": {
82643
- "planHash": "04fb614dcdd035a01636e51cf38d8178aeef7c9a1b45faf4af6187875800bd70",
82644
- "builtAt": "2026-11-17T07:45:52.855Z",
82643
+ "planHash": "959981d335cfd184d8b4e58074d1ab6997b2db87a62683ed13e99c149f8cd4fa",
82644
+ "builtAt": "2026-11-17T15:37:22.566Z",
82645
82645
  "records": [
82646
82646
  {
82647
82647
  "id": "operations.aggregate",
@@ -1,18 +1,18 @@
1
1
  'use strict';
2
2
 
3
- var chunkSGH7F2CH_cjs = require('./chunk-SGH7F2CH.cjs');
3
+ var chunkKAZE4WC7_cjs = require('./chunk-KAZE4WC7.cjs');
4
4
 
5
5
 
6
6
 
7
7
  Object.defineProperty(exports, "CAPABILITY_PLAN_HASHES", {
8
8
  enumerable: true,
9
- get: function () { return chunkSGH7F2CH_cjs.CAPABILITY_PLAN_HASHES; }
9
+ get: function () { return chunkKAZE4WC7_cjs.CAPABILITY_PLAN_HASHES; }
10
10
  });
11
11
  Object.defineProperty(exports, "loadCapabilities", {
12
12
  enumerable: true,
13
- get: function () { return chunkSGH7F2CH_cjs.loadCapabilities; }
13
+ get: function () { return chunkKAZE4WC7_cjs.loadCapabilities; }
14
14
  });
15
15
  Object.defineProperty(exports, "loadCapabilityRecords", {
16
16
  enumerable: true,
17
- get: function () { return chunkSGH7F2CH_cjs.loadCapabilityRecords; }
17
+ get: function () { return chunkKAZE4WC7_cjs.loadCapabilityRecords; }
18
18
  });
@@ -1 +1 @@
1
- export { CAPABILITY_PLAN_HASHES, loadCapabilities, loadCapabilityRecords } from './chunk-JCMXQUIC.js';
1
+ export { CAPABILITY_PLAN_HASHES, loadCapabilities, loadCapabilityRecords } from './chunk-SCFB5MF3.js';
@@ -1,5 +1,5 @@
1
- import { ConfigurationItemsResource, ContactsResource, InventoryProductsResource, QuotesResource, ResourceTimeOffAdditionalResource, ResourceTimeOffBalancesResource, ResourcesResource, ServiceCallsResource, TicketChargesResource, TicketsResource, TimeOffRequestsResource, AuthenticateResource, EntityInformationResource, ModulesResource, ThresholdInformationResource, VersionResource, VersionInformationResource, ZoneInformationResource } from './chunk-S6HEIGGM.js';
2
- import { resolveConfig, HttpClient, SIMPLE_RESOURCES, GenericResource, CompaniesResource, ContractsResource, InvoicesResource, TimeEntriesResource, runWithSignal, AutotaskConfigError } from './chunk-YYHCZRUH.js';
1
+ import { ConfigurationItemsResource, ContactsResource, InventoryProductsResource, QuotesResource, ResourceTimeOffAdditionalResource, ResourceTimeOffBalancesResource, ResourcesResource, ServiceCallsResource, TicketChargesResource, TicketsResource, TimeOffRequestsResource, AuthenticateResource, EntityInformationResource, ModulesResource, ThresholdInformationResource, VersionResource, VersionInformationResource, ZoneInformationResource } from './chunk-MMGO3SFL.js';
2
+ import { resolveConfig, HttpClient, SIMPLE_RESOURCES, GenericResource, CompaniesResource, ContractsResource, InvoicesResource, TimeEntriesResource, runWithSignal, runBounded } from './chunk-FK37JXSJ.js';
3
3
 
4
4
  // src/client.ts
5
5
  var AutotaskClient = class {
@@ -216,34 +216,7 @@ var AutotaskClient = class {
216
216
  return runWithSignal(signal, fn);
217
217
  }
218
218
  async batch(fn, items, opts = {}) {
219
- const concurrency = opts.concurrency ?? this.config.maxConcurrent;
220
- if (!Number.isInteger(concurrency) || concurrency <= 0) {
221
- throw new AutotaskConfigError("batch concurrency must be a positive integer");
222
- }
223
- const { signal, settle } = opts;
224
- const results = new Array(items.length);
225
- let next = 0;
226
- let failure;
227
- const worker = async () => {
228
- while (failure === void 0 && next < items.length) {
229
- if (signal?.aborted) {
230
- failure ??= { error: signal.reason };
231
- return;
232
- }
233
- const i = next++;
234
- try {
235
- const item = items[i];
236
- const value = await (signal === void 0 ? fn(item) : runWithSignal(signal, () => fn(item)));
237
- results[i] = settle ? { status: "fulfilled", value } : value;
238
- } catch (error) {
239
- if (settle) results[i] = { status: "rejected", reason: error };
240
- else failure ??= { error };
241
- }
242
- }
243
- };
244
- await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
245
- if (failure !== void 0) throw failure.error;
246
- return results;
219
+ return runBounded(fn, items, { ...opts, concurrency: opts.concurrency ?? this.config.maxConcurrent });
247
220
  }
248
221
  };
249
222