node-autotask 0.8.3 → 0.10.0

package/dist/operations/index.d.cts

@@ -1,7 +1,7 @@
-import { A as AutotaskClient } from '../client-Q6NoqinP.cjs';
-import { I as Identifier, a as FilterCondition } from '../index-DOCRp_83.cjs';
-import { eI as RelationshipResource, eJ as BlindSurfaceInventory, eK as BlindSurfaceRow, eL as CreateBlockerKind, eM as CreateGuidanceReport, eN as FieldCacheKind, bg as AutotaskConfigError } from '../index-B0I2bGtx.cjs';
-export { eO as FIELD_CACHE_KINDS } from '../index-B0I2bGtx.cjs';
+import { a as AutotaskClient, eN as BlindSurfaceInfo, eO as RelationshipResource, eP as BlindSurfaceInventory, eQ as BlindSurfaceRow, eR as CreateBlockerKind, eS as CreateGuidanceReport, eT as FieldCacheKind, g as AutotaskConfigError } from '../index-BOyh7S65.cjs';
+export { eU as FIELD_CACHE_KINDS } from '../index-BOyh7S65.cjs';
+import { I as Identifier, cE as EmptyReasonInfo, dI as PickListValue, a as FilterCondition } from '../index-cQ6CRexR.cjs';
+export { hp as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-cQ6CRexR.cjs';
 import { CapabilityRecord } from '../capabilities.cjs';
 
 /**
@@ -136,13 +136,43 @@ declare const FETCH_MANY_MAX_ITEMS = 20;
 interface FetchManyOptions {
     /** May LOWER the {@link FETCH_MANY_MAX_ITEMS} cap (integer >= 1) — never raise it. */
     maxItems?: number;
+    /**
+     * Opt-in live field validation (issue #66): when `true`, each item's
+     * requested `fields` are validated against the tenant's LIVE entity field
+     * metadata (the cached metadata channel — a warm fieldCache costs zero
+     * wire; a cold run is one `entityInformation/fields` GET per distinct
+     * resource in the batch) instead of the vendored-spec field set alone.
+     * When a resource's metadata is unavailable the validation falls back to
+     * the vendored-spec field set for THAT resource (unavailability never
+     * throws and never blocks the batch); when available the live set is
+     * authoritative — a field it lacks is refused even if the spec lists it,
+     * and a live field the spec lacks (e.g. `time_entries` `postedDate`) is
+     * accepted. Default `false` = today's vendored-spec-only validation,
+     * bit-for-bit (zero metadata wire).
+     */
+    liveFields?: boolean;
+}
+interface ValidateFetchManyValidation {
+    /**
+     * The resolved authoritative per-resource field sets (the `liveFields`
+     * mode, issue #66): the live entity field set when available, `null` when
+     * that resource's metadata read rejected (the vendored-spec fallback was
+     * applied at resolution). Absent / no entry = the vendored-spec set.
+     */
+    fieldSetsByResource?: ReadonlyMap<string, readonly string[] | null>;
+    /** Run the field-NAME membership check (the live mode's shape-only pass passes `false`). */
+    fieldCheck?: boolean;
 }
 /**
  * The pre-request validation (zero wire): one `CONFIG_ERROR` carries the
  * COMPLETE problem list for ALL items (shape, limits, unknown resource,
  * string id, unknown field key) — the caller fixes everything in one round.
+ *
+ * `validation` (the `liveFields` mode, issue #66): the resolved
+ * authoritative per-resource field sets to validate `fields` against; absent
+ * = the vendored-spec sets, bit-for-bit the default.
  */
-declare function validateFetchManyItems(items: unknown, cap: number): void;
+declare function validateFetchManyItems(items: unknown, cap: number, opName?: string, capRef?: string, validation?: ValidateFetchManyValidation): void;
 /**
  * Fetch up to 20 single records across mixed resources in ONE call
  * (sequential GETs; per-item typed partial failure; the op throws only
@@ -159,6 +189,91 @@ declare function validateFetchManyItems(items: unknown, cap: number): void;
  */
 declare function fetchMany(client: AutotaskClient, items: readonly FetchManyItem[], opts?: FetchManyOptions): Promise<FetchManyResult>;
 
