node-autotask 0.65.0 → 0.66.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 (34) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/MCP_TOOL_CATALOG.json +34 -14
  3. package/README.md +1 -1
  4. package/capabilities.json +157 -96
  5. package/dist/capabilities-data.js +156 -95
  6. package/dist/capabilities.cjs +4 -4
  7. package/dist/capabilities.js +1 -1
  8. package/dist/{chunk-C73NILBZ.js → chunk-4HJVHVPE.js} +2 -2
  9. package/dist/{chunk-WKR5IJEC.cjs → chunk-FLVMENXG.cjs} +3 -3
  10. package/dist/{chunk-ULI4UUB3.js → chunk-KO36QZXN.js} +390 -405
  11. package/dist/{chunk-N4EO3KAY.js → chunk-L5K2D2MZ.js} +3 -3
  12. package/dist/{chunk-M63TK4ZH.cjs → chunk-QG3O5G4L.cjs} +175 -179
  13. package/dist/{chunk-MXLE2F5G.js → chunk-T5TI22K5.js} +4 -8
  14. package/dist/{chunk-NTHEFYA7.cjs → chunk-TIFJFCCN.cjs} +395 -410
  15. package/dist/{chunk-UHV7SAX6.cjs → chunk-XAJ7SBPE.cjs} +31 -31
  16. package/dist/{index-vcFKvZqm.d.ts → index-BZ11hF8H.d.ts} +10 -24
  17. package/dist/{index-CRVQBajX.d.cts → index-DnisYPlj.d.cts} +10 -24
  18. package/dist/index.cjs +84 -84
  19. package/dist/index.d.cts +2 -2
  20. package/dist/index.d.ts +2 -2
  21. package/dist/index.js +5 -5
  22. package/dist/operations/index.cjs +50 -50
  23. package/dist/operations/index.d.cts +3 -3
  24. package/dist/operations/index.d.ts +3 -3
  25. package/dist/operations/index.js +2 -2
  26. package/dist/pool.cjs +8 -8
  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 +2 -2
  33. package/docs/VENDOR-QUIRKS.md +50 -34
  34. package/package.json +1 -1
@@ -1,18 +1,25 @@
1
- # Known vendor limits & zone quirks — node-autotask
1
+ # Vendor contracts and visibility guidance — node-autotask
2
2
 
3
3
  > Section 11 of the API reference, kept in its own file so `docs/API.md` stays
4
4
  > an orientation read. Section numbers outside §11 (§1–§10, §12–§13) refer to
5
5
  > [`docs/API.md`](./API.md).
6
6
 
7
- ## 11. Known vendor limits & zone quirks (australia-nz / ww29, live-verified)
7
+ ## 11. Vendor contracts and visibility guidance
8
8
 
