node-autotask 0.37.1 → 0.39.0

package/dist/operations/index.d.cts

@@ -1,7 +1,7 @@
-import { a as AutotaskClient, eF as BlindSurfaceInfo, eG as RelationshipResource, eH as BlindSurfaceInventory, eI as BlindSurfaceRow, eJ as CreateGuidanceValueRequirement, eK as CreateGuidanceRow, eL as CreateBlockerKind, eM as CreateGuidanceReport, Z as ZoneName, eN as FieldCacheKind, k as AutotaskConfigError } from '../index-CqepIQfp.cjs';
-export { eO as FIELD_CACHE_KINDS } from '../index-CqepIQfp.cjs';
-import { I as Identifier, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-m-7fOwFl.cjs';
-export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-m-7fOwFl.cjs';
+import { a as AutotaskClient, eF as BlindSurfaceInfo, eG as RelationshipResource, eH as BlindSurfaceInventory, eI as BlindSurfaceRow, eJ as CreateGuidanceValueRequirement, eK as CreateGuidanceRow, eL as CreateBlockerKind, eM as CreateGuidanceReport, Z as ZoneName, eN as FieldCacheKind, k as AutotaskConfigError } from '../index-BVOOHPvr.cjs';
+export { eO as FIELD_CACHE_KINDS } from '../index-BVOOHPvr.cjs';
+import { I as Identifier, hV as RowNamesSummary, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-BQVStxwi.cjs';
+export { hW as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-BQVStxwi.cjs';
 import { CapabilityRecord } from '../capabilities.cjs';
 
 /**
@@ -76,6 +76,8 @@ interface FetchManyResult {
     ok: number;
     /** Items that missed or faulted (typed per item). */
     failed: number;
+    /** Issue #276: present only when some labels are missing (cold-read cap hit / picklist unavailable). */
+    names?: RowNamesSummary;
 }
 interface ResolveAnyOptions {
     /** Resource keys to resolve against (default: the five workflow resources). */
@@ -171,6 +173,8 @@ interface FetchManyOptions {
      * bit-for-bit (zero metadata wire).
      */
     liveFields?: boolean;
+    /** Issue #276: label siblings on the found records (`statusLabel`, `contractIDName`, …). Default true; false = raw records. */
+    names?: boolean;
 }
 interface ValidateFetchManyValidation {
     /**
@@ -243,6 +247,8 @@ interface AggregateOptions {
     top?: number;
     /** The total-record cap for the walk modes (default = max = the house 2500 — `queryBounded`'s hard limit). */
     limit?: number;
+    /** Issue #276: label siblings on the returned group keys (`key.ticketIDName`, `key.statusLabel`, …). Default true; false = raw ids. */
+    names?: boolean;
 }
 /** One folded group (the key = the groupBy field tuple; `sums` present iff `sum` was given). */
 interface AggregateGroup {
@@ -271,6 +277,10 @@ interface AggregateResult {
     blindSurface?: BlindSurfaceInfo;
     /** The typed empty-reason stamp (the base's 0-row/0-count channel, when attached). */
     emptyReason?: EmptyReasonInfo;
+    /** Issue #275: a relation filter matched no parent record (group/sum mode; the walk was not issued). */
+    relationNote?: string;
+    /** Issue #276: present only when some group-key labels are missing (cold-read cap hit / picklist unavailable). */
+    names?: RowNamesSummary;
 }
 /**
  * `operations.aggregate` — fold any query surface into groups/sums in one
@@ -434,6 +444,8 @@ declare const FETCH_BY_IDS_CHUNK_SIZE = 250;
 interface FetchByIdsOptions {
     /** May LOWER the {@link FETCH_BY_IDS_MAX_ITEMS} cap (integer >= 1) — never raise it. */
     maxItems?: number;
+    /** Issue #276: label siblings on the found records (`statusLabel`, `contractIDName`, …). Default true; false = raw records. */
+    names?: boolean;
 }
 /**
  * Fetch up to 500 single records by vendor numeric id across mixed
@@ -813,6 +825,20 @@ interface FieldCatalogFieldRow {
     /** The vendor's exposed picklist VALUES, verbatim (present exactly when the `labels` opt is `true` and the vendor exposed values for this picklist field — the vendor-walled and non-picklist rows carry none). */
     picklistValues?: PickListValue[];
 }
+/** One compact field row (`compact: true`, issue #282): the five columns a
+ * caller needs to pick a field name — the full row's flags, lengths and
+ * reference targets are dropped. `picklistValues` rides only when `labels`
+ * AND a `fields` filter are both given (a targeted value lookup). */
+interface FieldCatalogCompactFieldRow {
+    name: string;
+    type: string;
+    isPickList: boolean;
+    /** True when the vendor names a referenced entity (`referenceEntityType` non-empty). */
+    isReference: boolean;
+    /** True on a `udf`-kind row, false on a standard field. */
+    udf: boolean;
+    picklistValues?: PickListValue[];
+}
 /** The derivation rule of one field (issue #219 N8) — a closed plan token, served without the field name it decorates. */
 interface DerivationRule {
     /** elapsed(<start>,<end>) (recomputed from those timestamps) | parent (inherited from the parent record) | mirror(<field>) (the vendor copies that field) | external (written by another entity's op — writableRoute names it). */
@@ -830,8 +856,8 @@ interface FieldCatalogRowError {
     code: string;
     message: string;
 }
-/** One resource's catalog row. */
-interface FieldCatalogRow {
+/** One resource's catalog row (`F` = the field-row shape: the full row by default, FieldCatalogCompactFieldRow under `compact: true`). */
+interface FieldCatalogRow<F = FieldCatalogFieldRow> {
     /** The plan resource key. */
     resource: string;
     /** The vendor entity name (the path segment; plan-derived). */
@@ -847,11 +873,11 @@ interface FieldCatalogRow {
     /** The plan's derived-field declaration for this resource (issue #219 N8) — present exactly when the plan declares any, in plan order; the same list the create guidance row and the describe channel serve. Read it before treating a submitted field value as authoritative. */
     derivedFields?: FieldDerivation[];
     /** The projected standard-field catalog (present exactly when `fields` was included and fetched; when the `fields` opt is given, only the matching rows — the requested names absent here land in `unmatchedFields`). */
-    fields?: FieldCatalogFieldRow[];
+    fields?: F[];
     /** The requested `fields`-filter names absent from this resource's fields catalog (in request order); `[]` when no filter is given, when the row carries no fields catalog (an `info`/`udf`-only include or a row error), or when nothing was missing. Reported, never an error. */
     unmatchedFields: string[];
     /** The projected UDF catalog (present exactly when `udf` was included and fetched). */
-    udf?: FieldCatalogFieldRow[] | null;
+    udf?: F[] | null;
     /** Present exactly when a `fields` projection was applied (the `fields` opt was given): the four derived lists below then describe the PROJECTED set only. A full row omits the key (it never carries `false`). */
     projected?: true;
     /** `isRequired === true` names, in catalog order (the `fields` catalog). */
@@ -873,7 +899,7 @@ interface FieldCatalogRow {
     error: FieldCatalogRowError | null;
 }
 /** The sweep result. */
-interface FieldCatalogResult {
+interface FieldCatalogResult<F = FieldCatalogFieldRow> {
     /** The resolved client zone ('unknown' for a bare explicit baseUrl). */
     zone: string;
     /** The zone label (a live op has no plan-pinned tenant label — it mirrors `zone`). */
@@ -887,13 +913,17 @@ interface FieldCatalogResult {
     /** The call instant (ISO). */
     fetchedAt: string;
     /** One row per requested resource, in request order. */
-    rows: FieldCatalogRow[];
+    rows: FieldCatalogRow<F>[];
     /** The metadata reads actually issued across the call (≤ `cap` by construction). */
     wireUsed: number;
     /** The wire cap the call ran under. */
     cap: number;
-    /** Always false: over-cap requests REFUSE (CONFIG_ERROR) — they are never silently truncated. */
-    truncated: false;
+    /** The resolved `compact` opt (true = the field rows are FieldCatalogCompactFieldRow). */
+    compact: boolean;
+    /** True only when the `maxBytes` size cap dropped field rows (see `truncation`). Over the WIRE cap the call is still refused (CONFIG_ERROR), never truncated. */
+    truncated: boolean;
+    /** Present exactly when `truncated`: the typed note naming what the `maxBytes` cap dropped (issue #282) — the payload stays valid JSON, never cut mid-document. */
+    truncation?: FieldCatalogTruncation;
     counts: {
         /** The requested (deduplicated) resource count. */
         resources: number;
@@ -911,6 +941,23 @@ interface FieldCatalogResult {
         note: string;
     };
 }
+/** The typed size-cap note (issue #282). */
+interface FieldCatalogTruncation {
+    reason: 'maxBytes';
+    /** The cap the call ran under (UTF-8 bytes of the JSON result). */
+    maxBytes: number;
+    /** The UTF-8 byte size of the untruncated JSON result. */
+    fullBytes: number;
+    /** The entries dropped, per resource and list (taken from the end: the udf rows, then the fields rows, last resource first; the name lists only when the field rows alone could not fit). */
+    omitted: Array<{
+        resource: string;
+        kind: FieldCatalogTrimKind;
+        count: number;
+    }>;
+    note: string;
+}
+/** The smallest accepted `maxBytes` (a cap below it could not hold a one-resource result envelope; a larger envelope that still cannot fit is refused at result-build). */
+declare const MIN_FIELD_CATALOG_MAX_BYTES = 4096;
 /** The optional call bag for `operations.fieldCatalog` (closed: unknown keys refuse). */
 interface FieldCatalogOptions {
     /** The plan resource keys to read. Omitted → the five workflow resources (never the full set — an on-demand op must not fan out 121 wire calls by default). */
@@ -923,7 +970,15 @@ interface FieldCatalogOptions {
     fields?: string[];
     /** Opt-in: when `true`, the projected `fields`-kind and `udf`-kind picklist rows carry the vendor's exposed `picklistValues` (the raw vendor shape as-is — `{ value, label, parentValue?, isActive?, ... }`, `value` a string, zero transform) for the picklist fields. The W-A4 wall still applies (a value the vendor does not expose to this API user is not resolvable — retrying will not surface it). Default `false`: the rows carry no VALUES (today's exact output). Zero extra wire: the values ride the same cached raw rows. */
     labels?: boolean;
+    /** Issue #282: when `true`, every field row is a FieldCatalogCompactFieldRow `{ name, type, isPickList, isReference, udf }` (a live tickets result: ~11 KB compact against ~20 KB full and ~137 KB full with `labels: true`). `picklistValues` ride a compact row only with `labels: true` AND a `fields` filter. Default `false` (the full rows). */
+    compact?: boolean;
+    /** Issue #282: a UTF-8 byte cap on the JSON result (integer ≥ MIN_FIELD_CATALOG_MAX_BYTES). Over it, field rows are dropped from the end until the result fits, `truncated` is `true` and `truncation` names what was dropped — never an invalid, cut-off document. The row-level name lists (required, readOnly, queryable, picklistFields) keep every name unless the field rows alone cannot fit (then they are trimmed too). A served result never exceeds the cap: when the envelope alone (it grows with the resource count) cannot fit, the call is refused with CONFIG_ERROR. The cost is linear in the result size. Default: no cap. */
+    maxBytes?: number;
 }
+/** The lists the size cap trims, in drop order within a row: the field rows
+ * first, then the name lists (only when the field rows alone cannot fit). */
+declare const TRIM_KINDS: readonly ["udf", "fields", "picklistFields", "queryable", "readOnly", "required"];
+type FieldCatalogTrimKind = (typeof TRIM_KINDS)[number];
 /**
  * Run the bounded live field-metadata sweep.
  *
@@ -934,9 +989,15 @@ interface FieldCatalogOptions {
  * ```
  *
  * @param client The wired client (the reads issue entityInformation GETs).
- * @param opts   The call bag ({ resources?, include?, fresh?, fields?, labels? }).
+ * @param opts   The call bag ({ resources?, include?, fresh?, fields?, labels?, compact?, maxBytes? }).
  */
-declare function fieldCatalog(client: AutotaskClient, opts?: FieldCatalogOptions): Promise<FieldCatalogResult>;
+declare function fieldCatalog(client: AutotaskClient, opts: FieldCatalogOptions & {
+    compact: true;
+}): Promise<FieldCatalogResult<FieldCatalogCompactFieldRow>>;
+declare function fieldCatalog(client: AutotaskClient, opts?: FieldCatalogOptions & {
+    compact?: false;
+}): Promise<FieldCatalogResult>;
+declare function fieldCatalog(client: AutotaskClient, opts?: FieldCatalogOptions): Promise<FieldCatalogResult<FieldCatalogFieldRow | FieldCatalogCompactFieldRow>>;
 
 /** The pinned per-call id cap (mirrors `FETCH_BY_IDS_MAX_ITEMS` — the house bulk cap; over → pre-request refusal, zero wire). */
 declare const EXPAND_RESOURCE_NAMES_MAX_IDS = 500;
@@ -1221,4 +1282,4 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[] | Record<string, unknown>, opts?: InvokeOptions): Promise<unknown>;
 
-export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, type DerivationRule, ENTITY_TYPE_TO_RESOURCE, EXPAND_RESOURCE_NAMES_MAX_IDS, type EffectiveRequiredFields, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type RequiredFieldsRecord, type RequiredFieldsSource, type RequiredFieldsZoneFacts, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type RevenueRollupAmount, type RevenueRollupDimension, type RevenueRollupKey, type RevenueRollupNonChargeable, type RevenueRollupNonChargeableAmount, type RevenueRollupOptions, type RevenueRollupResult, type RevenueRollupRow, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, type ServedCreateGuidanceReport, type ServedCreateGuidanceRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, revenueRollup, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, type DerivationRule, ENTITY_TYPE_TO_RESOURCE, EXPAND_RESOURCE_NAMES_MAX_IDS, type EffectiveRequiredFields, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogCompactFieldRow, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldCatalogTrimKind, type FieldCatalogTruncation, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, MIN_FIELD_CATALOG_MAX_BYTES, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type RequiredFieldsRecord, type RequiredFieldsSource, type RequiredFieldsZoneFacts, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type RevenueRollupAmount, type RevenueRollupDimension, type RevenueRollupKey, type RevenueRollupNonChargeable, type RevenueRollupNonChargeableAmount, type RevenueRollupOptions, type RevenueRollupResult, type RevenueRollupRow, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, type ServedCreateGuidanceReport, type ServedCreateGuidanceRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, revenueRollup, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };

package/dist/operations/index.d.ts

@@ -1,7 +1,7 @@
-import { a as AutotaskClient, eF as BlindSurfaceInfo, eG as RelationshipResource, eH as BlindSurfaceInventory, eI as BlindSurfaceRow, eJ as CreateGuidanceValueRequirement, eK as CreateGuidanceRow, eL as CreateBlockerKind, eM as CreateGuidanceReport, Z as ZoneName, eN as FieldCacheKind, k as AutotaskConfigError } from '../index-BDqw377y.js';
-export { eO as FIELD_CACHE_KINDS } from '../index-BDqw377y.js';
-import { I as Identifier, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-m-7fOwFl.js';
-export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-m-7fOwFl.js';
+import { a as AutotaskClient, eF as BlindSurfaceInfo, eG as RelationshipResource, eH as BlindSurfaceInventory, eI as BlindSurfaceRow, eJ as CreateGuidanceValueRequirement, eK as CreateGuidanceRow, eL as CreateBlockerKind, eM as CreateGuidanceReport, Z as ZoneName, eN as FieldCacheKind, k as AutotaskConfigError } from '../index-Bmoiwhx2.js';
+export { eO as FIELD_CACHE_KINDS } from '../index-Bmoiwhx2.js';
+import { I as Identifier, hV as RowNamesSummary, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-BQVStxwi.js';
+export { hW as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-BQVStxwi.js';
 import { CapabilityRecord } from '../capabilities.js';
 
 /**
@@ -76,6 +76,8 @@ interface FetchManyResult {
     ok: number;
     /** Items that missed or faulted (typed per item). */
     failed: number;
+    /** Issue #276: present only when some labels are missing (cold-read cap hit / picklist unavailable). */
+    names?: RowNamesSummary;
 }
 interface ResolveAnyOptions {
     /** Resource keys to resolve against (default: the five workflow resources). */
@@ -171,6 +173,8 @@ interface FetchManyOptions {
      * bit-for-bit (zero metadata wire).
      */
     liveFields?: boolean;
+    /** Issue #276: label siblings on the found records (`statusLabel`, `contractIDName`, …). Default true; false = raw records. */
+    names?: boolean;
 }
 interface ValidateFetchManyValidation {
     /**
@@ -243,6 +247,8 @@ interface AggregateOptions {
     top?: number;
     /** The total-record cap for the walk modes (default = max = the house 2500 — `queryBounded`'s hard limit). */
     limit?: number;
+    /** Issue #276: label siblings on the returned group keys (`key.ticketIDName`, `key.statusLabel`, …). Default true; false = raw ids. */
+    names?: boolean;
 }
 /** One folded group (the key = the groupBy field tuple; `sums` present iff `sum` was given). */
 interface AggregateGroup {
@@ -271,6 +277,10 @@ interface AggregateResult {
     blindSurface?: BlindSurfaceInfo;
     /** The typed empty-reason stamp (the base's 0-row/0-count channel, when attached). */
     emptyReason?: EmptyReasonInfo;
+    /** Issue #275: a relation filter matched no parent record (group/sum mode; the walk was not issued). */
+    relationNote?: string;
+    /** Issue #276: present only when some group-key labels are missing (cold-read cap hit / picklist unavailable). */
+    names?: RowNamesSummary;
 }
 /**
  * `operations.aggregate` — fold any query surface into groups/sums in one
@@ -434,6 +444,8 @@ declare const FETCH_BY_IDS_CHUNK_SIZE = 250;
 interface FetchByIdsOptions {
     /** May LOWER the {@link FETCH_BY_IDS_MAX_ITEMS} cap (integer >= 1) — never raise it. */
     maxItems?: number;
+    /** Issue #276: label siblings on the found records (`statusLabel`, `contractIDName`, …). Default true; false = raw records. */
+    names?: boolean;
 }
 /**
  * Fetch up to 500 single records by vendor numeric id across mixed
@@ -813,6 +825,20 @@ interface FieldCatalogFieldRow {
     /** The vendor's exposed picklist VALUES, verbatim (present exactly when the `labels` opt is `true` and the vendor exposed values for this picklist field — the vendor-walled and non-picklist rows carry none). */
     picklistValues?: PickListValue[];
 }
+/** One compact field row (`compact: true`, issue #282): the five columns a
+ * caller needs to pick a field name — the full row's flags, lengths and
+ * reference targets are dropped. `picklistValues` rides only when `labels`
+ * AND a `fields` filter are both given (a targeted value lookup). */
+interface FieldCatalogCompactFieldRow {
+    name: string;
+    type: string;
+    isPickList: boolean;
+    /** True when the vendor names a referenced entity (`referenceEntityType` non-empty). */
+    isReference: boolean;
+    /** True on a `udf`-kind row, false on a standard field. */
+    udf: boolean;
+    picklistValues?: PickListValue[];
+}
 /** The derivation rule of one field (issue #219 N8) — a closed plan token, served without the field name it decorates. */
 interface DerivationRule {
     /** elapsed(<start>,<end>) (recomputed from those timestamps) | parent (inherited from the parent record) | mirror(<field>) (the vendor copies that field) | external (written by another entity's op — writableRoute names it). */
@@ -830,8 +856,8 @@ interface FieldCatalogRowError {
     code: string;
     message: string;
 }
-/** One resource's catalog row. */
-interface FieldCatalogRow {
+/** One resource's catalog row (`F` = the field-row shape: the full row by default, FieldCatalogCompactFieldRow under `compact: true`). */
+interface FieldCatalogRow<F = FieldCatalogFieldRow> {
     /** The plan resource key. */
     resource: string;
     /** The vendor entity name (the path segment; plan-derived). */
@@ -847,11 +873,11 @@ interface FieldCatalogRow {
     /** The plan's derived-field declaration for this resource (issue #219 N8) — present exactly when the plan declares any, in plan order; the same list the create guidance row and the describe channel serve. Read it before treating a submitted field value as authoritative. */
     derivedFields?: FieldDerivation[];
     /** The projected standard-field catalog (present exactly when `fields` was included and fetched; when the `fields` opt is given, only the matching rows — the requested names absent here land in `unmatchedFields`). */
-    fields?: FieldCatalogFieldRow[];
+    fields?: F[];
     /** The requested `fields`-filter names absent from this resource's fields catalog (in request order); `[]` when no filter is given, when the row carries no fields catalog (an `info`/`udf`-only include or a row error), or when nothing was missing. Reported, never an error. */
     unmatchedFields: string[];
     /** The projected UDF catalog (present exactly when `udf` was included and fetched). */
-    udf?: FieldCatalogFieldRow[] | null;
+    udf?: F[] | null;
     /** Present exactly when a `fields` projection was applied (the `fields` opt was given): the four derived lists below then describe the PROJECTED set only. A full row omits the key (it never carries `false`). */
     projected?: true;
     /** `isRequired === true` names, in catalog order (the `fields` catalog). */
@@ -873,7 +899,7 @@ interface FieldCatalogRow {
     error: FieldCatalogRowError | null;
 }
 /** The sweep result. */
-interface FieldCatalogResult {
+interface FieldCatalogResult<F = FieldCatalogFieldRow> {
     /** The resolved client zone ('unknown' for a bare explicit baseUrl). */
     zone: string;
     /** The zone label (a live op has no plan-pinned tenant label — it mirrors `zone`). */
@@ -887,13 +913,17 @@ interface FieldCatalogResult {
     /** The call instant (ISO). */
     fetchedAt: string;
     /** One row per requested resource, in request order. */
-    rows: FieldCatalogRow[];
+    rows: FieldCatalogRow<F>[];
     /** The metadata reads actually issued across the call (≤ `cap` by construction). */
     wireUsed: number;
     /** The wire cap the call ran under. */
     cap: number;
-    /** Always false: over-cap requests REFUSE (CONFIG_ERROR) — they are never silently truncated. */
-    truncated: false;
+    /** The resolved `compact` opt (true = the field rows are FieldCatalogCompactFieldRow). */
+    compact: boolean;
+    /** True only when the `maxBytes` size cap dropped field rows (see `truncation`). Over the WIRE cap the call is still refused (CONFIG_ERROR), never truncated. */
+    truncated: boolean;
+    /** Present exactly when `truncated`: the typed note naming what the `maxBytes` cap dropped (issue #282) — the payload stays valid JSON, never cut mid-document. */
+    truncation?: FieldCatalogTruncation;
     counts: {
         /** The requested (deduplicated) resource count. */
         resources: number;
@@ -911,6 +941,23 @@ interface FieldCatalogResult {
         note: string;
     };
 }
+/** The typed size-cap note (issue #282). */
+interface FieldCatalogTruncation {
+    reason: 'maxBytes';
+    /** The cap the call ran under (UTF-8 bytes of the JSON result). */
+    maxBytes: number;
+    /** The UTF-8 byte size of the untruncated JSON result. */
+    fullBytes: number;
+    /** The entries dropped, per resource and list (taken from the end: the udf rows, then the fields rows, last resource first; the name lists only when the field rows alone could not fit). */
+    omitted: Array<{
+        resource: string;
+        kind: FieldCatalogTrimKind;
+        count: number;
+    }>;
+    note: string;
+}
+/** The smallest accepted `maxBytes` (a cap below it could not hold a one-resource result envelope; a larger envelope that still cannot fit is refused at result-build). */
+declare const MIN_FIELD_CATALOG_MAX_BYTES = 4096;
 /** The optional call bag for `operations.fieldCatalog` (closed: unknown keys refuse). */
 interface FieldCatalogOptions {
     /** The plan resource keys to read. Omitted → the five workflow resources (never the full set — an on-demand op must not fan out 121 wire calls by default). */
@@ -923,7 +970,15 @@ interface FieldCatalogOptions {
     fields?: string[];
     /** Opt-in: when `true`, the projected `fields`-kind and `udf`-kind picklist rows carry the vendor's exposed `picklistValues` (the raw vendor shape as-is — `{ value, label, parentValue?, isActive?, ... }`, `value` a string, zero transform) for the picklist fields. The W-A4 wall still applies (a value the vendor does not expose to this API user is not resolvable — retrying will not surface it). Default `false`: the rows carry no VALUES (today's exact output). Zero extra wire: the values ride the same cached raw rows. */
     labels?: boolean;
+    /** Issue #282: when `true`, every field row is a FieldCatalogCompactFieldRow `{ name, type, isPickList, isReference, udf }` (a live tickets result: ~11 KB compact against ~20 KB full and ~137 KB full with `labels: true`). `picklistValues` ride a compact row only with `labels: true` AND a `fields` filter. Default `false` (the full rows). */
+    compact?: boolean;
+    /** Issue #282: a UTF-8 byte cap on the JSON result (integer ≥ MIN_FIELD_CATALOG_MAX_BYTES). Over it, field rows are dropped from the end until the result fits, `truncated` is `true` and `truncation` names what was dropped — never an invalid, cut-off document. The row-level name lists (required, readOnly, queryable, picklistFields) keep every name unless the field rows alone cannot fit (then they are trimmed too). A served result never exceeds the cap: when the envelope alone (it grows with the resource count) cannot fit, the call is refused with CONFIG_ERROR. The cost is linear in the result size. Default: no cap. */
+    maxBytes?: number;
 }
+/** The lists the size cap trims, in drop order within a row: the field rows
+ * first, then the name lists (only when the field rows alone cannot fit). */
+declare const TRIM_KINDS: readonly ["udf", "fields", "picklistFields", "queryable", "readOnly", "required"];
+type FieldCatalogTrimKind = (typeof TRIM_KINDS)[number];
 /**
  * Run the bounded live field-metadata sweep.
  *
@@ -934,9 +989,15 @@ interface FieldCatalogOptions {
  * ```
  *
  * @param client The wired client (the reads issue entityInformation GETs).
- * @param opts   The call bag ({ resources?, include?, fresh?, fields?, labels? }).
+ * @param opts   The call bag ({ resources?, include?, fresh?, fields?, labels?, compact?, maxBytes? }).
  */
-declare function fieldCatalog(client: AutotaskClient, opts?: FieldCatalogOptions): Promise<FieldCatalogResult>;
+declare function fieldCatalog(client: AutotaskClient, opts: FieldCatalogOptions & {
+    compact: true;
+}): Promise<FieldCatalogResult<FieldCatalogCompactFieldRow>>;
+declare function fieldCatalog(client: AutotaskClient, opts?: FieldCatalogOptions & {
+    compact?: false;
+}): Promise<FieldCatalogResult>;
+declare function fieldCatalog(client: AutotaskClient, opts?: FieldCatalogOptions): Promise<FieldCatalogResult<FieldCatalogFieldRow | FieldCatalogCompactFieldRow>>;
 
 /** The pinned per-call id cap (mirrors `FETCH_BY_IDS_MAX_ITEMS` — the house bulk cap; over → pre-request refusal, zero wire). */
 declare const EXPAND_RESOURCE_NAMES_MAX_IDS = 500;
@@ -1221,4 +1282,4 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[] | Record<string, unknown>, opts?: InvokeOptions): Promise<unknown>;
 
-export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, type DerivationRule, ENTITY_TYPE_TO_RESOURCE, EXPAND_RESOURCE_NAMES_MAX_IDS, type EffectiveRequiredFields, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type RequiredFieldsRecord, type RequiredFieldsSource, type RequiredFieldsZoneFacts, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type RevenueRollupAmount, type RevenueRollupDimension, type RevenueRollupKey, type RevenueRollupNonChargeable, type RevenueRollupNonChargeableAmount, type RevenueRollupOptions, type RevenueRollupResult, type RevenueRollupRow, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, type ServedCreateGuidanceReport, type ServedCreateGuidanceRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, revenueRollup, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, type DerivationRule, ENTITY_TYPE_TO_RESOURCE, EXPAND_RESOURCE_NAMES_MAX_IDS, type EffectiveRequiredFields, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogCompactFieldRow, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldCatalogTrimKind, type FieldCatalogTruncation, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, MIN_FIELD_CATALOG_MAX_BYTES, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type RequiredFieldsRecord, type RequiredFieldsSource, type RequiredFieldsZoneFacts, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type RevenueRollupAmount, type RevenueRollupDimension, type RevenueRollupKey, type RevenueRollupNonChargeable, type RevenueRollupNonChargeableAmount, type RevenueRollupOptions, type RevenueRollupResult, type RevenueRollupRow, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, type ServedCreateGuidanceReport, type ServedCreateGuidanceRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, revenueRollup, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };