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/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 also passes through the response redaction transform
158
- (`redactResponseBody`, section 10) at this single choke point — secret fields
159
- always, personal/business-sensitive data by default.
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?)` is the status → class mapper — it deep-redacts the
187
- vendor body once (section 10), so `vendorError` and the adopted message never
188
- carry a pinned field value. `item: null` on a single GET (HTTP 200) is a NOT
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` | `true` | — | response redaction for PII + confidential fields (section 10); `false` = raw personal data, secrets still redacted |
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 boundary redacts response field values. A vendor 2xx JSON body is
2594
- deep-redacted at the single choke point (the 2xx branch of
2595
- `HttpClient.request`, after `JSON.parse`), and the vendor 4xx/5xx error body
2596
- is deep-redacted once in `errorFromStatus` (so `vendorError` and the adopted
2597
- message never carry a pinned field value — a 4xx that echoes a request body
2598
- which carried a secret cannot leak through the error path). The transform is
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** — redacted by default, opt-out | 53 pinned names (class sizes pinned by `test/redact.test.ts`): 41 personal-data fields (emails, phones, addresses, login names, …) + 12 business/device-sensitive fields (tax id, domain + registration dates, RMA/device audit IP/MAC/mobile/SNMP/contact, …) | redacted unless `redactPersonalData: false` (config, default `true`). |
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 under the default policy; the vendor-side
2638
- constraint remains the backstop (the `ConflictError` path). Set
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.88.1",
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,