node-autotask 0.64.1 → 0.65.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 CHANGED
@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.65.0] - 2026-11-17
11
+
12
+ ### Fixed
13
+
14
+ - `ticket_notes.create` re-stamps the live-verified facts after a 2026-11-17 re-probe (#443): `title` is now
15
+ live-required on create — the vendor 500s `Missing Required Field: title.` on a title-less create, and a
16
+ create with `title` succeeds — so `title` joins the live-required set and the live-proven prefix
17
+ (`description, noteType, publish, title`), the not-in-body quirk drops the "title is optional" clause,
18
+ and the usage/argNotes/example text is re-stamped with the dated re-probe evidence.
19
+ - `time_entries.create` gains the internal-organisation billability rule, live-verified 2026-11-17 (#444):
20
+ on internal-organisation tickets (companyID 0) `showOnInvoice` must be `false` — `true` 500s "This time
21
+ entry cannot be shown on an Invoice because it is for your internal organization." — and the vendor stores
22
+ `isNonBillable` as `true` on internal-organisation entries (a create that sent `false` read back `true`). Stamped as a
23
+ structured `field-constraint` quirk and surfaced in the op's usage text and the served tool description.
24
+
25
+ Plan change, so the plan hash moves (docs/VENDOR-QUIRKS.md §11.3, §11.4).
26
+
10
27
  ## [0.64.1] - 2026-11-16
11
28
 
12
29
  ### Changed
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "generatedBy": "scripts/build-tool-catalog.mjs",
3
- "generatedAt": "2026-11-12T01:38:07.478Z",
4
- "planHash": "c92aaa7dd21259e4e8b545e44cebf4d831e5f68a0c9e41e26af1c2966c84bdef",
3
+ "generatedAt": "2026-11-17T02:57:14.178Z",
4
+ "planHash": "546e9de78d62f2c30190c1bb82f89be73f9cc0a75d633d771956566c78f4efeb",
5
5
  "metaTools": [
6
6
  {
7
7
  "name": "autotask_catalog",
@@ -11188,7 +11188,7 @@
11188
11188
  "operation": "time_entries.dateWorkedWindow",
11189
11189
  "core": false,
11190
11190
  "tool": "autotask_timeEntry_date_worked_window",
11191
- "purpose": "The ONE posted-state read: a bounded read over the inclusive dateWorked window [from, to] (UTC 'YYYY-MM-DD' days) with the posted/unposted split derived from the billing_items.timeEntryID join — never a postedDate read (this zone's TimeEntry entity has no postedDate; postedDate exist|notExist 500s). Approval is NOT consulted (this zone never populates billingApprovalDateTime yet bills those entries). The no-window form is gone: read with no dateWorked filter goes through time_entries.query.",
11191
+ "purpose": "The ONE posted-state read: a bounded read over the inclusive dateWorked window [from, to] (UTC 'YYYY-MM-DD' days) with the posted/unposted split derived from the billing_items.timeEntryID join — never a postedDate read (the TimeEntry entity has no postedDate; postedDate exist|notExist 500s). Approval is NOT consulted (the vendor never populates billingApprovalDateTime yet bills those entries). The no-window form is gone: read with no dateWorked filter goes through time_entries.query.",
11192
11192
  "preferredWhen": null,
11193
11193
  "backingOperation": "time_entries.dateWorkedWindow",
11194
11194
  "effect": "read",
@@ -22773,7 +22773,7 @@
22773
22773
  "core": false,
22774
22774
  "tool": "autotask_relationship_map",
22775
22775
  "purpose": "Describe one resource's full relationship surface in a single ZERO-wire call: its parent, its children (with the scoped-op presence per child), its natural lookup keys, its pinned blind surfaces, and the zone-verified create required sets + quirks.",
22776
- "preferredWhen": "The first call when planning any multi-step composition (what exists under this resource, what a create requires, which surfaces are blind in this zone) — zero wire, so it is free to consult before every plan. For a live record, use the resource's read ops.",
22776
+ "preferredWhen": "The first call when planning any multi-step composition (what exists under this resource, what a create requires, which surfaces are blind) — zero wire, so it is free to consult before every plan. For a live record, use the resource's read ops.",
22777
22777
  "backingOperation": "operations.relationshipMap",
22778
22778
  "effect": "read",
22779
22779
  "dryRunFirst": false,
package/capabilities.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
- "generatedAt": "2026-11-12T01:38:06.882Z",
2
+ "generatedAt": "2026-11-17T02:57:12.910Z",
3
3
  "groups": {
4
4
  "B": {
5
- "planHash": "c92aaa7dd21259e4e8b545e44cebf4d831e5f68a0c9e41e26af1c2966c84bdef",
6
- "builtAt": "2026-11-12T01:38:06.865Z",
5
+ "planHash": "546e9de78d62f2c30190c1bb82f89be73f9cc0a75d633d771956566c78f4efeb",
6
+ "builtAt": "2026-11-17T02:57:12.895Z",
7
7
  "records": [
8
8
  {
9
9
  "id": "appointments.count",
@@ -716,7 +716,7 @@
716
716
  },
717
717
  "metadata": {
718
718
  "purpose": "Count billing code records matching a JSON filter.",
719
- "usage": "Unwraps queryCount; returns a plain number. Zone quirk: the unfiltered count/query surface is blind — query with `useType` (1 = general, 3 = internal) + `isActive` filters. A raw caller must pass those filters (the allocation-code-aware createForResource node op was cut).",
719
+ "usage": "Unwraps queryCount; returns a plain number. Vendor quirk: the unfiltered count/query surface is blind — query with `useType` (1 = general, 3 = internal) + `isActive` filters. A raw caller must pass those filters (the allocation-code-aware createForResource node op was cut).",
720
720
  "preferredWhen": null,
721
721
  "related": [
722
722
  "billing_codes.query"
@@ -1040,7 +1040,7 @@
1040
1040
  },
1041
1041
  "metadata": {
1042
1042
  "purpose": "Query BillingCode records with a JSON filter.",
1043
- "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Zone quirk: the unfiltered count/query surface is blind — query with `useType` (1 = general, 3 = internal) + `isActive` filters. A raw caller must pass those filters (the allocation-code-aware createForResource node op was cut). Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
1043
+ "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Vendor quirk: the unfiltered count/query surface is blind — query with `useType` (1 = general, 3 = internal) + `isActive` filters. A raw caller must pass those filters (the allocation-code-aware createForResource node op was cut). Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
1044
1044
  "preferredWhen": "Default for filtered reads (the bounded query op). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. Prefer an includeFields subset over the full model (field names via operations.fieldCatalog). latest: N is the latest-N rows (id-descending) when the newest rows are the goal (the vendor has no sort — count-anchored, docs/API.md §4). Prefer a hand-listed includeFields for common narrow reads (removed the closed fieldsPreset presets — the v1 billing_join field list for billing_items.query, if you need it, is: companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable); noteChars: N caps the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose) to N chars each with the explicit … [+N chars truncated] marker (opt-in; the raw result when absent).",
1045
1045
  "related": [
1046
1046
  "billing_codes.resolve"
@@ -39026,7 +39026,7 @@
39026
39026
  },
39027
39027
  "examples": [
39028
39028
  "await client.timeEntries.create({ resourceID: 2001, dateWorked: '2026-10-03' }, { dryRun: true })",
39029
- "this zone: the low-level escape hatch — posts exactly the given body (resourceID is the only vendor-required field) and lets the vendor linkage/allocation-code gates surface verbatim Resolve the allocation code yourself (billing_codes query with the family + active filter — the unfiltered surface is blind in this zone) or pass a linkage pin (ticketID/taskID/roleID)."
39029
+ "the low-level escape hatch — posts exactly the given body (resourceID is the only vendor-required field) and lets the vendor linkage/allocation-code gates surface verbatim Resolve the allocation code yourself (billing_codes query with the family + active filter — the unfiltered surface is blind) or pass a linkage pin (ticketID/taskID/roleID)."
39030
39030
  ],
39031
39031
  "permissions": "unknown",
39032
39032
  "pagination": {
@@ -39041,7 +39041,7 @@
39041
39041
  },
39042
39042
  "metadata": {
39043
39043
  "purpose": "Create a time entry.",
39044
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed.",
39044
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. On internal-organisation tickets (companyID 0) showOnInvoice must be false — true is refused by the vendor (500 \"This time entry cannot be shown on an Invoice because it is for your internal organization.\"); the vendor stores isNonBillable true on internal-organisation entries (a create that sent false read back true)",
39045
39045
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
39046
39046
  "related": [
39047
39047
  "time_entries.update"
@@ -39194,7 +39194,7 @@
39194
39194
  "set": 8
39195
39195
  },
39196
39196
  "metadata": {
39197
- "purpose": "The ONE posted-state read: a bounded read over the inclusive dateWorked window [from, to] (UTC 'YYYY-MM-DD' days) with the posted/unposted split derived from the billing_items.timeEntryID join — never a postedDate read (this zone's TimeEntry entity has no postedDate; postedDate exist|notExist 500s). Approval is NOT consulted (this zone never populates billingApprovalDateTime yet bills those entries). The no-window form is gone: read with no dateWorked filter goes through time_entries.query.",
39197
+ "purpose": "The ONE posted-state read: a bounded read over the inclusive dateWorked window [from, to] (UTC 'YYYY-MM-DD' days) with the posted/unposted split derived from the billing_items.timeEntryID join — never a postedDate read (the TimeEntry entity has no postedDate; postedDate exist|notExist 500s). Approval is NOT consulted (the vendor never populates billingApprovalDateTime yet bills those entries). The no-window form is gone: read with no dateWorked filter goes through time_entries.query.",
39198
39198
  "usage": "dateWorkedWindow(from, to, opts?): from/to are required inclusive 'YYYY-MM-DD' UTC days (impossible calendar days like 2026-02-31 and from-after-to are refused pre-request, zero wire). opts.state: 'posted' | 'unposted' — client-side narrowing AFTER the join (replaces the old posted boolean and the getPosted/getUnposted state modes); omitted = both. opts.limit 1-500 (default 500 = the hard cap); opts.ticketID / opts.resourceID eq narrowings sent server-side. Returns { items, postedCount, unpostedCount, window { from, to } (wire bounds, second precision), nextCursor, unconfirmed, truncated }: postedCount/unpostedCount split EVERY entry read (before state narrowing) while items is narrowed, so counts cover the returned rows ONLY (at most limit); truncated is true when the entry read has a live next-page cursor or a join page was truncated; unconfirmed entries sit in neither count nor items. Paging: opts.cursor (a previous nextCursor; a cursor whose path is not the TimeEntries continuation is refused RESPONSE_REJECTED; over 2048 chars refused). opts.countOnly: true (with opts.maxVendorCalls integer 1-200, default 30) returns the whole-window totals { window, total, postedCount, unpostedCount, vendorCalls, estimate, budget } instead of rows: one count call sizes the window, every entry page is read ids-only and joined at 250 ids per join, then the window is counted again — over budget BUDGET_EXCEEDED (the estimate named), a truncated join RESOLUTION_TRUNCATED, a distinct-id total equal to neither count INVALID_RESPONSE; no short total is ever returned. 429 and vendor faults propagate typed. Wire: one bounded POST /V1.0/TimeEntries/query (MaxRecords, dateWorked gte/lte + the eq narrowings) plus at most 2 BillingItems join queries (250 ids each). For a window with more rows than the cap, page with cursor or reconcile through time_entries.query with the same dateWorked filter (its 2500-row walk cap).",
39199
39199
  "preferredWhen": null,
39200
39200
  "related": [],
@@ -40198,7 +40198,7 @@
40198
40198
  },
40199
40199
  "metadata": {
40200
40200
  "purpose": "Update a time entry.",
40201
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. ticketID does NOT persist on update: the vendor returns success but keeps the old ticketID (probed live on this zone). To re-parent use time_entries.moveToTicket (create, verify, delete). The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
40201
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. ticketID does NOT persist on update: the vendor returns success but keeps the old ticketID (probed live, 2026-10-21). To re-parent use time_entries.moveToTicket (create, verify, delete). The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
40202
40202
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change. Not for ticketID: the vendor ignores it on update; use time_entries.moveToTicket.",
40203
40203
  "related": [
40204
40204
  "time_entries.get"
@@ -42725,8 +42725,8 @@
42725
42725
  ]
42726
42726
  },
42727
42727
  "A": {
42728
- "planHash": "c92aaa7dd21259e4e8b545e44cebf4d831e5f68a0c9e41e26af1c2966c84bdef",
42729
- "builtAt": "2026-11-12T01:38:06.866Z",
42728
+ "planHash": "546e9de78d62f2c30190c1bb82f89be73f9cc0a75d633d771956566c78f4efeb",
42729
+ "builtAt": "2026-11-17T02:57:12.896Z",
42730
42730
  "records": [
42731
42731
  {
42732
42732
  "id": "companies.count",
@@ -42779,7 +42779,7 @@
42779
42779
  },
42780
42780
  "metadata": {
42781
42781
  "purpose": "Count company records matching a JSON filter.",
42782
- "usage": "Unwraps queryCount; returns a plain number. Zone quirk: count/query return 0/empty for companies not owned by the caller — verify presence with get(id), not count.",
42782
+ "usage": "Unwraps queryCount; returns a plain number. Vendor quirk: count/query return 0/empty for companies not owned by the caller — verify presence with get(id), not count.",
42783
42783
  "preferredWhen": null,
42784
42784
  "related": [
42785
42785
  "companies.query"
@@ -42846,7 +42846,7 @@
42846
42846
  },
42847
42847
  "examples": [
42848
42848
  "await client.companies.create({ companyName: 'Example', companyType: 1, phone: '1300555001', isActive: true, ownerResourceID: 2001 }, { dryRun: true })",
42849
- "this zone validated: created a company with this body (required: companyName, companyType, phone, ownerResourceID — a non-API-only resource). CompanyModel has NO description field (the vendor silently 200s unknown fields); the create auto-creates a vendor \"Primary Address\" location (UI-only cleanup)."
42849
+ "validated: created a company with this body (required: companyName, companyType, phone, ownerResourceID — a non-API-only resource). CompanyModel has NO description field (the vendor silently 200s unknown fields); the create auto-creates a vendor \"Primary Address\" location (UI-only cleanup)."
42850
42850
  ],
42851
42851
  "permissions": "unknown",
42852
42852
  "pagination": {
@@ -42991,7 +42991,7 @@
42991
42991
  },
42992
42992
  "examples": [
42993
42993
  "await client.companies.fullProfile(1001)",
42994
- "this zone validated: a run served 1001 in exactly 6 wire (1 location; openTickets: 3 — data). args: (company id, optional { contactLimit, noteLimit, ticketLimit, projectLimit — default 50 }). openTickets part: open = status NOT in the tenant-resolved closed set (`tickets.statusSemantics`; ids {5} with source 'picklist' on this zone today, 'assumed' + a disclosing note when the catalog is unreadable); the part's query is always filtered and the tickets surface is blind UNFILTERED (verified: the filtered query returns data), so an empty answer is a TRUE zero — the typed blind part (blind: true + the blindSurface sentinel) only for a blind class that covers this filtered call. Company missing → NOT_FOUND."
42994
+ "validated: a run served 1001 in exactly 6 wire (1 location; openTickets: 3 — data). args: (company id, optional { contactLimit, noteLimit, ticketLimit, projectLimit — default 50 }). openTickets part: open = status NOT in the tenant-resolved closed set (`tickets.statusSemantics`; ids {5} with source 'picklist' today, 'assumed' + a disclosing note when the catalog is unreadable); the part's query is always filtered and the tickets surface is blind UNFILTERED (verified: the filtered query returns data), so an empty answer is a TRUE zero — the typed blind part (blind: true + the blindSurface sentinel) only for a blind class that covers this filtered call. Company missing → NOT_FOUND."
42995
42995
  ],
42996
42996
  "permissions": "unknown",
42997
42997
  "pagination": {
@@ -43006,7 +43006,7 @@
43006
43006
  },
43007
43007
  "metadata": {
43008
43008
  "purpose": "Get everything the node knows about one company in a single call: the company record, its locations, contacts and notes, its open tickets, and its projects — every part separately reported with caps.",
43009
- "usage": "args[0] is the company id (number); args[1] (optional) is the options object { contactLimit?: number (default 50), noteLimit?: number (default 50), ticketLimit?: number (default 50), projectLimit?: number (default 50), names?: boolean (default false — ON adds the opt-in name/label siblings — the company row (owner / created-by resource names), the openTickets rows (the same closed-scope ticket-field siblings as tickets.fullContext, incl. the ticket picklist labels), the projects rows (lead / creator resource names + the contract name — project picklists stay OUT of the closed label scope) — + the top-level `names` section; the siblings ride the existing default-on caches (NO new cache)), maxNameReads?: number (default 20 — the budget of COLD wire name reads: cache hits are free of the budget, lowerable never raised; over-budget ids serve name: null and the names section sets `truncated: true`, never an error) }. Wire: exactly 6 reads (companies.get + 5 companyID-filtered queries). With names: true, N added name reads (N = the distinct uncached ids, capped by maxNameReads) + at most ONE fieldCatalog labels read (zero wire on a warm fieldCache). The openTickets part: open = status NOT in the resolved closed set — the closed ids come from the tenant's Tickets status picklist via `tickets.statusSemantics` (one cache-aware field-metadata read, zero wire on a warm cache), falling back to id 5 with `source: 'assumed'` and a part `note` that discloses it; the part carries `closedStatus { closedIds, source, note }` and the always-filtered query applies the resolved leaf (a single `not-eq` for one closed id, `notIn` for several); the tickets count/query surface is blind UNFILTERED on this zone (verified: the FILTERED query returns data), so this always-filtered part degrades to `blind: true` + the typed `blindSurface` sentinel ONLY when the filter-aware `blindStampFor` predicate stamps this call (post-merge P1) — a filtered empty answer is a TRUE zero (the company has no open tickets), and a non-empty answer is data; the flag clears either way. Company missing → NOT_FOUND.",
43009
+ "usage": "args[0] is the company id (number); args[1] (optional) is the options object { contactLimit?: number (default 50), noteLimit?: number (default 50), ticketLimit?: number (default 50), projectLimit?: number (default 50), names?: boolean (default false — ON adds the opt-in name/label siblings — the company row (owner / created-by resource names), the openTickets rows (the same closed-scope ticket-field siblings as tickets.fullContext, incl. the ticket picklist labels), the projects rows (lead / creator resource names + the contract name — project picklists stay OUT of the closed label scope) — + the top-level `names` section; the siblings ride the existing default-on caches (NO new cache)), maxNameReads?: number (default 20 — the budget of COLD wire name reads: cache hits are free of the budget, lowerable never raised; over-budget ids serve name: null and the names section sets `truncated: true`, never an error) }. Wire: exactly 6 reads (companies.get + 5 companyID-filtered queries). With names: true, N added name reads (N = the distinct uncached ids, capped by maxNameReads) + at most ONE fieldCatalog labels read (zero wire on a warm fieldCache). The openTickets part: open = status NOT in the resolved closed set — the closed ids come from the tenant's Tickets status picklist via `tickets.statusSemantics` (one cache-aware field-metadata read, zero wire on a warm cache), falling back to id 5 with `source: 'assumed'` and a part `note` that discloses it; the part carries `closedStatus { closedIds, source, note }` and the always-filtered query applies the resolved leaf (a single `not-eq` for one closed id, `notIn` for several); the tickets count/query surface is blind UNFILTERED (verified: the FILTERED query returns data), so this always-filtered part degrades to `blind: true` + the typed `blindSurface` sentinel ONLY when the filter-aware `blindStampFor` predicate stamps this call (post-merge P1) — a filtered empty answer is a TRUE zero (the company has no open tickets), and a non-empty answer is data; the flag clears either way. Company missing → NOT_FOUND.",
43010
43010
  "preferredWhen": "The single read for 'what do you know about this company' — replaces 6 raw reads + describes with one call. companies.get alone is just the record.",
43011
43011
  "related": [
43012
43012
  "companies.get",
@@ -43622,7 +43622,7 @@
43622
43622
  },
43623
43623
  "metadata": {
43624
43624
  "purpose": "Query Company records with a JSON filter.",
43625
- "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Zone quirk: count/query return 0/empty for companies not owned by the caller — verify presence with get(id), not count. Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
43625
+ "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Vendor quirk: count/query return 0/empty for companies not owned by the caller — verify presence with get(id), not count. Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
43626
43626
  "preferredWhen": "Default for filtered reads (the bounded query op). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. Prefer an includeFields subset over the full model (field names via operations.fieldCatalog). latest: N is the latest-N rows (id-descending) when the newest rows are the goal (the vendor has no sort — count-anchored, docs/API.md §4). Prefer a hand-listed includeFields for common narrow reads (removed the closed fieldsPreset presets — the v1 billing_join field list for billing_items.query, if you need it, is: companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable); noteChars: N caps the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose) to N chars each with the explicit … [+N chars truncated] marker (opt-in; the raw result when absent).",
43627
43627
  "related": [
43628
43628
  "companies.resolve"
@@ -44136,7 +44136,7 @@
44136
44136
  },
44137
44137
  "metadata": {
44138
44138
  "purpose": "One call for a company's unbilled work: its posted billing items (per source), the time behind them (joined through the company's tickets and tasks — time entries carry no companyID), the per-ticket rollup, the unposted anti-join section, ex-tax totals + hours, and the billing-vs-time warnings",
44139
- "usage": "args[0] is the company id (number); args[1] (optional) is UnbilledWorkOptions { source?: 'posted_uninvoiced' (default — the billing items with no invoiceID (notExist), the uninvoiced mark) | 'invoice' (invoiceID = invoiceId; the invoice record itself is NOT fetched in v1 — the items already carry invoiceID/itemDate/amounts) | 'date_range' (itemDate window — dateFrom + dateTo REQUIRED) | 'tickets' (ticketID in ticketIds; the time-entries part additionally joins those tickets directly), includeParent?: boolean (default true — ONE level only, via company.parentCompanyID; dangling → parent: null, parent parts empty, NOT an error), dateFrom?/dateTo?: string (YYYY-MM-DD — the itemDate window on the billing part in EVERY source, the dateWorked window on the time part; required for date_range), invoiceId?: number | string (required shape for invoice), ticketIds?: (number | string)[] (required non-empty for tickets), includeNotes?: boolean (default false — the note fields EXCLUDED; when true the time part requests summaryNotes and the billing part description, each capped at noteChars with the marker BEFORE the server-side untrusted wrapper), noteChars?: number (default 400, integer >= 1), rollup?: 'ticket' (default — per-ticket rows; the unassigned bucket carries ticketId null) | 'entry' (the capped per-entry list), limit?: number (default 50, clamped 1..500 — the per-part record cap) }. Wire: exactly 6 bounded reads without a parent (company get + tickets + projects + tasks + billing + time queries), 7 with a parent present — zero mutating; includeNotes/noteChars/rollup add ZERO wire (response-side). The join: the company's ticket ids (tickets query, companyID in) + the company's task ids (projects query, companyID in → tasks query, projectID in); the time query is or [taskID in, ticketID in] (the join sets are capped at 300 ids per list — the 8000-char filter cap — with a documented note when truncated); an EMPTY join set skips the time part with status 'skipped' + the honest note (no tasks/tickets to join against is NOT evidence of no time entries). Per part: the capped/hasMore flags + the status 'ok' | 'blind' | 'skipped' (the blind stamp is the filter-aware predicate — a FILTERED empty part is a TRUE zero with the status note, never a sentinel; the pinned this zone unfiltered-blind tickets surface is always queried filtered here). The billing part rides the billing_join column list as its IncludeFields (the join's columns, + id; + description with includeNotes). The client-side folds (zero wire): rollup (billing items by ticketID; time entries by their own ticketID — the vendored TaskModel carries no ticket field, so the entry's own ticketID is the only resolvable ticket link; null → the unassigned bucket), unposted (the fetched entries whose id is in no fetched billing item's timeEntryID), totals { preTax = Σ extendedPrice, hours = Σ hoursWorked, entryCount, totalAmount, taxDollars — surfaced for reconciliation } derived from the SAME folded rows (one source of truth), warnings { noTimeEntry (the billing items whose timeEntryID is empty/0 — capped list + count), hourDelta (the billing items WITH a resolvable time entry where |billed quantity − hoursWorked| > 0 — strict; capped list + count) }. Company missing → NOT_FOUND (zero further wire). Closed opts bag: an unknown key → typed CONFIG_ERROR naming the key + the valid keys (one-round complete problem list, pre-request, zero wire).",
44139
+ "usage": "args[0] is the company id (number); args[1] (optional) is UnbilledWorkOptions { source?: 'posted_uninvoiced' (default — the billing items with no invoiceID (notExist), the uninvoiced mark) | 'invoice' (invoiceID = invoiceId; the invoice record itself is NOT fetched in v1 — the items already carry invoiceID/itemDate/amounts) | 'date_range' (itemDate window — dateFrom + dateTo REQUIRED) | 'tickets' (ticketID in ticketIds; the time-entries part additionally joins those tickets directly), includeParent?: boolean (default true — ONE level only, via company.parentCompanyID; dangling → parent: null, parent parts empty, NOT an error), dateFrom?/dateTo?: string (YYYY-MM-DD — the itemDate window on the billing part in EVERY source, the dateWorked window on the time part; required for date_range), invoiceId?: number | string (required shape for invoice), ticketIds?: (number | string)[] (required non-empty for tickets), includeNotes?: boolean (default false — the note fields EXCLUDED; when true the time part requests summaryNotes and the billing part description, each capped at noteChars with the marker BEFORE the server-side untrusted wrapper), noteChars?: number (default 400, integer >= 1), rollup?: 'ticket' (default — per-ticket rows; the unassigned bucket carries ticketId null) | 'entry' (the capped per-entry list), limit?: number (default 50, clamped 1..500 — the per-part record cap) }. Wire: exactly 6 bounded reads without a parent (company get + tickets + projects + tasks + billing + time queries), 7 with a parent present — zero mutating; includeNotes/noteChars/rollup add ZERO wire (response-side). The join: the company's ticket ids (tickets query, companyID in) + the company's task ids (projects query, companyID in → tasks query, projectID in); the time query is or [taskID in, ticketID in] (the join sets are capped at 300 ids per list — the 8000-char filter cap — with a documented note when truncated); an EMPTY join set skips the time part with status 'skipped' + the honest note (no tasks/tickets to join against is NOT evidence of no time entries). Per part: the capped/hasMore flags + the status 'ok' | 'blind' | 'skipped' (the blind stamp is the filter-aware predicate — a FILTERED empty part is a TRUE zero with the status note, never a sentinel; the pinned unfiltered-blind tickets surface is always queried filtered here). The billing part rides the billing_join column list as its IncludeFields (the join's columns, + id; + description with includeNotes). The client-side folds (zero wire): rollup (billing items by ticketID; time entries by their own ticketID — the vendored TaskModel carries no ticket field, so the entry's own ticketID is the only resolvable ticket link; null → the unassigned bucket), unposted (the fetched entries whose id is in no fetched billing item's timeEntryID), totals { preTax = Σ extendedPrice, hours = Σ hoursWorked, entryCount, totalAmount, taxDollars — surfaced for reconciliation } derived from the SAME folded rows (one source of truth), warnings { noTimeEntry (the billing items whose timeEntryID is empty/0 — capped list + count), hourDelta (the billing items WITH a resolvable time entry where |billed quantity − hoursWorked| > 0 — strict; capped list + count) }. Company missing → NOT_FOUND (zero further wire). Closed opts bag: an unknown key → typed CONFIG_ERROR naming the key + the valid keys (one-round complete problem list, pre-request, zero wire).",
44140
44140
  "preferredWhen": "For allocation-style questions about one company's posted/uninvoiced work — replaces the multi-call billing×time×ticket hand-join; companies.fullProfile for the general company picture; operations.aggregate for cross-resource existence/totals",
44141
44141
  "related": [
44142
44142
  "companies.fullProfile",
@@ -51305,7 +51305,7 @@
51305
51305
  },
51306
51306
  "examples": [
51307
51307
  "await client.configurationItems.create({ companyID: 1001, productID: 123, isActive: true }, { dryRun: true })",
51308
- "this zone live wall (probes 500d on types 3/5/6): the body must set productID to an EXISTING Product (123 is illustrative — this zone has none: products.count is 0, no enumerable id) — this create is UNAVAILABLE in tenants without products. The body documents the wall, not a working create."
51308
+ "live wall (probes 500d on types 3/5/6): the body must set productID to an EXISTING Product (123 is illustrative — the tenant has none: products.count is 0, no enumerable id) — this create is UNAVAILABLE in tenants without products. The body documents the wall, not a working create."
51309
51309
  ],
51310
51310
  "permissions": "unknown",
51311
51311
  "pagination": {
@@ -51320,7 +51320,7 @@
51320
51320
  },
51321
51321
  "metadata": {
51322
51322
  "purpose": "Create a configuration item.",
51323
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Live wall: the body must set productID to an EXISTING Product; products.count is 0 on this zone (blind surface, no enumerable id) — this create is UNAVAILABLE in tenants without products. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
51323
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Live wall: the body must set productID to an EXISTING Product; products.count is 0 (blind surface, no enumerable id) — this create is UNAVAILABLE in tenants without products. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
51324
51324
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
51325
51325
  "related": [
51326
51326
  "configuration_items.update"
@@ -51933,7 +51933,7 @@
51933
51933
  },
51934
51934
  "examples": [
51935
51935
  "await client.configurationItems.profile(1)",
51936
- "Shape-only: NO CI record exists on this zone (the product wall blocked every create — products.count = 0), so the id is a placeholder and the op is mock-verified. args: (CI id, optional { noteLimit (default 50), relatedLimit (default 50) }). Wire: <=6 reads (get + type + category + 3 item-scoped queries; a dangling type/category FK skips its read). productAssociations is TYPED, never an error: on a tenant without enumerable products the part carries blind: true + the zone-facts note. CI missing → NOT_FOUND."
51936
+ "Shape-only: NO CI record exists (the product wall blocked every create — products.count = 0), so the id is a placeholder and the op is mock-verified. args: (CI id, optional { noteLimit (default 50), relatedLimit (default 50) }). Wire: <=6 reads (get + type + category + 3 item-scoped queries; a dangling type/category FK skips its read). productAssociations is TYPED, never an error: on a tenant without enumerable products the part carries blind: true + the zone-facts note. CI missing → NOT_FOUND."
51937
51937
  ],
51938
51938
  "permissions": "unknown",
51939
51939
  "pagination": {
@@ -51948,7 +51948,7 @@
51948
51948
  },
51949
51949
  "metadata": {
51950
51950
  "purpose": "Get the full profile of one configuration item in a single call: the item, its type and category records, its notes, related items and billing-product associations.",
51951
- "usage": "args[0] is the configuration item id (number); args[1] (optional) is the options object { noteLimit?: number (default 50), relatedLimit?: number (default 50), names?: boolean (default false — ON adds the opt-in name sibling on the ci row (closed scope: the contract name — the CI row has no issue-listed picklist fields, so no labels) + the top-level `names` section; the sibling rides the existing default-on caches (NO new cache)), maxNameReads?: number (default 20 — the budget of COLD wire name reads, lowerable never raised; over-budget ids serve name: null and the names section sets `truncated: true`, never an error) }. Wire: <=6 reads (get + type + category + 3 item-scoped queries; a dangling type/category FK skips its read). With names: true, N added name reads (N = the distinct uncached FK ids, capped by maxNameReads). productAssociations: the raw association rows (billingProductID FK) + the typed product-wall annotation from the served zone facts (blind: true + note) on tenants without enumerable products (this zone: products.count = 0) — never an error. CI missing → NOT_FOUND. On this zone no CI record exists (the product wall blocked every create) — no CI exists there (the product wall is the boundary), so the op is mock-verified.",
51951
+ "usage": "args[0] is the configuration item id (number); args[1] (optional) is the options object { noteLimit?: number (default 50), relatedLimit?: number (default 50), names?: boolean (default false — ON adds the opt-in name sibling on the ci row (closed scope: the contract name — the CI row has no issue-listed picklist fields, so no labels) + the top-level `names` section; the sibling rides the existing default-on caches (NO new cache)), maxNameReads?: number (default 20 — the budget of COLD wire name reads, lowerable never raised; over-budget ids serve name: null and the names section sets `truncated: true`, never an error) }. Wire: <=6 reads (get + type + category + 3 item-scoped queries; a dangling type/category FK skips its read). With names: true, N added name reads (N = the distinct uncached FK ids, capped by maxNameReads). productAssociations: the raw association rows (billingProductID FK) + the typed product-wall annotation from the served zone facts (blind: true + note) on tenants without enumerable products (products.count = 0) — never an error. CI missing → NOT_FOUND. On a productless tenant no CI record exists (the product wall blocked every create) — no CI exists there (the product wall is the boundary), so the op is mock-verified.",
51952
51952
  "preferredWhen": "The single read for 'what is this configuration item' — replaces 5-6 raw reads + describes with one call.",
51953
51953
  "related": [
51954
51954
  "configuration_items.get",
@@ -53205,7 +53205,7 @@
53205
53205
  },
53206
53206
  "examples": [
53207
53207
  "await client.contacts.create(1001, { firstName: 'Jane', lastName: 'Doe', companyID: 1001, isActive: 1 }, { dryRun: true })",
53208
- "this zone validated required set: firstName, lastName, companyID, isActive — isActive is a NUMBER (1/0) in this zone, not a boolean (a JSON boolean 500s at the vendor parse layer). The create is parent-scoped (the company id rides the scoped path + the body)."
53208
+ "validated required set: firstName, lastName, companyID, isActive — isActive is a NUMBER (1/0), not a boolean (a JSON boolean 500s at the vendor parse layer). The create is parent-scoped (the company id rides the scoped path + the body)."
53209
53209
  ],
53210
53210
  "permissions": "unknown",
53211
53211
  "pagination": {
@@ -53220,7 +53220,7 @@
53220
53220
  },
53221
53221
  "metadata": {
53222
53222
  "purpose": "Create a contact. (under a company)",
53223
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. Live-required: firstName, lastName, companyID, isActive — isActive is a NUMBER (1), not a boolean, in this zone; the spec declares no required fields.",
53223
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. Live-required: firstName, lastName, companyID, isActive — isActive is a NUMBER (1), not a boolean; the spec declares no required fields.",
53224
53224
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
53225
53225
  "related": [
53226
53226
  "contacts.update"
@@ -54424,7 +54424,7 @@
54424
54424
  },
54425
54425
  "metadata": {
54426
54426
  "purpose": "Update a contact. (under a company)",
54427
- "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. isActive is a NUMBER (1/0) in this zone — a JSON boolean 500s at the vendor parse layer (ContactModel; LocationModel takes a boolean).",
54427
+ "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. isActive is a NUMBER (1/0) — a JSON boolean 500s at the vendor parse layer (ContactModel; LocationModel takes a boolean).",
54428
54428
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
54429
54429
  "related": [
54430
54430
  "contacts.get"
@@ -69299,7 +69299,7 @@
69299
69299
  },
69300
69300
  "examples": [
69301
69301
  "await client.projects.create({ projectName: 'Example', description: 'Example', companyID: 0, projectType: 2, status: 1, startDateTime: '2026-10-03T00:00:00Z', endDateTime: '2026-10-10T00:00:00Z' }, { dryRun: true })",
69302
- "this zone validated: created a project with this full proven body (companyID 0 = tenant-global; project 8002 was a sample record, never-mutated fixture reference). Per-field minimality was not isolated live — keep the full shape."
69302
+ "validated: created a project with this full proven body (companyID 0 = tenant-global; project 8002 was a sample record, never-mutated fixture reference). Per-field minimality was not isolated live — keep the full shape."
69303
69303
  ],
69304
69304
  "permissions": "unknown",
69305
69305
  "pagination": {
@@ -73592,7 +73592,7 @@
73592
73592
  },
73593
73593
  "examples": [
73594
73594
  "await client.tasks.create(8001, { title: 'Example', projectID: 8001, taskType: 1, status: 1 }, { dryRun: true })",
73595
- "this zone verified: created task 7003 with this body under project 8001 (the DEL-GAP fixture — FK/read only, never mutated). projectID is REQUIRED IN THE BODY (the scoped parent path carries the parent too); taskType is an integer picklist (1/2); a missing required field 500s with a typed field-level error."
73595
+ "verified: created task 7003 with this body under project 8001 (the DEL-GAP fixture — FK/read only, never mutated). projectID is REQUIRED IN THE BODY (the scoped parent path carries the parent too); taskType is an integer picklist (1/2); a missing required field 500s with a typed field-level error."
73596
73596
  ],
73597
73597
  "permissions": "unknown",
73598
73598
  "pagination": {
@@ -77359,7 +77359,7 @@
77359
77359
  },
77360
77360
  "metadata": {
77361
77361
  "purpose": "Update a ticket charge.",
77362
- "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. ticketID does NOT persist on update (success returned, old ticketID kept; probed live on this zone). To re-parent use ticket_charges.moveToTicket (create, verify, delete).",
77362
+ "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. ticketID does NOT persist on update (success returned, old ticketID kept; probed live, 2026-10-21). To re-parent use ticket_charges.moveToTicket (create, verify, delete).",
77363
77363
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change. Not for ticketID: use ticket_charges.moveToTicket.",
77364
77364
  "related": [
77365
77365
  "ticket_charges.get"
@@ -78412,8 +78412,8 @@
78412
78412
  "drops": []
78413
78413
  },
78414
78414
  "examples": [
78415
- "await client.ticketNotes.create(7001, { description: 'Example', noteType: 1, publish: 1 }, { dryRun: true })",
78416
- "this zone validated: created a note under ticket 7001 with this body. publish is an INTEGER picklist (1/2/4), NOT a boolean (a JSON boolean 500s); noteType is an integer; ticketID is NOT in the body (the scoped parent path supplies it); title is optional."
78415
+ "await client.ticketNotes.create(7001, { description: 'Example', noteType: 1, publish: 1, title: 'Example' }, { dryRun: true })",
78416
+ "validated: a title-less note was created under ticket 7001; with a title the create succeeds and without one the vendor refuses (body verbatim: \"Missing Required Field: title.\"); publish is an INTEGER picklist (1/2/4), NOT a boolean (a JSON boolean 500s); noteType is an integer; ticketID is NOT in the body (the scoped parent path supplies it)."
78417
78417
  ],
78418
78418
  "permissions": "unknown",
78419
78419
  "pagination": {
@@ -78428,7 +78428,7 @@
78428
78428
  },
78429
78429
  "metadata": {
78430
78430
  "purpose": "Create a ticket note.",
78431
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. publish is an integer picklist (1/2/4) and noteType is an integer — both INT, a JSON boolean 500s at the vendor parse layer. Live-required: description, noteType, publish; ticketID is NOT in the body (the scoped parent path supplies it); title is optional. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
78431
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. publish is an integer picklist (1/2/4) and noteType is an integer — both INT, a JSON boolean 500s at the vendor parse layer. Live-required: description, noteType, publish, title; ticketID is NOT in the body (the scoped parent path supplies it). A title-less create is refused by the vendor (\"Missing Required Field: title.\"); a create with title succeeded. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
78432
78432
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
78433
78433
  "related": [
78434
78434
  "ticket_notes.update"
@@ -78888,7 +78888,7 @@
78888
78888
  },
78889
78889
  "metadata": {
78890
78890
  "purpose": "Update a ticket note.",
78891
- "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. Setting ticketID in the body MOVES the note: the parent-scoped update (oldTicketID, noteId, { ticketID: newTicketID }) persists (probed live on this zone). There is no unscoped route (404) and notes cannot be deleted (405), so a note is never moved by create-then-delete. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
78891
+ "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. Setting ticketID in the body MOVES the note: the parent-scoped update (oldTicketID, noteId, { ticketID: newTicketID }) persists (probed live, 2026-10-21). There is no unscoped route (404) and notes cannot be deleted (405), so a note is never moved by create-then-delete. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
78892
78892
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
78893
78893
  "related": [
78894
78894
  "ticket_notes.get"
@@ -80169,7 +80169,7 @@
80169
80169
  },
80170
80170
  "examples": [
80171
80171
  "await client.tickets.changeStatus(7002, 14, {}, { dryRun: true })",
80172
- "this zone: args (ticket id, targetStatus from the tenant's LIVE status picklist (the entity metadata is the oracle; the values + labels are discoverable with operations.fieldCatalog({ resources: [tickets], fields: [status], labels: true })), optional caller fields, opts). The node validates the status pre-request against the live picklist (the vendor's own validation decides when the metadata is unavailable), merges the current record (one GET) and fills the proven-safe defaults for the fields the target status requires that the record lacks (the per-status map is live-discovered vendor state). current === target → typed NO_CHANGE (zero mutating wire). 7002 = a sample ticket (verified present); dry-run shown — apply mutates the ticket."
80172
+ "args (ticket id, targetStatus from the tenant's LIVE status picklist (the entity metadata is the oracle; the values + labels are discoverable with operations.fieldCatalog({ resources: [tickets], fields: [status], labels: true })), optional caller fields, opts). The node validates the status pre-request against the live picklist (the vendor's own validation decides when the metadata is unavailable), merges the current record (one GET) and fills the proven-safe defaults for the fields the target status requires that the record lacks (the per-status map is live-discovered vendor state). current === target → typed NO_CHANGE (zero mutating wire). 7002 = a sample ticket (verified present); dry-run shown — apply mutates the ticket."
80173
80173
  ],
80174
80174
  "permissions": "unknown",
80175
80175
  "pagination": {
@@ -80277,7 +80277,7 @@
80277
80277
  },
80278
80278
  "metadata": {
80279
80279
  "purpose": "Count ticket records matching a JSON filter.",
80280
- "usage": "Unwraps queryCount; returns a plain number. Zone quirk: count/query return 0/empty on this surface (0 before AND after a proven live create) — verify presence with get(id), not count.",
80280
+ "usage": "Unwraps queryCount; returns a plain number. Vendor quirk: count/query return 0/empty on this surface (0 before AND after a proven live create) — verify presence with get(id), not count.",
80281
80281
  "preferredWhen": null,
80282
80282
  "related": [
80283
80283
  "tickets.query"
@@ -80348,7 +80348,7 @@
80348
80348
  },
80349
80349
  "examples": [
80350
80350
  "await client.tickets.create({ title: 'Example', status: 1, priority: 3, companyID: 1001, queueID: 3001 }, { dryRun: true })",
80351
- "this zone validated: created a ticket with exactly this field set (companyID anonymized to the fixture company 1001). A body missing any of title/status/priority/companyID/queueID 500s with a typed field-level error."
80351
+ "validated: created a ticket with exactly this field set (companyID anonymized to the fixture company 1001). A body missing any of title/status/priority/companyID/queueID 500s with a typed field-level error."
80352
80352
  ],
80353
80353
  "permissions": "unknown",
80354
80354
  "pagination": {
@@ -80705,7 +80705,7 @@
80705
80705
  },
80706
80706
  "examples": [
80707
80707
  "await client.tickets.fullContext(7002)",
80708
- "this zone validated: a run served 7002 in 5 wire (ticket + company part + 3 scoped queries; the dangling FK parts were 'absent'; 5 notes; long text capped at the default textLimit and flagged). args: (ticket id, optional { noteLimit (default 50), timeEntryLimit (default 50), includeAttachments (default true — metadata only: ids + names), includeHistories (default false), textLimit (default 500) }). Wire: 8 bounded reads (10 with histories). A missing/dangling FK part is null + 'absent' — a part miss never fails the op; the ticket itself missing → NOT_FOUND."
80708
+ "validated: a run served 7002 in 5 wire (ticket + company part + 3 scoped queries; the dangling FK parts were 'absent'; 5 notes; long text capped at the default textLimit and flagged). args: (ticket id, optional { noteLimit (default 50), timeEntryLimit (default 50), includeAttachments (default true — metadata only: ids + names), includeHistories (default false), textLimit (default 500) }). Wire: 8 bounded reads (10 with histories). A missing/dangling FK part is null + 'absent' — a part miss never fails the op; the ticket itself missing → NOT_FOUND."
80709
80709
  ],
80710
80710
  "permissions": "unknown",
80711
80711
  "pagination": {
@@ -81385,7 +81385,7 @@
81385
81385
  },
81386
81386
  "metadata": {
81387
81387
  "purpose": "Query Ticket records with a JSON filter.",
81388
- "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Zone quirk: count/query return 0/empty on this surface (0 before AND after a proven live create) — verify presence with get(id), not count. Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
81388
+ "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Vendor quirk: count/query return 0/empty on this surface (0 before AND after a proven live create) — verify presence with get(id), not count. Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
81389
81389
  "preferredWhen": "Default for filtered reads (the bounded query op). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. Prefer an includeFields subset over the full model (field names via operations.fieldCatalog). latest: N is the latest-N rows (id-descending) when the newest rows are the goal (the vendor has no sort — count-anchored, docs/API.md §4). Prefer a hand-listed includeFields for common narrow reads (removed the closed fieldsPreset presets — the v1 billing_join field list for billing_items.query, if you need it, is: companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable); noteChars: N caps the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose) to N chars each with the explicit … [+N chars truncated] marker (opt-in; the raw result when absent).",
81390
81390
  "related": [
81391
81391
  "tickets.resolve"
@@ -82134,8 +82134,8 @@
82134
82134
  ]
82135
82135
  },
82136
82136
  "operations": {
82137
- "planHash": "c92aaa7dd21259e4e8b545e44cebf4d831e5f68a0c9e41e26af1c2966c84bdef",
82138
- "builtAt": "2026-11-12T01:38:06.866Z",
82137
+ "planHash": "546e9de78d62f2c30190c1bb82f89be73f9cc0a75d633d771956566c78f4efeb",
82138
+ "builtAt": "2026-11-17T02:57:12.896Z",
82139
82139
  "records": [
82140
82140
  {
82141
82141
  "id": "operations.aggregate",
@@ -82375,7 +82375,7 @@
82375
82375
  "operations.relationshipMap",
82376
82376
  "autotask_catalog"
82377
82377
  ],
82378
- "args": "args[0] is the optional opts object: { resources?: string[] (plan keys), kind?: CreateBlockerKind }. Zero wire — the answer is the served, drift-guarded campaign artifact (92 create entities, zone-labelled). Unknown resource → typed RESOURCE_UNKNOWN (count + autotask_catalog pointer); unknown kind → typed CONFIG_ERROR naming the valid kinds."
82378
+ "args": "args[0] is the optional opts object: { resources?: string[] (plan keys), kind?: CreateBlockerKind }. Zero wire — the answer is the served, drift-guarded campaign artifact (92 create entities). Unknown resource → typed RESOURCE_UNKNOWN (count + autotask_catalog pointer); unknown kind → typed CONFIG_ERROR naming the valid kinds."
82379
82379
  },
82380
82380
  "compact": "CreateGuidanceReport",
82381
82381
  "status": "tested"
@@ -82909,7 +82909,7 @@
82909
82909
  },
82910
82910
  "examples": [
82911
82911
  "await invoke(client, 'operations.relationshipMap', ['tickets'])",
82912
- "this zone validated: a run served the tickets entry ZERO wire (its 10 scoped children with scoped-op flags + the unowned-blind stamps). args (invoke form): the plan resource key string. Returns { resource, apiEntity, tier, parent, children [{ resource, parentField, scopedOps { create, query, update, delete }, specialOps }], naturalKeys, blindSurfaces, zoneFacts }. 'What can I attach to a ticket?' → children; 'what does creating a ticket note require?' → relationshipMap('ticket_notes').zoneFacts.createRequiredSet = [description, noteType, publish]. Unknown key → typed RESOURCE_UNKNOWN (carries the resource count + a pointer to autotask_catalog). ZERO vendor wire by construction — the data is the served registry artifact."
82912
+ "validated: a run served the tickets entry ZERO wire (its 10 scoped children with scoped-op flags + the unowned-blind stamps). args (invoke form): the plan resource key string. Returns { resource, apiEntity, tier, parent, children [{ resource, parentField, scopedOps { create, query, update, delete }, specialOps }], naturalKeys, blindSurfaces, zoneFacts }. 'What can I attach to a ticket?' → children; 'what does creating a ticket note require?' → relationshipMap('ticket_notes').zoneFacts.createRequiredSet = [description, noteType, publish, title]. Unknown key → typed RESOURCE_UNKNOWN (carries the resource count + a pointer to autotask_catalog). ZERO vendor wire by construction — the data is the served registry artifact."
82913
82913
  ],
82914
82914
  "permissions": "unknown",
82915
82915
  "pagination": {
@@ -82924,8 +82924,8 @@
82924
82924
  },
82925
82925
  "metadata": {
82926
82926
  "purpose": "Describe one resource's full relationship surface in a single ZERO-wire call: its parent, its children (with the scoped-op presence per child), its natural lookup keys, its pinned blind surfaces, and the zone-verified create required sets + quirks.",
82927
- "usage": "args[0] is the plan resource key (string, e.g. 'tickets'). Returns { resource, apiEntity, tier, workflowResource, parent, children: [{ resource, apiEntity, parentField, parentSegment, scopedOps: { create, query, update, delete }, specialOps, searchCovers }], naturalKeys: { hasSearch, searchCovers, findBy }, blindSurfaces, zoneFacts }. 'What can I attach to a ticket?' → children of 'tickets' (the 10 scoped child resources with their scoped-op flags); 'what does creating a ticket note require?' → relationshipMap('ticket_notes').zoneFacts.createRequiredSet = [description, noteType, publish]. Unknown key → typed RESOURCE_UNKNOWN (carries the resource count + a pointer to autotask_catalog — never a 128-key dump). ZERO vendor wire: the data is the plan-pinned registry artifact (the zone facts are the verified set — the zone label travels with them).",
82928
- "preferredWhen": "The first call when planning any multi-step composition (what exists under this resource, what a create requires, which surfaces are blind in this zone) — zero wire, so it is free to consult before every plan. For a live record, use the resource's read ops.",
82927
+ "usage": "args[0] is the plan resource key (string, e.g. 'tickets'). Returns { resource, apiEntity, tier, workflowResource, parent, children: [{ resource, apiEntity, parentField, parentSegment, scopedOps: { create, query, update, delete }, specialOps, searchCovers }], naturalKeys: { hasSearch, searchCovers, findBy }, blindSurfaces, zoneFacts }. 'What can I attach to a ticket?' → children of 'tickets' (the 10 scoped child resources with their scoped-op flags); 'what does creating a ticket note require?' → relationshipMap('ticket_notes').zoneFacts.createRequiredSet = [description, noteType, publish, title]. Unknown key → typed RESOURCE_UNKNOWN (carries the resource count + a pointer to autotask_catalog — never a 128-key dump). ZERO vendor wire: the data is the plan-pinned registry artifact (the zone facts are the verified set — the zone label travels with them).",
82928
+ "preferredWhen": "The first call when planning any multi-step composition (what exists under this resource, what a create requires, which surfaces are blind) — zero wire, so it is free to consult before every plan. For a live record, use the resource's read ops.",
82929
82929
  "related": [
82930
82930
  "operations.resolveAny",
82931
82931
  "autotask_catalog"