node-autotask 0.88.1 → 0.90.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 +12 -0
- package/MCP_TOOL_CATALOG.json +2 -2
- package/README.md +3 -4
- 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-DSHWQMF2.cjs → chunk-4CI27SCM.cjs} +30 -30
- package/dist/{chunk-KM7ITBOT.js → chunk-CY6USWUY.js} +22 -10
- package/dist/{chunk-JHDT4O7N.cjs → chunk-D7MJC7HA.cjs} +201 -201
- package/dist/{chunk-JVVE4XEN.js → chunk-HU6OGAPI.js} +2 -2
- package/dist/{chunk-ZADTVF6M.js → chunk-K5X4BPQC.js} +3 -3
- package/dist/{chunk-YTOBU3Z6.cjs → chunk-OI6E5XQA.cjs} +27 -15
- package/dist/{chunk-33UVHMFN.js → chunk-Q73VQSUP.js} +3 -3
- package/dist/{chunk-SHJ7EOBW.cjs → chunk-ZLMYYO7R.cjs} +3 -3
- package/dist/{index-XDIy_GvD.d.cts → index-BEqbDuMk.d.cts} +6 -11
- package/dist/{index-GSA44LRd.d.ts → index-DWyJAad_.d.ts} +6 -11
- package/dist/index.cjs +85 -85
- package/dist/index.d.cts +7 -10
- package/dist/index.d.ts +7 -10
- package/dist/index.js +5 -5
- package/dist/operations/index.cjs +51 -51
- 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 +17 -29
- package/package.json +1 -1
package/docs/API.md
CHANGED
|
@@ -154,9 +154,10 @@ while headroom remains; neither informational endpoint bypasses the hourly guard
|
|
|
154
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`).
|
|
155
155
|
|
|
156
156
|
Credential-shaped fields are redacted in audit payloads by default.
|
|
157
|
-
Every 2xx JSON body
|
|
158
|
-
(`redactResponseBody`, section 10)
|
|
159
|
-
|
|
157
|
+
Every 2xx JSON body passes through response redaction at this point
|
|
158
|
+
(`redactResponseBody`, section 10). The transform always redacts secret
|
|
159
|
+
fields. Set `redactPersonalData: true` to also redact personal and
|
|
160
|
+
business-sensitive fields.
|
|
160
161
|
|
|
161
162
|
### 1.5 `errors/` — error hierarchy
|
|
162
163
|
|
|
@@ -183,9 +184,9 @@ person's name, section 7.7). The vendor documents no error bodies; the shape
|
|
|
183
184
|
`{ errors: [{ message, field?, code? }] }` is pinned from the node's
|
|
184
185
|
errorHandler and parsed defensively (`parseVendorErrors`,
|
|
185
186
|
`formatVendorDetail`). `errorFromStatus(status, body, url?, operation?,
|
|
186
|
-
redactPersonalData?)`
|
|
187
|
-
|
|
188
|
-
|
|
187
|
+
redactPersonalData?)` maps the HTTP status to an error class. It applies
|
|
188
|
+
the configured field redaction to the parsed vendor body before deriving
|
|
189
|
+
`vendorError` and the message (section 10). `item: null` on a single GET (HTTP 200) is a NOT
|
|
189
190
|
FOUND, not a success — the vendor's not-found signal. `isAutotaskError` is
|
|
190
191
|
the type guard. Two house classes are thrown by the TRANSPORT (not
|
|
191
192
|
`errorFromStatus`): `UnexpectedContentTypeError` (`UNEXPECTED_CONTENT_TYPE`,
|
|
@@ -578,7 +579,7 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
|
|
|
578
579
|
| `resolution.scanOnMiss` | `false` | — | re-check a bare-value `resolve` miss with the bounded client scan (exact match on the search fields). Off: the server filter's zero items is a complete non-match (`null`, one call) |
|
|
579
580
|
| `logger` | `NoopLogger` | — | request log sink |
|
|
580
581
|
| `labels` | `false` | — | opt-in label siblings (`statusLabel`, `<fk>Name`) on query, aggregate and fetch rows (issue #287); a per-call `names` overrides it — section 11.27 |
|
|
581
|
-
| `redactPersonalData` | `
|
|
582
|
+
| `redactPersonalData` | `false` | — | set `true` to redact personal and confidential fields (section 10) |
|
|
582
583
|
| `cache` | on | read 4096 / field 256 entries | `{ ttlMs?, fieldTtlMs?, companyIndexTtlMs?, store? }` the SDK's in-memory caches (issue #286; one block): single-record reads (get-by-id, the id branch of `resolve`, composite FK reads, `operations.expandResourceNames` names) live `ttlMs` (default 5 min; the reference tables `REFERENCE_ENTITIES` live 1 h), entity field metadata lives `fieldTtlMs` (default 5 min). `false` = every channel off. A real write through the client clears the record cache; a vendor drift signal drops one entity's field metadata (section 11.14). Ordinary lists, queries, counts, mutations and errors are never cached. The named exception is the separate `companies.searchFuzzy` name index (default refresh 30 min, `companyIndexTtlMs`); company writes invalidate and rebuild it, and `false` disables it too. `fieldCache`, `resourceNameCache` and `cache.perResourceTtlMs` were removed in 0.40.0 (the first two are refused) |
|
|
583
584
|
| `update` | off | — | `{ putFallback?: boolean }` opt-in PUT item-path fallback for a 404'd non-collectionUpdate update route (issue #34) — see section 11.16. A TYPED 404 retries ONCE as `PUT /{Entity}/{id}` with the caller's fields merged onto a fresh unredacted read (never a null-clearing partial); collectionUpdate routes, `raw: true` updates and every non-404 fault are never retried — a declined gate throws the self-explaining error naming the route, the status and the opt-in |
|
|
584
585
|
| `reResolveZoneOn401` | off | — | opt-in zone re-resolution on 401 (issue #43) — see section 11.19. A 401 on a relative path against a CATALOG base makes ONE unauthenticated vendor zone-discovery call; if the tenant's zone base has moved, the client re-points its live base URL (process-lifetime, observable via `http.baseUrl`) and retries the SAME request ONCE. An explicit `baseUrl` and an absolute path are never re-pointed; a resolved base identical to the live one, or a discovery fault, propagates today's typed 401 untouched (zero retry); a retry that 401s again carries `details.zoneRecovery = { from, to, retried: true }` |
|
|
@@ -2590,20 +2591,12 @@ of the plan (`test/scripts/relationships-artifact.test.ts` pins it
|
|
|
2590
2591
|
TDD-style).
|
|
2591
2592
|
## 10. Response redaction (secret and personal fields)
|
|
2592
2593
|
|
|
2593
|
-
The SDK
|
|
2594
|
-
|
|
2595
|
-
|
|
2596
|
-
|
|
2597
|
-
|
|
2598
|
-
|
|
2599
|
-
mode-agnostic (a pure function of the parsed body): dedicated tools, the
|
|
2600
|
-
three mode tools (`autotask_read`/`autotask_write`/`autotask_delete`),
|
|
2601
|
-
compositions and the special-op reads all cross the boundary already
|
|
2602
|
-
redacted. The value of every redacted key is replaced with
|
|
2603
|
-
the existing marker `'[REDACTED]'` (the key itself is kept — stable shape);
|
|
2604
|
-
the input is never mutated and request bodies are never redacted (credentials
|
|
2605
|
-
travel in create/patch requests by design; the G10b request-body-audit
|
|
2606
|
-
redaction is a separate mechanism, untouched).
|
|
2594
|
+
The SDK applies field redaction to parsed 2xx responses, parsed 4xx/5xx
|
|
2595
|
+
responses before deriving `vendorError` and the error message, and input
|
|
2596
|
+
echoes in dry-run results. Redacted fields retain their keys and use the
|
|
2597
|
+
value `'[REDACTED]'`. Raw non-JSON error text and `details.bodySnippet` are
|
|
2598
|
+
free text. Diagnostic snippets are byte-capped, and field redaction applies
|
|
2599
|
+
only to structured data. Request-body audit redaction is separate.
|
|
2607
2600
|
|
|
2608
2601
|
Two classes, two behaviors (the A1 leak-audit design,
|
|
2609
2602
|
`.run/reports/leak-audit.md`):
|
|
@@ -2611,7 +2604,7 @@ Two classes, two behaviors (the A1 leak-audit design,
|
|
|
2611
2604
|
| class | names | behavior |
|
|
2612
2605
|
|-------|-------|----------|
|
|
2613
2606
|
| **SECRET** — always redacted, **no opt-out** | `password`, `secretKey`, `secret` (exact vendor casing, case-sensitive) | usable credentials in plaintext responses (portal password, webhook HMAC signing secrets, integration-vendor credential). The SDK is the **only permission boundary** — the vendor API has no read-only key — so these values never cross the SDK boundary, regardless of config. |
|
|
2614
|
-
| **PII + CONFIDENTIAL**
|
|
2607
|
+
| **PII + CONFIDENTIAL** | Personal fields such as email, phone, address, and login name, and business-sensitive fields such as tax ID, device IP, and device MAC | Returned by default. Set `redactPersonalData: true` to redact them. |
|
|
2615
2608
|
|
|
2616
2609
|
- **Pinned name sets, not a regex.** The A1 census proves the 3 SECRET names
|
|
2617
2610
|
are secret-only across all 787 swagger definitions (17,167 leaf fields), so
|
|
@@ -2623,10 +2616,6 @@ Two classes, two behaviors (the A1 leak-audit design,
|
|
|
2623
2616
|
- **Exempt: `authToken`** (`AuthTokenResultModel`, `GET /V1.0/Authenticate`) —
|
|
2624
2617
|
the endpoint's purpose is token issuance; it is in no pinned set and is
|
|
2625
2618
|
never redacted (pinned by test).
|
|
2626
|
-
- **Opt-out scope + risk.** `redactPersonalData: false` disables ONLY the
|
|
2627
|
-
PII + CONFIDENTIAL class — the SECRET class is always redacted. Opt out for
|
|
2628
|
-
regulated workflows that need raw personal data and keep model transcripts
|
|
2629
|
-
inside your control; credential values are never opted out.
|
|
2630
2619
|
- **`includeFields` interaction.** Redaction runs on the parsed response body
|
|
2631
2620
|
(server-side of the response, after any vendor field filtering, before the
|
|
2632
2621
|
caller) and is **independent of `includeFields`** by construction: a
|
|
@@ -2634,9 +2623,8 @@ Two classes, two behaviors (the A1 leak-audit design,
|
|
|
2634
2623
|
`'[REDACTED]'` — the stable, safe behavior.
|
|
2635
2624
|
- **Internal consumers see what the caller sees.** SDK logic that reads
|
|
2636
2625
|
response values (e.g. `contacts.moveToCompany`'s duplicate-email precheck)
|
|
2637
|
-
filters on the redacted value
|
|
2638
|
-
constraint remains the backstop (the `ConflictError` path).
|
|
2639
|
-
`redactPersonalData: false` where such pre-checks must run on raw PII.
|
|
2626
|
+
filters on the redacted value when `redactPersonalData: true`. The
|
|
2627
|
+
vendor-side constraint remains the backstop (the `ConflictError` path).
|
|
2640
2628
|
|
|
2641
2629
|
## 11. Known vendor limits & zone quirks (australia-nz / ww29, live-verified)
|
|
2642
2630
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "node-autotask",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.90.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,
|