+/** The group-row cap (top may lower it, never raise it). */
+declare const AGGREGATE_TOP_MAX = 100;
+/** The default group-row count. */
+declare const AGGREGATE_DEFAULT_TOP = 25;
+/** The walk-mode default record cap = the house `BOUNDED_QUERY_MAX_LIMIT` (the hard max — `queryBounded` rejects above it). */
+declare const AGGREGATE_DEFAULT_LIMIT = 2500;
+/** The closed opts bag for `operations.aggregate`. */
+interface AggregateOptions {
+    /** The group-by vendor field names (the group key = the field tuple). */
+    groupBy?: string[];
+    /** The numeric vendor field names to sum per group. */
+    sum?: string[];
+    /** The group-row cap (default 25, clamped 1..100). */
+    top?: number;
+    /** The total-record cap for the walk modes (default = max = the house 2500 — `queryBounded`'s hard limit). */
+    limit?: number;
+}
+/** One folded group (the key = the groupBy field tuple; `sums` present iff `sum` was given). */
+interface AggregateGroup {
+    key: Record<string, unknown>;
+    count: number;
+    sums?: Record<string, number>;
+}
+/** The aggregate result (the mode discards the other mode's fields). */
+interface AggregateResult {
+    mode: 'count' | 'group' | 'sum';
+    /** count mode: the count value (a plain number; 0 + `blind` on a pinned blind shape). */
+    count?: number;
+    /** group/sum mode: the top-N folded groups (the returned rows ONLY when `hasMore`). */
+    groups?: AggregateGroup[];
+    /** group/sum mode: the number of DISTINCT groups the fold found (before `top` cut them). */
+    totalGroups?: number;
+    /** group/sum mode: true when `top` dropped groups (`totalGroups > groups.length`): the returned groups are the top-N only. */
+    groupsTruncated?: boolean;
+    /** group/sum mode: the walk's fetched record count. */
+    totalScanned?: number;
+    /** group/sum mode: the walk's truncation flag (true → groups/sums cover the returned rows only). */
+    hasMore?: boolean;
+    /** count mode: true exactly when the S12-C sentinel stamped the 0 (the filter-aware predicate). */
+    blind?: boolean;
+    /** The S12-C typed sentinel (count mode: the blind 0; walk mode: the 0-row walk stamp). */
+    blindSurface?: BlindSurfaceInfo;
+    /** The typed empty-reason stamp (the base's 0-row/0-count channel, when attached). */
+    emptyReason?: EmptyReasonInfo;
+}
+/**
+ * `operations.aggregate` — fold any query surface into groups/sums in one
+ * bounded call, or count it with the vendor count endpoint when no folding
+ * is needed (the `groupBy`/`sum`-absent mode). See the module header for
+ * the pinned semantics (the mode table, the blind-surface marking, the
+ * truncation honesty, the closed-arg contract).
+ *
+ * ```ts
+ * import { aggregate } from 'node-autotask/operations';
+ * const count = await aggregate(client, 'billing_items.query', [{ field: 'companyID', op: 'eq', value: 30132785 }]);
+ * const fold = await aggregate(client, 'time_entries.query', [{ field: 'dateWorked', op: 'gte', value: '2026-09-01' }], { groupBy: ['ticketID'], sum: ['hoursWorked'], top: 10 });
+ * ```
+ */
+declare function aggregate(client: AutotaskClient, operation: string, filter: unknown, opts?: AggregateOptions): Promise<AggregateResult>;
+
+/** The pinned per-call item cap (total items per call, mixed resources — the issue's "500 ids" budget; over → CONFIG_ERROR pre-request, zero wire). */
+declare const FETCH_BY_IDS_MAX_ITEMS = 500;
+/** The pinned `id in` chunk size (250/chunk — the chunk query is a single page: 250 is well under the 500 vendor page max). */
+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;
+}
+/**
+ * Fetch up to 500 single records by vendor numeric id across mixed
+ * resources in ONE call (query-first chunked `id in` reads + the per-id
+ * `get` fallback; per-item typed partial failure; the op throws only
+ * pre-request).
+ *
+ * ```ts
+ * import { fetchByIds } from 'node-autotask/operations';
+ * const { results, ok, failed } = await fetchByIds(client, [
+ *   { resource: 'tickets', id: 527119 },
+ *   { resource: 'tickets', id: 527118, fields: ['id', 'title', 'status'] },
+ *   { resource: 'projects', id: 693 },
+ * ]);
+ * ```
+ */
+declare function fetchByIds(client: AutotaskClient, items: readonly FetchManyItem[], opts?: FetchByIdsOptions): Promise<FetchManyResult>;
+
 /**
  * Serve one resource's relationship entry (zero wire).
  *
@@ -313,10 +428,11 @@ declare function createGuidance(client: AutotaskClient, opts?: CreateGuidanceOpt
  * pre-request (CONFIG_ERROR naming the computed cost and the cap) —
  * refused, never truncated. */
 declare const MAX_FIELD_CATALOG_WIRE = 60;
