node-autotask 0.64.1 → 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 +36 -0
  2. package/MCP_TOOL_CATALOG.json +35 -15
  3. package/README.md +1 -1
  4. package/capabilities.json +174 -113
  5. package/dist/capabilities-data.js +173 -112
  6. package/dist/capabilities.cjs +4 -4
  7. package/dist/capabilities.js +1 -1
  8. package/dist/{chunk-NWQVMOP5.js → chunk-4HJVHVPE.js} +2 -2
  9. package/dist/{chunk-ENRW25IT.cjs → chunk-FLVMENXG.cjs} +3 -3
  10. package/dist/{chunk-BQNC4RYG.js → chunk-KO36QZXN.js} +418 -414
  11. package/dist/{chunk-C3OLJGY5.js → chunk-L5K2D2MZ.js} +3 -3
  12. package/dist/{chunk-MIKVE6VJ.cjs → chunk-QG3O5G4L.cjs} +175 -179
  13. package/dist/{chunk-SVCTQVTV.js → chunk-T5TI22K5.js} +4 -8
  14. package/dist/{chunk-AGGOZD2J.cjs → chunk-TIFJFCCN.cjs} +423 -419
  15. package/dist/{chunk-7DC524X3.cjs → chunk-XAJ7SBPE.cjs} +31 -31
  16. package/dist/{index-RkTNsoOz.d.ts → index-BZ11hF8H.d.ts} +10 -24
  17. package/dist/{index-B7bZQ34O.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 +64 -37
  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
 
@@ -76,9 +83,12 @@ generated note (the one-call recovery op that shared it was deleted in
76
83
  `LocationModel.isActive` takes a boolean (V6, rw-cycles).
77
84
  - `ticket_notes.create` (live-verified, S11-B N3): `publish` is an **integer
78
85
  picklist (1/2/4) — NOT a boolean** (a JSON boolean 500s at the vendor parse
79
- layer; same zone family as the isActive quirk) and `noteType` is an integer
80
- picklist. Required: `{ description, noteType, publish }` — `ticketID` is NOT
81
- in the body (the scoped parent path supplies it); `title` is optional.
86
+ layer; same family as the isActive quirk) and `noteType` is an integer
87
+ picklist. Required: `{ description, noteType, publish, title }` — `ticketID`
88
+ is NOT in the body (the scoped parent path supplies it); `title` is
89
+ live-required on create (live-verified ww29 2026-11-17: a title-less create was
90
+ refused with the verbatim vendor 500 `Missing Required Field: title.`; a
91
+ create with title succeeded).
82
92
  - **Live-required sets** (the spec declares none; a first create without them
83
93
  500s with a typed field-level error): tickets `{ title, status, priority,
84
94
  companyID, queueID }`; companies `{ companyName, companyType, phone,
@@ -86,11 +96,11 @@ generated note (the one-call recovery op that shared it was deleted in
86
96
  companyID, isActive (a NUMBER) }`; tasks `{ projectID (required IN THE BODY —
87
97
  the scoped parent path carries the parent too), taskType (1/2), status,
88
98
  title }`.
89
- - `configuration_items.create` **product wall** (S11-B I receipts): the body must set
90
- `productID` to an **existing Product**; `products.count` is 0 on ww29 (blind surface,
91
- no enumerable id) — this create is UNAVAILABLE in tenants without products; the CI
92
- type itself is discoverable via `configuration_item_types.query` (the wall is the
93
- 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`.
94
104
 
95
105
  ### 11.4 `time_entries.create` — zone facts
96
106
 
@@ -111,6 +121,14 @@ generated note (the one-call recovery op that shared it was deleted in
111
121
  (resource, role) pairs exist in the tenant (the then-`postedWithin` rows: resourceID
112
122
  5001 / 5003 with roleID 4001). The typed W-A3 pointer note
113
123
  carries this.
124
+ - **Internal-organisation billability (issue #444; live-verified ww29 2026-11-17)**: on
125
+ internal-organisation tickets (companyID 0) `showOnInvoice` must be `false` —
126
+ `true` was refused at apply with the verbatim vendor 500 "This time entry
127
+ cannot be shown on an Invoice because it is for your internal
128
+ organization." — and the vendor stores `isNonBillable: true` on
129
+ internal-organisation entries (the payload sent `false`; the read-back
130
+ showed `true`). Served as a structured
131
+ `field-constraint` quirk on `time_entries.create` and in the op's usage text.
114
132
  - **Derived fields (issue #219 N8, live ww29 2026-10-26 — twelve time entries
115
133
  logged on ticket 7005)**: `hoursWorked` is recomputed from
116
134
  `startDateTime`/`endDateTime` (a create sending `1.43` for a 14:00-15:26
@@ -182,21 +200,21 @@ of the data).
182
200
  the plain number.
183
201
  - `queryBounded` on a pinned surface carries **`blindSurface`** on the
184
202
  result object when the walk returned zero items (for `unfiltered-blind`
185
- surfaces, ONLY when the call is unfiltered — a filtered empty answer is a
186
- 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
187
205
  blind in this scope).
188
- - **The `blindSurface` object**: `{ surface, zone, kind, authority, note }` —
189
- `surface` = one of the pins below; `zone` = `australia-nz` (the facts are
190
- 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`
191
209
  (companies) / `unfiltered-blind`
192
210
  (tickets, billing_codes, and the UDF definition / list-item counts — post-merge P1: the tickets class moved from
193
211
  `fully-blind` after S12-B P1 live-verified that FILTERED tickets queries
194
212
  return data); `authority` = the `<resource>.get` op that is the REMEDY
195
213
  (it returns the record even while count/query are blind); `note` = the zone
196
- fact + remedy, LLM-consumer grade.
214
+ warning + remedy, without asserting current-user blindness.
197
215
  - **The pinned surfaces** (live-verified ww29; the pin is
198
216
  `plan.blindSurfaces` in `capabilities.plan.json` — the same block stamps
199
- `metadata.blindSurface` on exactly these records, and
217
+ `metadata.blindSurface` on the matching records, and
200
218
  `capabilities:check` asserts the set-equality, so the describe channel and
201
219
  the result channel cannot drift):
202
220
  `companies.count` · `companies.query` · `tickets.count` · `tickets.query` ·
@@ -210,8 +228,8 @@ of the data).
210
228
  vendor `count` AND `query` take the same filter shape, and the filtered
211
229
  query RETURNS DATA (live-verified S12-B P1: 3 open tickets via a
212
230
  companyID+status filter; the earlier `fully-blind` pin — unfiltered-only
213
- evidence — overstated the blind surface). A filtered empty result is a
214
- 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 —
215
233
  `blindStampFor` in `src/resources/base.ts` — shared by the query wrap, the
216
234
  count wrap, and the `companies.fullProfile` open-tickets part, so no
217
235
  consumer can drift.
@@ -247,7 +265,7 @@ synthesis. The registry-backed create records — `tickets` / `companies` /
247
265
  carried one until it was cut in #292), and every example passes its own record's `inputSchema`
248
266
  (the governor dispatch validator; pinned by
249
267
  `test/scripts/mcp-surface/create-examples.test.ts`). The `configuration_items`
250
- body documents the §11.3 product wall, not a working create;
268
+ body illustrates the §11.3 productID requirement with placeholder ids;
251
269
  `time_entries.create` says to resolve the allocation code yourself (a filtered
252
270
  `billing_codes` query) or pass a linkage pin. The plan's 12-target list also names `tickets.createIfNotExists`,
253
271
  `companies.createIfNotExists` and `contacts.createIfNotExists` — those three
@@ -521,12 +539,21 @@ serve `message`/`remedy` as they are.
521
539
  - `non-mutable` **is** a create blocker: the vendor refuses the create write
522
540
  itself for the entity. No row carries it today.
523
541
  - `blind-reference` rows always name `referenceField` (the field whose
524
- 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
525
543
  billing-rule / exclusion / service / bundle rows.
526
- - `blocker.unsatisfiableViaApi: true` is the structured flag for creates the
527
- API cannot satisfy for any input: exactly the `picklist-unexposed` rows (the
528
- attachment `Type` picklist) and the `undocumented-ladder` row
529
- (`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.
530
557
 
531
558
  **Where to read the company (issue #246).** Some resources have no `companyID`
532
559
  of their own. `row.parentCompany?: { via, resource, field }` says which parent
@@ -1442,8 +1469,8 @@ release carries them):
1442
1469
  `limit` (default 50, clamped 1..500) = the part's `MaxRecords` + the capped
1443
1470
  lists (`warnings`, the `unposted` anti-join); each part flags `capped` /
1444
1471
  `hasMore` + the typed `status` (`ok` / `blind` / `skipped` — the empty
1445
- join set SKIPS the time query with the honest note; a filtered empty part is
1446
- 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
1447
1474
  no fetched billing item's `timeEntryID` (client-side anti-join, zero wire).
1448
1475
  Warnings: `noTimeEntry` (billing items whose `timeEntryID` is empty/0) and
1449
1476
  `hourDelta` (billed `quantity` ≠ entry `hoursWorked` — strict: the vendor
@@ -1772,8 +1799,8 @@ returns the contract's reconciled P&L over a date window:
1772
1799
  `customer: null` + `parts.customer: 'absent'` + `customerAbsent: <code>`.
1773
1800
  Every tickets call is
1774
1801
  `contractID`-filtered, so the pinned `unfiltered-blind` tickets class
1775
- never stamps a filtered empty (a filtered 0 is a TRUE zero with the
1776
- 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
1777
1804
  `tenant-empty-for-user` `emptyReason` stamp where attached. A dangling
1778
1805
  customer FK (`companies.get` 404) degrades to `customer: null` +
1779
1806
  `parts.customer: 'skipped'` — NOT an error (the CIs read still fires on
@@ -1981,7 +2008,7 @@ name reads per call, so a plain read returns raw ids), through the same
1981
2008
  ### 11.31 UDF definition and picklist-value surfaces (0.61.0 #428, live-verified 2026-11-11; issue #432)
1982
2009
 
1983
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).
1984
- - 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).
1985
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.
1986
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.
1987
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.64.1",
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,