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.
- package/CHANGELOG.md +36 -0
- package/MCP_TOOL_CATALOG.json +35 -15
- package/README.md +1 -1
- package/capabilities.json +174 -113
- package/dist/capabilities-data.js +173 -112
- package/dist/capabilities.cjs +4 -4
- package/dist/capabilities.js +1 -1
- package/dist/{chunk-NWQVMOP5.js → chunk-4HJVHVPE.js} +2 -2
- package/dist/{chunk-ENRW25IT.cjs → chunk-FLVMENXG.cjs} +3 -3
- package/dist/{chunk-BQNC4RYG.js → chunk-KO36QZXN.js} +418 -414
- package/dist/{chunk-C3OLJGY5.js → chunk-L5K2D2MZ.js} +3 -3
- package/dist/{chunk-MIKVE6VJ.cjs → chunk-QG3O5G4L.cjs} +175 -179
- package/dist/{chunk-SVCTQVTV.js → chunk-T5TI22K5.js} +4 -8
- package/dist/{chunk-AGGOZD2J.cjs → chunk-TIFJFCCN.cjs} +423 -419
- package/dist/{chunk-7DC524X3.cjs → chunk-XAJ7SBPE.cjs} +31 -31
- package/dist/{index-RkTNsoOz.d.ts → index-BZ11hF8H.d.ts} +10 -24
- package/dist/{index-B7bZQ34O.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 +64 -37
- 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
|
|
|
@@ -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
|
|
80
|
-
picklist. Required: `{ description, noteType, publish }` — `ticketID`
|
|
81
|
-
in the body (the scoped parent path supplies it); `title` is
|
|
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`
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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
|
|
186
|
-
|
|
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,
|
|
189
|
-
`surface`
|
|
190
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
214
|
-
|
|
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
|
|
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
|
|
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
|
-
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
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
|
|
1446
|
-
|
|
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
|
|
1776
|
-
|
|
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
|
|
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.
|
|
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,
|