-/** The stable honesty sentence served in the result (W-A4: the live
- * catalog reports field SHAPE; it cannot resolve a picklist VALUE the
- * vendor does not expose to this API user — where values ARE exposed,
- * they are served). */
+/** The stable honesty sentence served in the result (the live catalog
+ * reports field SHAPE as FLAGS and NAMES; with the opt-in `labels: true`
+ * the projected picklist rows carry the vendor's exposed picklist
+ * VALUES; it cannot resolve a picklist VALUE the vendor does not expose
+ * to this API user — the W-A4 wall). */
 declare const FIELD_CATALOG_HONESTY_NOTE: string;
 /** One projected field row (the stable, small served shape — not the raw
  * vendor blob; the raw one stays available through the resource's own
@@ -336,6 +452,8 @@ interface FieldCatalogFieldRow {
     maxLength: number | null;
     /** The referenced entity type for reference fields ('' when none). */
     referenceEntityType: string;
+    /** 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 per-resource fault (partial failures are typed PER ROW — never all-or-nothing). */
 interface FieldCatalogRowError {
@@ -352,8 +470,10 @@ interface FieldCatalogRow {
     udfCapable: boolean;
     /** The entity information model (present exactly when `info` was included and fetched). */
     info?: Record<string, unknown> | null;
-    /** The projected standard-field catalog (present exactly when `fields` was included and fetched). */
+    /** 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[];
+    /** 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;
     /** `isRequired === true` names, in catalog order (the `fields` catalog). */
@@ -382,6 +502,8 @@ interface FieldCatalogResult {
     label: string;
     /** Whether a FieldCache was configured at all. */
     cached: boolean;
+    /** The resolved `labels` opt (the served payload names what it carries: `true` = the picklist rows may carry `picklistValues`). */
+    labels: boolean;
     /** The configured TTL (null when no cache). */
     ttlMs: number | null;
     /** The call instant (ISO). */
@@ -406,7 +528,7 @@ interface FieldCatalogResult {
     };
     /** The honest scope: what the live catalog can and cannot report. */
     honesty: {
-        /** 'partial' when any served row carries picklist VALUES the vendor exposed; 'unexposed' otherwise. */
+        /** The vendor's WIRE exposure of picklist values, informational only (orthogonal to the `labels` opt — it reports what the vendor exposed on the wire, not what the caller opted into): 'partial' when any row's raw vendor response carried picklist VALUES on the wire — computed over the full raw list, not the filtered subset; 'unexposed' otherwise. */
         picklistValues: 'unexposed' | 'partial';
         note: string;
     };
@@ -419,6 +541,10 @@ interface FieldCatalogOptions {
     include?: FieldCacheKind[];
     /** Bypass the fieldCache for this call (fetch live, refresh the entries). Default false. */
     fresh?: boolean;
+    /** The optional post-projection filter on the `fields`-kind rows only: keep the named fields (vendor names, trimmed, de-duplicated). Report-not-error: names absent from a resource's fields catalog land on that row's `unmatchedFields`, never an error; the `info` and `udf` rows are unaffected (the filter is a no-op on them). Applied after projection, on cache hits and wire reads alike — the cache entries stay the full raw list (zero extra wire, no invalidation). */
+    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;
 }
 /**
  * Run the bounded live field-metadata sweep.
@@ -430,10 +556,62 @@ interface FieldCatalogOptions {
  * ```
  *
  * @param client The wired client (the reads issue entityInformation GETs).
- * @param opts   The call bag ({ resources?, include?, fresh? }).
+ * @param opts   The call bag ({ resources?, include?, fresh?, fields?, labels? }).
  */
 declare function fieldCatalog(client: AutotaskClient, opts?: FieldCatalogOptions): Promise<FieldCatalogResult>;
 
+/** 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;
+interface ExpandResourceNamesOptions {
+    /** May LOWER the {@link EXPAND_RESOURCE_NAMES_MAX_IDS} cap (integer >= 1) — never raise it. */
+    maxIds?: number;
+    /** Bypass + refresh the NAME cache AND the ReadCache (default false — the name-cache lookup runs unless `resourceNameCache: false`; the per-id `resources.get` otherwise rides the ReadCache when `cache` is configured). With `fresh: true`, the per-id GET fetches live and refreshes BOTH caches — a rename made elsewhere is served on the very next call, never a stale snapshot (issue #77). */
+    fresh?: boolean;
+}
+/** One per-id outcome (input order; duplicates get identical rows). */
+interface ExpandResourceNameRow {
+    /** The canonical id as requested (safe integer, or the exact-digit string). */
+    id: Identifier;
+    /** The composed display name (`firstName [middleName] lastName`,
+     * single spaces); null when the vendor returned no name part (a
+     * data gap — distinct from blind) or the id is blind. */
+    name: string | null;
+    /** True when the per-id read is the vendor's true not-found (404 or
+     * `200 item: null`) — the table-invisible case: the id is kept, no
+     * error, no throw. */
+    blind: boolean;
+    /** A transient per-id fault (code + httpStatus + message) — present
+     * exactly when the id neither resolved nor came back blind; never
+     * cached, never aborting the remaining ids. */
+    error?: FetchManyItemError;
+}
+/** The batch result: one row per input occurrence, in input order. */
+interface ExpandResourceNamesResult {
+    results: ExpandResourceNameRow[];
+    /** Rows with a composed name. */
+    resolved: number;
+    /** Rows marked blind (the vendor's true not-found). */
+    blind: number;
+    /** Rows carrying a per-id fault. */
+    failed: number;
+}
+/**
+ * Resolve vendor numeric resource ids to display names in ONE opt-in
+ * call (per-id `resources.get` reads ONLY — never an `id in` query;
+ * blind-marked rows for ids the API user cannot resolve; the opt-in
+ * name cache when configured).
+ *
+ * ```ts
+ * import { expandResourceNames } from 'node-autotask/operations';
+ * const { results, resolved, blind, failed } = await expandResourceNames(
+ *   client,
+ *   [101, 102, '103'],
+ *   { maxIds: 500, fresh: false },
+ * );
+ * ```
+ */
+declare function expandResourceNames(client: AutotaskClient, ids: readonly Identifier[], opts?: ExpandResourceNamesOptions): Promise<ExpandResourceNamesResult>;
+
 /** The exact confirmation string the destructive apply requires (R4 style: the op key). */
 declare const RECOVERY_CONFIRM = "operations.recovery";
 /** The default TOTAL match cap of the marker search. */
@@ -600,9 +778,10 @@ declare function recovery(client: AutotaskClient, input: RecoveryInput, opts?: R
  * - the query-family params bag (`args[0]` for `query` / `queryAll` /
  *   `count`) is CLOSED at its top level: the valid key set is per-verb
  *   (PARAMS_BAG_KEYS — for `query` routed to `queryBounded`:
- *   filter / limit / includeFields / via) and an unknown key (`filters`,
- *   `lmit`, `pageSize`, `cursor`, …) is refused pre-request with a typed
- *   error naming the key + the valid keys + a did-you-mean; entity bodies,
+ *   filter / limit / latest / includeFields / via) and an unknown key
+ *   (`filters`, `lmit`, `pageSize`, `cursor`, …) is refused pre-request
+ *   with a typed error naming the key + the valid keys + a did-you-mean
+ *   (`last` → `latest`, issue #59); entity bodies,
  *   UDF maps and the filter tree stay open (strictness applies to tool
  *   arguments, not vendor payloads);
  * - the caller's `args` are validated against the record's declared
@@ -715,4 +894,4 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[], opts?: InvokeOptions): Promise<unknown>;
 
-export { BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, 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 ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, WORKFLOW_RESOURCES, blindSurfaces, createGuidance, fetchMany, fieldCatalog, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+export { 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, EXPAND_RESOURCE_NAMES_MAX_IDS, 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, 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 ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, WORKFLOW_RESOURCES, aggregate, blindSurfaces, createGuidance, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };

package/dist/operations/index.d.ts

@@ -1,7 +1,7 @@
-import { A as AutotaskClient } from '../client-DHmr0Oyx.js';
-import { I as Identifier, a as FilterCondition } from '../index-DOCRp_83.js';
-import { eI as RelationshipResource, eJ as BlindSurfaceInventory, eK as BlindSurfaceRow, eL as CreateBlockerKind, eM as CreateGuidanceReport, eN as FieldCacheKind, bg as AutotaskConfigError } from '../index-B6JeThrY.js';
-export { eO as FIELD_CACHE_KINDS } from '../index-B6JeThrY.js';
+import { a as AutotaskClient, eN as BlindSurfaceInfo, eO as RelationshipResource, eP as BlindSurfaceInventory, eQ as BlindSurfaceRow, eR as CreateBlockerKind, eS as CreateGuidanceReport, eT as FieldCacheKind, g as AutotaskConfigError } from '../index-DGgMD8aq.js';
+export { eU as FIELD_CACHE_KINDS } from '../index-DGgMD8aq.js';
+import { I as Identifier, cE as EmptyReasonInfo, dI as PickListValue, a as FilterCondition } from '../index-cQ6CRexR.js';
+export { hp as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-cQ6CRexR.js';
 import { CapabilityRecord } from '../capabilities.js';
 
 /**
@@ -136,13 +136,43 @@ declare const FETCH_MANY_MAX_ITEMS = 20;
 interface FetchManyOptions {
     /** May LOWER the {@link FETCH_MANY_MAX_ITEMS} cap (integer >= 1) — never raise it. */
     maxItems?: number;
+    /**
+     * Opt-in live field validation (issue #66): when `true`, each item's
+     * requested `fields` are validated against the tenant's LIVE entity field
+     * metadata (the cached metadata channel — a warm fieldCache costs zero
+     * wire; a cold run is one `entityInformation/fields` GET per distinct
+     * resource in the batch) instead of the vendored-spec field set alone.
+     * When a resource's metadata is unavailable the validation falls back to
+     * the vendored-spec field set for THAT resource (unavailability never
+     * throws and never blocks the batch); when available the live set is
+     * authoritative — a field it lacks is refused even if the spec lists it,
+     * and a live field the spec lacks (e.g. `time_entries` `postedDate`) is
+     * accepted. Default `false` = today's vendored-spec-only validation,
+     * bit-for-bit (zero metadata wire).
+     */
+    liveFields?: boolean;
+}
+interface ValidateFetchManyValidation {
+    /**
+     * The resolved authoritative per-resource field sets (the `liveFields`
+     * mode, issue #66): the live entity field set when available, `null` when
+     * that resource's metadata read rejected (the vendored-spec fallback was
+     * applied at resolution). Absent / no entry = the vendored-spec set.
+     */
+    fieldSetsByResource?: ReadonlyMap<string, readonly string[] | null>;
+    /** Run the field-NAME membership check (the live mode's shape-only pass passes `false`). */
+    fieldCheck?: boolean;
 }
 /**
  * The pre-request validation (zero wire): one `CONFIG_ERROR` carries the
  * COMPLETE problem list for ALL items (shape, limits, unknown resource,
  * string id, unknown field key) — the caller fixes everything in one round.
+ *
+ * `validation` (the `liveFields` mode, issue #66): the resolved
+ * authoritative per-resource field sets to validate `fields` against; absent
+ * = the vendored-spec sets, bit-for-bit the default.
  */
-declare function validateFetchManyItems(items: unknown, cap: number): void;
+declare function validateFetchManyItems(items: unknown, cap: number, opName?: string, capRef?: string, validation?: ValidateFetchManyValidation): void;
 /**
  * Fetch up to 20 single records across mixed resources in ONE call
  * (sequential GETs; per-item typed partial failure; the op throws only
@@ -159,6 +189,91 @@ declare function validateFetchManyItems(items: unknown, cap: number): void;
  */
 declare function fetchMany(client: AutotaskClient, items: readonly FetchManyItem[], opts?: FetchManyOptions): Promise<FetchManyResult>;
 
+/** The group-row cap (top may lower it, never raise it). */
+declare const AGGREGATE_TOP_MAX = 100;
+/** The default group-row count. */
+declare const AGGREGATE_DEFAULT_TOP = 25;
+/** The walk-mode default record cap = the house `BOUNDED_QUERY_MAX_LIMIT` (the hard max — `queryBounded` rejects above it). */
+declare const AGGREGATE_DEFAULT_LIMIT = 2500;
+/** The closed opts bag for `operations.aggregate`. */
+interface AggregateOptions {
+    /** The group-by vendor field names (the group key = the field tuple). */
+    groupBy?: string[];
+    /** The numeric vendor field names to sum per group. */
+    sum?: string[];
+    /** The group-row cap (default 25, clamped 1..100). */
+    top?: number;
+    /** The total-record cap for the walk modes (default = max = the house 2500 — `queryBounded`'s hard limit). */
+    limit?: number;
+}
+/** One folded group (the key = the groupBy field tuple; `sums` present iff `sum` was given). */
+interface AggregateGroup {
+    key: Record<string, unknown>;
+    count: number;
+    sums?: Record<string, number>;
+}
+/** The aggregate result (the mode discards the other mode's fields). */
+interface AggregateResult {
+    mode: 'count' | 'group' | 'sum';
+    /** count mode: the count value (a plain number; 0 + `blind` on a pinned blind shape). */
+    count?: number;
+    /** group/sum mode: the top-N folded groups (the returned rows ONLY when `hasMore`). */
+    groups?: AggregateGroup[];
+    /** group/sum mode: the number of DISTINCT groups the fold found (before `top` cut them). */
+    totalGroups?: number;
+    /** group/sum mode: true when `top` dropped groups (`totalGroups > groups.length`): the returned groups are the top-N only. */
+    groupsTruncated?: boolean;
+    /** group/sum mode: the walk's fetched record count. */
+    totalScanned?: number;
+    /** group/sum mode: the walk's truncation flag (true → groups/sums cover the returned rows only). */
+    hasMore?: boolean;
+    /** count mode: true exactly when the S12-C sentinel stamped the 0 (the filter-aware predicate). */
+    blind?: boolean;
+    /** The S12-C typed sentinel (count mode: the blind 0; walk mode: the 0-row walk stamp). */
+    blindSurface?: BlindSurfaceInfo;
+    /** The typed empty-reason stamp (the base's 0-row/0-count channel, when attached). */
+    emptyReason?: EmptyReasonInfo;
+}
+/**
+ * `operations.aggregate` — fold any query surface into groups/sums in one
+ * bounded call, or count it with the vendor count endpoint when no folding
+ * is needed (the `groupBy`/`sum`-absent mode). See the module header for
+ * the pinned semantics (the mode table, the blind-surface marking, the
+ * truncation honesty, the closed-arg contract).
+ *
+ * ```ts
+ * import { aggregate } from 'node-autotask/operations';
+ * const count = await aggregate(client, 'billing_items.query', [{ field: 'companyID', op: 'eq', value: 30132785 }]);
+ * const fold = await aggregate(client, 'time_entries.query', [{ field: 'dateWorked', op: 'gte', value: '2026-09-01' }], { groupBy: ['ticketID'], sum: ['hoursWorked'], top: 10 });
+ * ```
+ */
+declare function aggregate(client: AutotaskClient, operation: string, filter: unknown, opts?: AggregateOptions): Promise<AggregateResult>;
+
+/** The pinned per-call item cap (total items per call, mixed resources — the issue's "500 ids" budget; over → CONFIG_ERROR pre-request, zero wire). */
+declare const FETCH_BY_IDS_MAX_ITEMS = 500;
+/** The pinned `id in` chunk size (250/chunk — the chunk query is a single page: 250 is well under the 500 vendor page max). */
+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;
+}
+/**
+ * Fetch up to 500 single records by vendor numeric id across mixed
+ * resources in ONE call (query-first chunked `id in` reads + the per-id
+ * `get` fallback; per-item typed partial failure; the op throws only
+ * pre-request).
+ *
+ * ```ts
+ * import { fetchByIds } from 'node-autotask/operations';
+ * const { results, ok, failed } = await fetchByIds(client, [
+ *   { resource: 'tickets', id: 527119 },
+ *   { resource: 'tickets', id: 527118, fields: ['id', 'title', 'status'] },
+ *   { resource: 'projects', id: 693 },
+ * ]);
+ * ```
+ */
+declare function fetchByIds(client: AutotaskClient, items: readonly FetchManyItem[], opts?: FetchByIdsOptions): Promise<FetchManyResult>;
+
 /**
  * Serve one resource's relationship entry (zero wire).
  *
@@ -313,10 +428,11 @@ declare function createGuidance(client: AutotaskClient, opts?: CreateGuidanceOpt
  * pre-request (CONFIG_ERROR naming the computed cost and the cap) —
  * refused, never truncated. */
 declare const MAX_FIELD_CATALOG_WIRE = 60;
-/** The stable honesty sentence served in the result (W-A4: the live
- * catalog reports field SHAPE; it cannot resolve a picklist VALUE the
- * vendor does not expose to this API user — where values ARE exposed,
- * they are served). */
+/** The stable honesty sentence served in the result (the live catalog
+ * reports field SHAPE as FLAGS and NAMES; with the opt-in `labels: true`
+ * the projected picklist rows carry the vendor's exposed picklist
+ * VALUES; it cannot resolve a picklist VALUE the vendor does not expose
+ * to this API user — the W-A4 wall). */
 declare const FIELD_CATALOG_HONESTY_NOTE: string;
 /** One projected field row (the stable, small served shape — not the raw
  * vendor blob; the raw one stays available through the resource's own
@@ -336,6 +452,8 @@ interface FieldCatalogFieldRow {
     maxLength: number | null;
     /** The referenced entity type for reference fields ('' when none). */
     referenceEntityType: string;
+    /** 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 per-resource fault (partial failures are typed PER ROW — never all-or-nothing). */
 interface FieldCatalogRowError {
@@ -352,8 +470,10 @@ interface FieldCatalogRow {
     udfCapable: boolean;
     /** The entity information model (present exactly when `info` was included and fetched). */
     info?: Record<string, unknown> | null;
-    /** The projected standard-field catalog (present exactly when `fields` was included and fetched). */
+    /** 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[];
+    /** 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;
     /** `isRequired === true` names, in catalog order (the `fields` catalog). */
@@ -382,6 +502,8 @@ interface FieldCatalogResult {
     label: string;
     /** Whether a FieldCache was configured at all. */
     cached: boolean;
+    /** The resolved `labels` opt (the served payload names what it carries: `true` = the picklist rows may carry `picklistValues`). */
+    labels: boolean;
     /** The configured TTL (null when no cache). */
     ttlMs: number | null;
     /** The call instant (ISO). */
@@ -406,7 +528,7 @@ interface FieldCatalogResult {
     };
     /** The honest scope: what the live catalog can and cannot report. */
     honesty: {
-        /** 'partial' when any served row carries picklist VALUES the vendor exposed; 'unexposed' otherwise. */
+        /** The vendor's WIRE exposure of picklist values, informational only (orthogonal to the `labels` opt — it reports what the vendor exposed on the wire, not what the caller opted into): 'partial' when any row's raw vendor response carried picklist VALUES on the wire — computed over the full raw list, not the filtered subset; 'unexposed' otherwise. */
         picklistValues: 'unexposed' | 'partial';
         note: string;
     };
@@ -419,6 +541,10 @@ interface FieldCatalogOptions {
     include?: FieldCacheKind[];
     /** Bypass the fieldCache for this call (fetch live, refresh the entries). Default false. */
     fresh?: boolean;
+    /** The optional post-projection filter on the `fields`-kind rows only: keep the named fields (vendor names, trimmed, de-duplicated). Report-not-error: names absent from a resource's fields catalog land on that row's `unmatchedFields`, never an error; the `info` and `udf` rows are unaffected (the filter is a no-op on them). Applied after projection, on cache hits and wire reads alike — the cache entries stay the full raw list (zero extra wire, no invalidation). */
+    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;
 }
 /**
  * Run the bounded live field-metadata sweep.
@@ -430,10 +556,62 @@ interface FieldCatalogOptions {
  * ```
  *
  * @param client The wired client (the reads issue entityInformation GETs).
- * @param opts   The call bag ({ resources?, include?, fresh? }).
+ * @param opts   The call bag ({ resources?, include?, fresh?, fields?, labels? }).
  */
 declare function fieldCatalog(client: AutotaskClient, opts?: FieldCatalogOptions): Promise<FieldCatalogResult>;
 
+/** 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;
+interface ExpandResourceNamesOptions {
+    /** May LOWER the {@link EXPAND_RESOURCE_NAMES_MAX_IDS} cap (integer >= 1) — never raise it. */
+    maxIds?: number;
+    /** Bypass + refresh the NAME cache AND the ReadCache (default false — the name-cache lookup runs unless `resourceNameCache: false`; the per-id `resources.get` otherwise rides the ReadCache when `cache` is configured). With `fresh: true`, the per-id GET fetches live and refreshes BOTH caches — a rename made elsewhere is served on the very next call, never a stale snapshot (issue #77). */
+    fresh?: boolean;
+}
+/** One per-id outcome (input order; duplicates get identical rows). */
+interface ExpandResourceNameRow {
+    /** The canonical id as requested (safe integer, or the exact-digit string). */
+    id: Identifier;
+    /** The composed display name (`firstName [middleName] lastName`,
+     * single spaces); null when the vendor returned no name part (a
+     * data gap — distinct from blind) or the id is blind. */
+    name: string | null;
+    /** True when the per-id read is the vendor's true not-found (404 or
+     * `200 item: null`) — the table-invisible case: the id is kept, no
+     * error, no throw. */
+    blind: boolean;
+    /** A transient per-id fault (code + httpStatus + message) — present
+     * exactly when the id neither resolved nor came back blind; never
+     * cached, never aborting the remaining ids. */
+    error?: FetchManyItemError;
+}
+/** The batch result: one row per input occurrence, in input order. */
+interface ExpandResourceNamesResult {
+    results: ExpandResourceNameRow[];
+    /** Rows with a composed name. */
+    resolved: number;
+    /** Rows marked blind (the vendor's true not-found). */
+    blind: number;
+    /** Rows carrying a per-id fault. */
+    failed: number;
+}
+/**
+ * Resolve vendor numeric resource ids to display names in ONE opt-in
+ * call (per-id `resources.get` reads ONLY — never an `id in` query;
+ * blind-marked rows for ids the API user cannot resolve; the opt-in
+ * name cache when configured).
+ *
+ * ```ts
+ * import { expandResourceNames } from 'node-autotask/operations';
+ * const { results, resolved, blind, failed } = await expandResourceNames(
+ *   client,
+ *   [101, 102, '103'],
+ *   { maxIds: 500, fresh: false },
+ * );
+ * ```
+ */
+declare function expandResourceNames(client: AutotaskClient, ids: readonly Identifier[], opts?: ExpandResourceNamesOptions): Promise<ExpandResourceNamesResult>;
+
 /** The exact confirmation string the destructive apply requires (R4 style: the op key). */
 declare const RECOVERY_CONFIRM = "operations.recovery";
 /** The default TOTAL match cap of the marker search. */
@@ -600,9 +778,10 @@ declare function recovery(client: AutotaskClient, input: RecoveryInput, opts?: R
  * - the query-family params bag (`args[0]` for `query` / `queryAll` /
  *   `count`) is CLOSED at its top level: the valid key set is per-verb
  *   (PARAMS_BAG_KEYS — for `query` routed to `queryBounded`:
- *   filter / limit / includeFields / via) and an unknown key (`filters`,
- *   `lmit`, `pageSize`, `cursor`, …) is refused pre-request with a typed
- *   error naming the key + the valid keys + a did-you-mean; entity bodies,
+ *   filter / limit / latest / includeFields / via) and an unknown key
+ *   (`filters`, `lmit`, `pageSize`, `cursor`, …) is refused pre-request
+ *   with a typed error naming the key + the valid keys + a did-you-mean
+ *   (`last` → `latest`, issue #59); entity bodies,
  *   UDF maps and the filter tree stay open (strictness applies to tool
  *   arguments, not vendor payloads);
  * - the caller's `args` are validated against the record's declared
@@ -715,4 +894,4 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[], opts?: InvokeOptions): Promise<unknown>;
 
-export { BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, 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 ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, WORKFLOW_RESOURCES, blindSurfaces, createGuidance, fetchMany, fieldCatalog, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+export { 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, EXPAND_RESOURCE_NAMES_MAX_IDS, 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, 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 ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, WORKFLOW_RESOURCES, aggregate, blindSurfaces, createGuidance, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };