node-autotask 0.38.0 → 0.39.0

package/dist/resources/index.js

@@ -126,7 +126,7 @@ import {
   VersionInformationResource,
   VersionResource,
   ZoneInformationResource
-} from "../chunk-KPYXO7F5.js";
+} from "../chunk-LD5UPSDB.js";
 import {
   BillingCodesResource,
   BillingItemsResource,
@@ -138,8 +138,8 @@ import {
   OrganizationalLevelAssociationsResource,
   ResourcesResource,
   TimeEntriesResource
-} from "../chunk-4QHGCYEI.js";
-import "../chunk-U3K6IDKB.js";
+} from "../chunk-FV5PJLIZ.js";
+import "../chunk-2KQS3RHQ.js";
 import "../chunk-5VHSLJMR.js";
 export {
   AppointmentsResource,

package/docs/API.md

@@ -2721,15 +2721,19 @@ metadata is (the `autotask_describe` channel, `capabilities.json`,
 `node-autotask/capabilities`). One row shape over a CLOSED kind set:
 
 ```ts
-{ kind: 'not-persisted'; fields?: string[]; note: string; remedyOp?: string }
+{ kind: 'not-persisted' | 'field-semantics'; fields?: string[]; note: string; remedyOp?: string }
 ```
 
 - `not-persisted`: the op accepts the listed `fields` but the vendor does not
   store them. `fields` is required for this kind; `remedyOp` names the plan
   operation that does what this one cannot.
+- `field-semantics` (issue #282): the listed `fields` have meanings a caller
+  must not conflate; `note` states them in a sentence a server can quote.
+  `fields` is required for this kind too.
 - First rows: `time_entries.update` and `ticket_charges.update` declare
   `{ kind: 'not-persisted', fields: ['ticketID'], remedyOp:
-  '<resource>.moveToTicket' }`.
+  '<resource>.moveToTicket' }`; `time_entries.query` and `time_entries.get`
+  declare `{ kind: 'field-semantics', fields: ['hoursWorked', 'hoursToBill'] }`.
 - The kind set is closed at build time: `scripts/generate-capabilities.mjs`
   throws on an unknown kind or a malformed row, and gate clause 22 also checks
   that every named field exists on the resource model and every `remedyOp` is
@@ -2910,7 +2914,7 @@ record write says nothing about the field catalog and never invalidates;
 the TTL is the other expiry path.
 
 **The on-demand op:** `operations.fieldCatalog(client, opts?)`
-(`{ resources?, include?, fields?, labels?, fresh? }` — `fields` filters the
+(`{ resources?, include?, fields?, labels?, fresh?, compact?, maxBytes? }` — `fields` filters the
 fields-kind rows to the named fields and reports `unmatchedFields`; a
 projected row is marked `projected: true` (issue #121 — the four derived
 lists then describe the PROJECTED set only, so a consumer can never read a
@@ -2930,6 +2934,22 @@ the field catalog; the seven integration singletons are refused typed —
 a known key without a catalog → `CONFIG_ERROR`, an unknown key → typed
 `RESOURCE_UNKNOWN` carrying the count + the `autotask_catalog` pointer).
 
+**Compact rows and the size cap (issue #282).** Measured live from the SDK,
+a `tickets` result is ~20 KB full, ~137 KB full with `labels: true` and
+~11 KB with `compact: true` (`time_entries`: ~9 / ~11 / ~5 KB).
+`compact: true` serves each field row as `{ name, type, isPickList,
+isReference, udf }` (picklist values only with `labels: true` AND a `fields`
+filter; the row name lists stay). `maxBytes` (integer >= 4096) caps the UTF-8
+JSON size: over it, field rows are dropped from the end (udf rows, then
+fields rows, last resource first; the name lists only when the field rows
+alone cannot fit) and the result carries `truncated: true` and
+`truncation: { reason: 'maxBytes', maxBytes, fullBytes, omitted: [{ resource,
+kind, count }], note }`, so it is always valid JSON and never over the cap (a
+result whose envelope alone cannot fit, e.g. many resources under a small cap,
+is refused with `CONFIG_ERROR`). Both default off (the
+full rows, no cap); a model-facing server should pass `compact: true` and a
+`maxBytes`.
+
 **Reference targets (issue #219 N1).** Every projected field row carries
 `targetResource: string | null` and `targetEnumerable: boolean`: the plan
 resource key the vendor `referenceEntityType` names, and whether that
@@ -4096,11 +4116,16 @@ keys of `operations.aggregate`, and the found records of `operations.fetchMany`
   values stay raw (picklists are outside the untrusted class by the registry
   rule). Example: `contractIDName: "<untrusted_content>Managed Services 2026</untrusted_content>"`.
 - `assignedResourceName` is also written (same value as `assignedResourceIDName`):
-  a **deprecated alias** kept for one minor release (removed in 0.39.0).
+  a **deprecated alias**, still written in 0.39.0 (null with it, issue #282);
+  its removal is deferred to a later minor.
 - Aggregate: `groups[].key.ticketIDName`, `groups[].key.statusLabel`, … (only the
   returned `top` groups are labelled).
-- An absent, `null` or `0` value gets no sibling. An unknown id (the vendor's
-  not-found) gets `null`, never an error.
+- A labelled field that is present in the row always gets its sibling (issue
+  #282): a `null` or `0` value, an unknown id (the vendor's not-found) or a
+  capped id gets `null`, never a missing key and never an error. Only a field
+  absent from the row gets no sibling. Example: `{ contractID: null,
+  contractIDName: null, assignedResourceID: null, assignedResourceIDName: null,
+  assignedResourceName: null, status: null, statusLabel: null }`.
 - Opt out per call: `names: false` (query bag key, aggregate opts, fetchMany /
   fetchByIds opts). A non-boolean `names` is refused pre-request.
 - Caches: picklists ride the fieldCache, staff names the resource name cache,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime dependencies. Built for building MCP servers and integrations.",
   "type": "module",
   "sideEffects": false,