9
- Live-verified facts from the ww29 (australia-nz) sandbox — receipts in
10
- `.run/mcp-fix-20261003/reports/` (delete-gap.md, rw-cycles.md, te-smarts-impl.md,
11
- sweep-v050.md; run artifacts, not committed). The vendored spec (api-docs.json)
12
- declares `required: []` and no field types on the target models, so every fact
13
- below is LIVE-DISCOVERED; other zones may differ (zone-robustness is a separate
14
- campaign). Each LLM-facing note in the MCP surface (manifest descriptions and
15
- input-column notes) carries its zone label and traces back to this section.
9
+ All Autotask zones use the same entity API. This section retains the context of prior reference-tenant
10
+ probes; an empty list, a rejected input or a missing reference in that tenant does not establish the
11
+ current tenant's inventory, API-user permissions or API capability (#447). Served guidance therefore
12
+ uses conditional visibility warnings and current field metadata. Structural routes and documented
13
+ field constraints remain authoritative; verify known records and preview valid inputs before writing.
14
+ Historical receipts remain in the repository history and `vendorEvidence` where present.
15
+
16
+ Vendor ids on product vendors, subscriptions and assets refer to Companies. Use the current
17
+ `companyType` picklist and a scoped Companies query, or a known company id; the absence of a
18
+ standalone Vendors endpoint does not make these references unavailable. See the official
19
+ [ProductVendors](https://autotask.net/help/DeveloperHelp/Content/APIs/REST/Entities/ProductVendorsEntity.htm),
20
+ [Subscriptions](https://autotask.net/help/DeveloperHelp/Content/APIs/REST/Entities/SubscriptionsEntity.htm)
21
+ and [ConfigurationItems](https://www.autotask.net/help/developerhelp/content/apis/REST/Entities/ConfigurationItemsEntity.htm)
22
+ field references.
16
23
 
17
24
  ### 11.1 No entity DELETE on 7 endpoints (the vendor-405 delete boundary)
18
25
 
@@ -89,11 +96,11 @@ generated note (the one-call recovery op that shared it was deleted in
89
96
  companyID, isActive (a NUMBER) }`; tasks `{ projectID (required IN THE BODY —
90
97
  the scoped parent path carries the parent too), taskType (1/2), status,
91
98
  title }`.
92
- - `configuration_items.create` **product wall** (S11-B I receipts): the body must set
93
- `productID` to an **existing Product**; `products.count` is 0 on ww29 (blind surface,
94
- no enumerable id) — this create is UNAVAILABLE in tenants without products; the CI
95
- type itself is discoverable via `configuration_item_types.query` (the wall is the
96
- FK, not the type).
99
+ - `configuration_items.create` requires `productID` to reference an existing Product.
100
+ A reference tenant returned an empty products count, but that does not establish that the API
101
+ cannot create assets or that the tenant has no products (#447). Use a known product id or read
102
+ products with the appropriate API-user visibility. The CI type is discoverable through
103
+ `configuration_item_types.query`.
97
104
 
98
105
  ### 11.4 `time_entries.create` — zone facts
99
106
 
@@ -193,21 +200,21 @@ of the data).
193
200
  the plain number.
194
201
  - `queryBounded` on a pinned surface carries **`blindSurface`** on the
195
202
  result object when the walk returned zero items (for `unfiltered-blind`
196
- surfaces, ONLY when the call is unfiltered — a filtered empty answer is a
197
- true absence). A non-empty result is never stamped (data present is not
203
+ surfaces, ONLY when the call is unfiltered — a filtered empty answer means
204
+ no rows returned under current API-user visibility). A non-empty result is never stamped (data present is not
198
205
  blind in this scope).
199
- - **The `blindSurface` object**: `{ surface, zone, kind, authority, note }` —
200
- `surface` = one of the pins below; `zone` = `australia-nz` (the facts are
201
- zone-specific — never read across zones); `kind` = `unowned-blind`
206
+ - **The `blindSurface` object**: `{ surface, kind, authority, note }` —
207
+ `surface` names a pinned warning channel; no zone is selected.
208
+ `kind` = `unowned-blind`
202
209
  (companies) / `unfiltered-blind`
203
210
  (tickets, billing_codes, and the UDF definition / list-item counts — post-merge P1: the tickets class moved from
204
211
  `fully-blind` after S12-B P1 live-verified that FILTERED tickets queries
205
212
  return data); `authority` = the `<resource>.get` op that is the REMEDY
206
213
  (it returns the record even while count/query are blind); `note` = the zone
207
- fact + remedy, LLM-consumer grade.
214
+ warning + remedy, without asserting current-user blindness.
208
215
  - **The pinned surfaces** (live-verified ww29; the pin is
209
216
  `plan.blindSurfaces` in `capabilities.plan.json` — the same block stamps
210
- `metadata.blindSurface` on exactly these records, and
217
+ `metadata.blindSurface` on the matching records, and
211
218
  `capabilities:check` asserts the set-equality, so the describe channel and
212
219
  the result channel cannot drift):
213
220
  `companies.count` · `companies.query` · `tickets.count` · `tickets.query` ·
@@ -221,8 +228,8 @@ of the data).
221
228
  vendor `count` AND `query` take the same filter shape, and the filtered
222
229
  query RETURNS DATA (live-verified S12-B P1: 3 open tickets via a
223
230
  companyID+status filter; the earlier `fully-blind` pin — unfiltered-only
224
- evidence — overstated the blind surface). A filtered empty result is a
225
- true absence, never a sentinel. The decision lives in exactly ONE place —
231
+ evidence — overstated the blind surface). A filtered empty result is not stamped; it reports no rows returned under
232
+ current API-user visibility, without establishing tenant-wide absence. The decision lives in exactly ONE place —
226
233
  `blindStampFor` in `src/resources/base.ts` — shared by the query wrap, the
227
234
  count wrap, and the `companies.fullProfile` open-tickets part, so no
228
235
  consumer can drift.
@@ -258,7 +265,7 @@ synthesis. The registry-backed create records — `tickets` / `companies` /
258
265
  carried one until it was cut in #292), and every example passes its own record's `inputSchema`
259
266
  (the governor dispatch validator; pinned by
260
267
  `test/scripts/mcp-surface/create-examples.test.ts`). The `configuration_items`
261
- body documents the §11.3 product wall, not a working create;
268
+ body illustrates the §11.3 productID requirement with placeholder ids;
262
269
  `time_entries.create` says to resolve the allocation code yourself (a filtered
263
270
  `billing_codes` query) or pass a linkage pin. The plan's 12-target list also names `tickets.createIfNotExists`,
264
271
  `companies.createIfNotExists` and `contacts.createIfNotExists` — those three
@@ -532,12 +539,21 @@ serve `message`/`remedy` as they are.
532
539
  - `non-mutable` **is** a create blocker: the vendor refuses the create write
533
540
  itself for the entity. No row carries it today.
534
541
  - `blind-reference` rows always name `referenceField` (the field whose
535
- referenced table is blind for this API user), including the contract
542
+ referenced record must be verified against current data and API-user permissions), including the contract
536
543
  billing-rule / exclusion / service / bundle rows.
537
- - `blocker.unsatisfiableViaApi: true` is the structured flag for creates the
538
- API cannot satisfy for any input: exactly the `picklist-unexposed` rows (the
539
- attachment `Type` picklist) and the `undocumented-ladder` row
540
- (`opportunities`). Clause 15 holds the flag and the kind in step.
544
+ - Failed reference-tenant create probes do not establish that no valid API input exists (#447).
545
+ Opportunities and attachment creates are documented API operations; their unverified input sets
546
+ carry `unknown` with `unproven: true`, preserving the error evidence without declaring them
547
+ impossible. The `picklist-unexposed` and `undocumented-ladder` kinds and their
548
+ `unsatisfiableViaApi` flag remain reserved for compatibility, but no current row carries them.
549
+ Read the current field metadata and the documented create contract, then preview corrected input;
550
+ do not guess values or retry an unchanged rejected payload.
551
+
552
+ **Conditional parent and reference findings (#447).** `blind-parent` and `blind-reference`
553
+ are retained diagnostic kinds. They do not establish that the current API user cannot enumerate
554
+ or read the referenced value. Query the current tenant, read a known id, or use current field metadata
555
+ for a picklist; if the required value is not readable, ask for it. Specific contract-type, billing-type
556
+ and active-service requirements remain in the guidance, and prior error evidence is preserved.
541
557
 
542
558
  **Where to read the company (issue #246).** Some resources have no `companyID`
543
559
  of their own. `row.parentCompany?: { via, resource, field }` says which parent
@@ -1453,8 +1469,8 @@ release carries them):
1453
1469
  `limit` (default 50, clamped 1..500) = the part's `MaxRecords` + the capped
1454
1470
  lists (`warnings`, the `unposted` anti-join); each part flags `capped` /
1455
1471
  `hasMore` + the typed `status` (`ok` / `blind` / `skipped` — the empty
1456
- join set SKIPS the time query with the honest note; a filtered empty part is
1457
- a TRUE zero). The unposted section = the fetched time entries whose id is in
1472
+ join set SKIPS the time query with the honest note; a filtered empty part reports
1473
+ no rows returned under current API-user visibility). The unposted section = the fetched time entries whose id is in
1458
1474
  no fetched billing item's `timeEntryID` (client-side anti-join, zero wire).
1459
1475
  Warnings: `noTimeEntry` (billing items whose `timeEntryID` is empty/0) and
1460
1476
  `hourDelta` (billed `quantity` ≠ entry `hoursWorked` — strict: the vendor
@@ -1783,8 +1799,8 @@ returns the contract's reconciled P&L over a date window:
1783
1799
  `customer: null` + `parts.customer: 'absent'` + `customerAbsent: <code>`.
1784
1800
  Every tickets call is
1785
1801
  `contractID`-filtered, so the pinned `unfiltered-blind` tickets class
1786
- never stamps a filtered empty (a filtered 0 is a TRUE zero with the
1787
- honest note); the 0-row parts carry the pinned
1802
+ never stamps a filtered empty (a filtered 0 reports no rows returned under current
1803
+ API-user visibility, without establishing tenant-wide absence); the 0-row parts carry the pinned
1788
1804
  `tenant-empty-for-user` `emptyReason` stamp where attached. A dangling
1789
1805
  customer FK (`companies.get` 404) degrades to `customer: null` +
1790
1806
  `parts.customer: 'skipped'` — NOT an error (the CIs read still fires on
@@ -1992,7 +2008,7 @@ name reads per call, so a plain read returns raw ids), through the same
1992
2008
  ### 11.31 UDF definition and picklist-value surfaces (0.61.0 #428, live-verified 2026-11-11; issue #432)
1993
2009
 
1994
2010
  - The read paths match the vendored spec URLs with no 404 and no shape mismatch: `UserDefinedFieldDefinitions/query`, `.../query/count`, `UserDefinedFieldDefinitions/{id}`, the standalone read-only `UserDefinedFieldListItems/query`, and the parent-scoped `UserDefinedFields/{parentId}/ListItems/{id}` all answer coherent rows. The item GET returns the full vendor model with no label siblings, while query rows carry the SDK-added `dataTypeLabel` / `udfTypeLabel` (on the verified tenant: List = dataType 3, String = 1; udfType 6 = Installed_Product, 9 = Site_Config).
1995
- - The UNFILTERED count surface on both UDF entities is blind on the verified zone (issue #432): the unfiltered `query/count` answers 0 while a filtered count on the same surface (a single `id gt 0` condition) returns a three-digit total, and the unfiltered `query` page returns real rows. Same quirk class as the blind tickets / unowned-company count surfaces (B5): a filtered empty answer is a true absence, an unfiltered 0 proves nothing. 0.61.0 served the blind 0 without the typed `blindSurface` sentinel (no plan pin), and a `latest` read anchored on that 0 answered empty; since #432 both `count` ops are pinned (`unfiltered-blind`, count only — the unfiltered query is not blind), so the unfiltered 0 carries the sentinel. Since #435 `latest` re-probes that blind 0 with the filtered `id gt 0` count and runs the normal full-set or threshold mode on the real total (0.62.0 to 0.63.0 walked the query instead, which refused with `LATEST_WINDOW_INCOMPLETE` once the visible rows passed the walk limit).
2011
+ - The UNFILTERED count surface on both UDF entities is blind on the verified zone (issue #432): the unfiltered `query/count` answers 0 while a filtered count on the same surface (a single `id gt 0` condition) returns a three-digit total, and the unfiltered `query` page returns real rows. Same quirk class as the blind tickets / unowned-company count surfaces (B5): a filtered empty answer reports no rows returned under current API-user visibility, without establishing tenant-wide absence; an unfiltered 0 proves nothing. 0.61.0 served the blind 0 without the typed `blindSurface` sentinel (no plan pin), and a `latest` read anchored on that 0 answered empty; since #432 both `count` ops are pinned (`unfiltered-blind`, count only — the unfiltered query is not blind), so the unfiltered 0 carries the sentinel. Since #435 `latest` re-probes that blind 0 with the filtered `id gt 0` count and runs the normal full-set or threshold mode on the real total (0.62.0 to 0.63.0 walked the query instead, which refused with `LATEST_WINDOW_INCOMPLETE` once the visible rows passed the walk limit).
1996
2012
  - A `udfFieldId` filter on the standalone list-items endpoint narrows exactly to one definition's values: every returned row carried the filtered `udfFieldId`, and the filtered `query/count` equaled the filtered row count.
1997
2013
  - Absence of DELETE confirmed by surface enumeration (no delete op is served on either entity; the deleteBoundary note is spec-derived) — a live DELETE was not attempted. Soft removal is `isActive=false`; the vendor caps active company UDFs at 200.
1998
2014
  - 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-autotask",
3
- "version": "0.65.0",
3
+ "version": "0.66.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,