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.
- package/CHANGELOG.md +19 -0
- package/MCP_TOOL_CATALOG.json +34 -14
- package/README.md +1 -1
- package/capabilities.json +157 -96
- package/dist/capabilities-data.js +156 -95
- package/dist/capabilities.cjs +4 -4
- package/dist/capabilities.js +1 -1
- package/dist/{chunk-C73NILBZ.js → chunk-4HJVHVPE.js} +2 -2
- package/dist/{chunk-WKR5IJEC.cjs → chunk-FLVMENXG.cjs} +3 -3
- package/dist/{chunk-ULI4UUB3.js → chunk-KO36QZXN.js} +390 -405
- package/dist/{chunk-N4EO3KAY.js → chunk-L5K2D2MZ.js} +3 -3
- package/dist/{chunk-M63TK4ZH.cjs → chunk-QG3O5G4L.cjs} +175 -179
- package/dist/{chunk-MXLE2F5G.js → chunk-T5TI22K5.js} +4 -8
- package/dist/{chunk-NTHEFYA7.cjs → chunk-TIFJFCCN.cjs} +395 -410
- package/dist/{chunk-UHV7SAX6.cjs → chunk-XAJ7SBPE.cjs} +31 -31
- package/dist/{index-vcFKvZqm.d.ts → index-BZ11hF8H.d.ts} +10 -24
- package/dist/{index-CRVQBajX.d.cts → index-DnisYPlj.d.cts} +10 -24
- package/dist/index.cjs +84 -84
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +5 -5
- package/dist/operations/index.cjs +50 -50
- package/dist/operations/index.d.cts +3 -3
- package/dist/operations/index.d.ts +3 -3
- package/dist/operations/index.js +2 -2
- package/dist/pool.cjs +8 -8
- 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 +2 -2
- package/docs/VENDOR-QUIRKS.md +50 -34
- package/package.json +1 -1
package/docs/VENDOR-QUIRKS.md
CHANGED
|
@@ -1,18 +1,25 @@
|
|
|
1
|
-
#
|
|
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.
|
|
7
|
+
## 11. Vendor contracts and visibility guidance
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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`
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
|
197
|
-
|
|
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,
|
|
200
|
-
`surface`
|
|
201
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
225
|
-
|
|
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
|
|
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
|
|
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
|
-
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
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
|
|
1457
|
-
|
|
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
|
|
1787
|
-
|
|
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
|
|
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.
|
|
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,
|