node-autotask 0.8.3 → 0.10.0

package/dist/operations/index.js

@@ -2,36 +2,38 @@ import {
   AutotaskConfigError,
   AutotaskError,
   BLIND_SURFACE_INVENTORY,
+  BOUNDED_QUERY_MAX_LIMIT,
   CREATE_GUIDANCE,
   ConfirmationRequiredError,
   DELETE_BOUNDARY_NOTES,
   DeleteBoundaryError,
+  EXPAND_RESOURCE_NAMES_MAX_IDS,
   FIELD_CACHE_KINDS,
+  FIELD_CATALOG_HONESTY_NOTE,
   MARKER_FIELDS,
+  MAX_FIELD_CATALOG_WIRE,
   MarkerUnsafeIdError,
   NotFoundError,
+  PICKLIST_VALUE_NOT_SERVED_NOTE,
   REACHABILITY_PROBE_DEFAULTS,
   RELATIONSHIP_MAP,
   RELATIONSHIP_ZONE,
   RecoveryTruncatedError,
+  WORKFLOW_RESOURCES,
+  buildFilter,
+  buildQueryRequest,
   camelKey,
   clampPageSize,
+  expandResourceNames,
+  fieldCatalog,
   isAutotaskError,
   isRecord,
-  parseIdentifier
-} from "../chunk-GYI4ZQID.js";
+  parseIdentifier,
+  unwrapItems
+} from "../chunk-HWC2WPX2.js";
 import {
   CAPABILITIES
-} from "../chunk-32AKZMY4.js";
-
-// src/operations/types.ts
-var WORKFLOW_RESOURCES = [
-  "companies",
-  "tickets",
-  "contacts",
-  "configuration_items",
-  "projects"
-];
+} from "../chunk-6KFP5HV3.js";
 
 // src/operations/searchAcrossResources.ts
 var DEFAULT_LIMIT = 25;
@@ -259,23 +261,23 @@ var MODEL_FIELD_SETS = {
 
 // src/operations/fetchMany.ts
 var FETCH_MANY_MAX_ITEMS = 20;
-function validateFetchManyItems(items, cap) {
+function validateFetchManyItems(items, cap, opName = "fetchMany", capRef = `FETCH_MANY_MAX_ITEMS = ${FETCH_MANY_MAX_ITEMS}`, validation) {
   if (!Array.isArray(items)) {
     throw new AutotaskConfigError(
-      `fetchMany: items must be the items ARRAY \u2014 one positional arg, [{ resource: string, id: number, fields?: string[] }] (got ${Array.isArray(items) ? "an array" : typeof items})`,
+      `${opName}: items must be the items ARRAY \u2014 one positional arg, [{ resource: string, id: number, fields?: string[] }] (got ${Array.isArray(items) ? "an array" : typeof items})`,
       {
         suggestedAction: 'Pass args = [[{ resource: "tickets", id: 123 }, { resource: "projects", id: 456 }]] \u2014 the items array is the single positional argument.'
       }
     );
   }
   if (items.length === 0) {
-    throw new AutotaskConfigError("fetchMany: items must not be empty (a zero-item batch is a shape error, not a no-op)", {
+    throw new AutotaskConfigError(`${opName}: items must not be empty (a zero-item batch is a shape error, not a no-op)`, {
       suggestedAction: "Pass at least one { resource, id } item \u2014 or use the resource's query op for a filtered read."
     });
   }
   if (items.length > cap) {
     throw new AutotaskConfigError(
-      `fetchMany: ${items.length} items over the ${cap}-item cap (FETCH_MANY_MAX_ITEMS = ${FETCH_MANY_MAX_ITEMS}) \u2014 zero items were fetched (pre-request)`,
+      `${opName}: ${items.length} items over the ${cap}-item cap (${capRef}) \u2014 zero items were fetched (pre-request)`,
       {
         suggestedAction: `Split the batch into groups of <= ${cap} items \u2014 or, for more than ${cap} records / a filtered set, use the resource's bounded query op (<resource>.query).`
       }
@@ -327,21 +329,24 @@ function validateFetchManyItems(items, cap) {
     }
     if (item.fields !== void 0) {
       if (!Array.isArray(item.fields) || item.fields.some((f) => typeof f !== "string")) {
-        problems.push(`${at}.fields: must be an array of exact vendor field names (discover them via ${resourceKey}.getFieldInfo)`);
+        problems.push(`${at}.fields: must be an array of exact vendor field names (discover them via operations.fieldCatalog)`);
         continue;
       }
-      for (const f of item.fields) {
-        if (!fields.includes(f)) {
-          problems.push(
-            `${at}.fields: "${f}" is not a field of ${resourceKey} \u2014 a hallucinated field is a shape error, not a silent projection-miss (exact vendor field names via ${resourceKey}.getFieldInfo)`
-          );
+      if (validation?.fieldCheck !== false) {
+        const authoritative = validation?.fieldSetsByResource?.get(resourceKey) ?? fields;
+        for (const f of item.fields) {
+          if (!authoritative.includes(f)) {
+            problems.push(
+              `${at}.fields: "${f}" is not a field of ${resourceKey} \u2014 a hallucinated field is a shape error, not a silent projection-miss (exact vendor field names via operations.fieldCatalog)`
+            );
+          }
         }
       }
     }
   }
   if (problems.length > 0) {
     throw new AutotaskConfigError(
-      `fetchMany: ${problems.length} problem(s) found pre-request (zero wire was issued)
+      `${opName}: ${problems.length} problem(s) found pre-request (zero wire was issued)
 - ` + problems.join("\n- "),
       { suggestedAction: "Fix every item above and call again \u2014 validation covers the whole batch up-front (one round, zero wire)." }
     );
@@ -360,8 +365,38 @@ async function fetchMany(client, items, opts = {}) {
       throw new AutotaskConfigError(`fetchMany: maxItems must be an integer >= 1 (got ${String(opts.maxItems)})`);
     }
   }
+  if (opts.liveFields !== void 0 && typeof opts.liveFields !== "boolean") {
+    throw new AutotaskConfigError(`fetchMany: liveFields must be a boolean (got ${typeof opts.liveFields})`);
+  }
   const cap = Math.min(FETCH_MANY_MAX_ITEMS, opts.maxItems ?? FETCH_MANY_MAX_ITEMS);
-  validateFetchManyItems(items, cap);
+  if (opts.liveFields === true) {
+    validateFetchManyItems(items, cap, void 0, void 0, { fieldCheck: false });
+    const liveFieldSets = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const key = item.resource;
+      if (liveFieldSets.has(key)) continue;
+      const holder = client[camelKey(key)];
+      if (holder === void 0) {
+        throw new AutotaskConfigError(`fetchMany: the client exposes no accessor for resource "${key}"`, {
+          suggestedAction: "Rebuild the client from the SDK build that ships this registry (the resource set is pinned by the plan)."
+        });
+      }
+      try {
+        const rows = await holder.getFieldInfo();
+        const names = [];
+        for (const row of rows) {
+          if (typeof row.name === "string") names.push(row.name);
+        }
+        liveFieldSets.set(key, names.length > 0 ? names : null);
+      } catch (err) {
+        if (!isAutotaskError(err) || err.code === "ABORTED") throw err;
+        liveFieldSets.set(key, null);
+      }
+    }
+    validateFetchManyItems(items, cap, void 0, void 0, { fieldSetsByResource: liveFieldSets });
+  } else {
+    validateFetchManyItems(items, cap);
+  }
   const results = [];
   for (const item of items) {
     const key = item.resource;
@@ -391,6 +426,286 @@ async function fetchMany(client, items, opts = {}) {
   return { results, ok, failed: results.length - ok };
 }
 
+// src/operations/aggregate.ts
+var AGGREGATE_TOP_MAX = 100;
+var AGGREGATE_DEFAULT_TOP = 25;
+var AGGREGATE_DEFAULT_LIMIT = BOUNDED_QUERY_MAX_LIMIT;
+var QUERY_RESOURCE_KEYS = (() => {
+  const s = /* @__PURE__ */ new Set();
+  for (const rec of CAPABILITIES) if (rec.operation === "query") s.add(rec.resource);
+  return s;
+})();
+var AGGREGATE_OPT_KEYS = ["groupBy", "sum", "top", "limit"];
+var OP_RE = /^([a-z0-9_]+)\.query$/;
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+function validateAggregate(operation, filter, opts) {
+  const problems = [];
+  let resourceKey;
+  if (typeof operation !== "string" || !OP_RE.test(operation)) {
+    problems.push(
+      `operation must be exactly "<planResourceKey>.query" (the resource's bounded query op \u2014 e.g. "billing_items.query"); a special op, a ".count" row, or any other verb is not an aggregate surface \u2014 see autotask_catalog for the exact plan keys`
+    );
+  } else {
+    const key = OP_RE.exec(operation)[1];
+    resourceKey = key;
+    if (!QUERY_RESOURCE_KEYS.has(key)) {
+      problems.push(
+        `operation "${operation}": "${key}" has no query row in the capability registry (116 query surfaces) \u2014 see autotask_catalog for the exact plan keys`
+      );
+    }
+  }
+  let conditions = [];
+  if (filter === void 0 || filter === null) {
+    conditions = [];
+  } else {
+    const conds = Array.isArray(filter) ? filter : filter.filter;
+    if (!Array.isArray(conds)) {
+      problems.push("filter must be the query-bag filter (a conditions array, or { filter: [...] })");
+    } else if (conds.length === 0) {
+      conditions = [];
+    } else {
+      try {
+        conditions = buildFilter(conds).filter;
+      } catch (err) {
+        problems.push(err instanceof AutotaskConfigError ? err.message : `filter must be the query-bag filter (13 operators; caps 500 OR-conditions / 1 UDF / 8000 chars); ${String(err)}`);
+      }
+    }
+  }
+  if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
+    throw new AutotaskConfigError(
+      `aggregate: opts must be the options object (got ${Array.isArray(opts) ? "an array" : typeof opts})`,
+      { operation: "operations.aggregate" }
+    );
+  }
+  for (const key of Object.keys(opts ?? {})) {
+    if (!AGGREGATE_OPT_KEYS.includes(key)) {
+      problems.push(`unknown opts key "${key}" \u2014 the bag is closed: ${AGGREGATE_OPT_KEYS.join(", ")}`);
+    }
+  }
+  const fieldSets = resourceKey !== void 0 ? MODEL_FIELD_SETS[resourceKey] : void 0;
+  const checkFields = (name, fields) => {
+    if (fields === void 0) return [];
+    if (!Array.isArray(fields) || fields.length === 0 || fields.some((f) => typeof f !== "string" || f.trim() === "")) {
+      problems.push(`${name} must be a non-empty array of exact vendor field names (discover them via operations.fieldCatalog)`);
+      return [];
+    }
+    const out = [];
+    for (const f of fields) {
+      if (fieldSets === void 0 || !fieldSets.includes(f)) {
+        problems.push(`${name}: "${f}" is not a field of ${resourceKey} \u2014 a hallucinated field is a shape error, not a silent fold-miss (exact vendor field names via operations.fieldCatalog)`);
+      } else {
+        out.push(f);
+      }
+    }
+    return out;
+  };
+  const groupBy = checkFields("groupBy", opts.groupBy);
+  const sum = checkFields("sum", opts.sum);
+  let top = AGGREGATE_DEFAULT_TOP;
+  if (opts.top !== void 0) {
+    if (!Number.isInteger(opts.top)) {
+      problems.push(`top must be an integer (got ${String(opts.top)})`);
+    } else {
+      top = Math.min(Math.max(opts.top, 1), AGGREGATE_TOP_MAX);
+    }
+  }
+  let limit = AGGREGATE_DEFAULT_LIMIT;
+  if (opts.limit !== void 0) {
+    if (!Number.isInteger(opts.limit)) {
+      problems.push(`limit must be an integer (got ${String(opts.limit)})`);
+    } else {
+      limit = Math.min(Math.max(opts.limit, 1), BOUNDED_QUERY_MAX_LIMIT);
+    }
+  }
+  if (problems.length > 0) {
+    throw new AutotaskConfigError(
+      `aggregate: ${problems.length} problem(s) found pre-request (zero wire was issued)
+- ` + problems.join("\n- "),
+      { operation: "operations.aggregate" }
+    );
+  }
+  return { resourceKey, conditions, groupBy, sum, top, limit };
+}
+async function aggregate(client, operation, filter, opts = {}) {
+  const v = validateAggregate(operation, filter, opts);
+  const holder = client[camelKey(v.resourceKey)];
+  if (holder === void 0) {
+    throw new AutotaskConfigError(`aggregate: the client exposes no accessor for resource "${v.resourceKey}"`, {
+      operation: "operations.aggregate",
+      suggestedAction: "Rebuild the client from the SDK build that ships this registry (the resource set is pinned by the plan)."
+    });
+  }
+  const wireFilter = v.conditions.length === 0 ? void 0 : v.conditions;
+  if (v.groupBy.length === 0 && v.sum.length === 0) {
+    const raw = await holder.count({ filter: wireFilter });
+    const sentinel = typeof raw === "object" && raw !== null && "count" in raw ? raw : { count: raw };
+    const result2 = { mode: "count", count: sentinel.count, blind: sentinel.blindSurface !== void 0 };
+    if (sentinel.blindSurface !== void 0) result2.blindSurface = sentinel.blindSurface;
+    if (sentinel.emptyReason !== void 0) result2.emptyReason = sentinel.emptyReason;
+    return result2;
+  }
+  const res = await holder.queryBounded({ filter: wireFilter, limit: v.limit });
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of res.items) {
+    const key = {};
+    const values = [];
+    for (const f of v.groupBy) {
+      const value = item[f] === void 0 ? null : item[f];
+      key[f] = value;
+      values.push(value);
+    }
+    const keyOrder = JSON.stringify(values);
+    let g = groups.get(keyOrder);
+    if (g === void 0) {
+      g = { key, keyOrder, count: 0, ...v.sum.length > 0 ? { sums: {} } : {} };
+      groups.set(keyOrder, g);
+    }
+    g.count += 1;
+    if (g.sums !== void 0) {
+      for (const f of v.sum) g.sums[f] = (g.sums[f] ?? 0) + num(item[f]);
+    }
+  }
+  const sorted = [...groups.values()].sort((a, b) => b.count - a.count || (a.keyOrder < b.keyOrder ? -1 : a.keyOrder > b.keyOrder ? 1 : 0));
+  const top = sorted.slice(0, v.top);
+  const result = {
+    mode: v.groupBy.length > 0 ? "group" : "sum",
+    groups: top.map((g) => ({ key: g.key, count: g.count, ...g.sums !== void 0 ? { sums: g.sums } : {} })),
+    totalGroups: sorted.length,
+    groupsTruncated: sorted.length > top.length,
+    totalScanned: res.fetched,
+    hasMore: res.hasMore
+  };
+  if (res.blindSurface !== void 0) result.blindSurface = res.blindSurface;
+  if (res.emptyReason !== void 0) result.emptyReason = res.emptyReason;
+  return result;
+}
+
+// src/operations/fetchByIds.ts
+var FETCH_BY_IDS_MAX_ITEMS = 500;
+var FETCH_BY_IDS_CHUNK_SIZE = 250;
+function project2(value, fields) {
+  const out = {};
+  for (const f of fields) {
+    if (f in value) out[f] = value[f];
+  }
+  return out;
+}
+function resourcePathOf(key, holder) {
+  const path = holder?.resourcePath;
+  if (typeof path !== "string" || path === "") {
+    throw new AutotaskConfigError(`fetchByIds: the client exposes no ${key} resource path (registry drift)`, {
+      suggestedAction: "Rebuild the client from the SDK build that ships this registry (the resource set is pinned by the plan)."
+    });
+  }
+  return path;
+}
+async function fetchByIds(client, items, opts = {}) {
+  if (opts.maxItems !== void 0) {
+    if (!Number.isInteger(opts.maxItems) || opts.maxItems < 1) {
+      throw new AutotaskConfigError(`fetchByIds: maxItems must be an integer >= 1 (got ${String(opts.maxItems)})`);
+    }
+  }
+  const cap = Math.min(FETCH_BY_IDS_MAX_ITEMS, opts.maxItems ?? FETCH_BY_IDS_MAX_ITEMS);
+  validateFetchManyItems(items, cap, "fetchByIds", `FETCH_BY_IDS_MAX_ITEMS = ${FETCH_BY_IDS_MAX_ITEMS}`);
+  const groups = /* @__PURE__ */ new Map();
+  const canonical = [];
+  for (let i = 0; i < items.length; i += 1) {
+    const item = items[i];
+    const id = parseIdentifier(item.id, `items[${i}].id`);
+    canonical[i] = id;
+    const g = groups.get(item.resource) ?? { indices: [], fields: /* @__PURE__ */ new Set(), anyFields: false };
+    g.indices.push(i);
+    if (item.fields !== void 0) {
+      g.anyFields = true;
+      for (const f of item.fields) g.fields.add(f);
+    }
+    groups.set(item.resource, g);
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (const [key, group] of groups) {
+    const holder = client[camelKey(key)];
+    if (holder === void 0) {
+      throw new AutotaskConfigError(`fetchByIds: the client exposes no accessor for resource "${key}"`, {
+        suggestedAction: "Rebuild the client from the SDK build that ships this registry (the resource set is pinned by the plan)."
+      });
+    }
+    const resourcePath = resourcePathOf(key, holder);
+    const unique = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const i of group.indices) {
+      const k = String(canonical[i]);
+      if (!seen.has(k)) {
+        seen.add(k);
+        unique.push(canonical[i]);
+      }
+    }
+    const includeFields = group.anyFields && group.indices.every((i) => items[i].fields !== void 0) ? [...group.fields] : void 0;
+    const kOf = (id) => `${key}:${String(id)}`;
+    for (let c = 0; c < unique.length; c += FETCH_BY_IDS_CHUNK_SIZE) {
+      const chunk = unique.slice(c, c + FETCH_BY_IDS_CHUNK_SIZE);
+      const chunkKeys = new Set(chunk.map((id) => String(id)));
+      try {
+        const req = buildQueryRequest(client.http.baseUrl, resourcePath, {
+          filter: [{ field: "id", op: "in", value: chunk }],
+          maxRecords: FETCH_BY_IDS_CHUNK_SIZE,
+          includeFields
+        });
+        const res = await client.http.request({ ...req, operation: `${key}.fetchByIds` });
+        const { items: rows } = unwrapItems(res, `${key}.fetchByIds`);
+        for (const row of rows) {
+          const k = String(row.id);
+          if (!chunkKeys.has(k)) continue;
+          const q = kOf(k);
+          if (!byKey.has(q)) byKey.set(q, { found: true, value: row });
+        }
+      } catch (err) {
+        if (isAutotaskError(err) && err.code !== "ABORTED") {
+          const e = { code: err.code, message: err.message };
+          if (err.httpStatus !== void 0) e.httpStatus = err.httpStatus;
+          for (const u of chunk) {
+            const q = kOf(u);
+            if (!byKey.has(q)) byKey.set(q, { found: false, value: null, error: e });
+          }
+          continue;
+        }
+        throw err;
+      }
+    }
+    for (const id of unique) {
+      const k = kOf(id);
+      if (byKey.has(k)) continue;
+      try {
+        const value = await holder.get(id);
+        byKey.set(k, { found: true, value });
+      } catch (err) {
+        if (err instanceof NotFoundError) {
+          byKey.set(k, { found: false, value: null, error: { code: "NOT_FOUND", message: err.message } });
+        } else if (isAutotaskError(err) && err.code !== "ABORTED") {
+          const e = { code: err.code, message: err.message };
+          if (err.httpStatus !== void 0) e.httpStatus = err.httpStatus;
+          byKey.set(k, { found: false, value: null, error: e });
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+  const results = [];
+  for (let i = 0; i < items.length; i += 1) {
+    const item = items[i];
+    const id = canonical[i];
+    const out = byKey.get(`${item.resource}:${String(id)}`);
+    const value = out.found ? item.fields !== void 0 ? project2(out.value, item.fields) : out.value : null;
+    results.push(
+      out.found ? { resource: item.resource, id, found: true, value } : { resource: item.resource, id, found: false, value: null, error: out.error }
+    );
+  }
+  const ok = results.filter((r) => r.found).length;
+  return { results, ok, failed: results.length - ok };
+}
+
 // src/operations/relationshipMap.ts
 async function relationshipMap(client, resourceKey) {
   void client;
@@ -628,229 +943,6 @@ async function createGuidance(client, opts) {
   };
 }
 
-// src/operations/fieldCatalog.ts
-var MAX_FIELD_CATALOG_WIRE = 60;
-var FIELD_CATALOG_HONESTY_NOTE = "Live field metadata reports the SHAPE of a field (existence, requiredness, type, maxLength, read-only, queryable, picklist-ness) and serves picklist VALUES where the vendor exposes them. It cannot resolve a picklist VALUE the vendor does not expose to this API user (the W-A4 wall \u2014 e.g. the attachments Type picklist): retrying the catalog will not surface a withheld value; that gap is vendor-side, not a client defect.";
-var FIELD_CATALOG_OPT_KEYS = ["resources", "include", "fresh"];
-function projectFieldRow(raw) {
-  const r = typeof raw === "object" && raw !== null ? raw : {};
-  const name = typeof r.name === "string" ? r.name : "";
-  const type = typeof r.dataType === "string" ? r.dataType : typeof r.type === "string" ? r.type : "";
-  return {
-    name,
-    ...typeof r.label === "string" && r.label !== "" ? { label: r.label } : {},
-    type,
-    isRequired: r.isRequired === true,
-    isReadOnly: r.isReadOnly === true,
-    isQueryable: r.isQueryable === true,
-    isPickList: r.isPickList === true,
-    maxLength: typeof r.length === "number" ? r.length : null,
-    referenceEntityType: typeof r.referenceEntityType === "string" ? r.referenceEntityType : ""
-  };
-}
-function exposesPicklistValues(raw) {
-  const r = typeof raw === "object" && raw !== null ? raw : {};
-  return Array.isArray(r.picklistValues) && r.picklistValues.length > 0;
-}
-function capabilitySets() {
-  const fieldOps = /* @__PURE__ */ new Map();
-  const udfOps = /* @__PURE__ */ new Map();
-  const resources = /* @__PURE__ */ new Set();
-  for (const rec of CAPABILITIES) {
-    if (rec.resource === "operations") continue;
-    resources.add(rec.resource);
-    if (rec.operation === "getFieldInfo") fieldOps.set(rec.resource, rec);
-    if (rec.operation === "getUdfInfo") udfOps.set(rec.resource, rec);
-  }
-  return { fieldOps, udfOps, resources };
-}
-function apiEntityFor(rec) {
-  const m = /^GET \/V1\.0\/([^/]+)\/entityInformation\/fields$/.exec(rec.endpoint ?? "");
-  if (m === null) {
-    throw new AutotaskConfigError(
-      `fieldCatalog: the plan's getFieldInfo endpoint for "${rec.resource}" has no /V1.0/<Entity>/entityInformation/fields shape (${rec.endpoint}) \u2014 plan defect`,
-      { operation: "operations.fieldCatalog" }
-    );
-  }
-  return m[1];
-}
-async function fieldCatalog(client, opts) {
-  if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
-    throw new AutotaskConfigError(
-      "fieldCatalog: opts must be an object { resources?: string[], include?: (info|fields|udf)[], fresh?: boolean }"
-    );
-  }
-  for (const key of Object.keys(opts ?? {})) {
-    if (!FIELD_CATALOG_OPT_KEYS.includes(key)) {
-      throw new AutotaskConfigError(
-        `fieldCatalog: unknown opts key "${key}" \u2014 the bag is closed: ${FIELD_CATALOG_OPT_KEYS.join(", ")}`,
-        { suggestedAction: "Drop the unknown key (autotask_describe(operations.fieldCatalog) shows the exact bag)." }
-      );
-    }
-  }
-  const { fieldOps, udfOps, resources: allResources } = capabilitySets();
-  const includeRaw = opts?.include ?? ["fields"];
-  if (!Array.isArray(includeRaw) || includeRaw.length === 0) {
-    throw new AutotaskConfigError("fieldCatalog: opts.include must be a non-empty array of (info|fields|udf)");
-  }
-  const include = [];
-  for (const kind of includeRaw) {
-    if (typeof kind !== "string" || !FIELD_CACHE_KINDS.includes(kind)) {
-      throw new AutotaskConfigError(
-        `fieldCatalog: unknown include kind "${String(kind)}" \u2014 the valid kinds are: ${FIELD_CACHE_KINDS.join(", ")}`,
-        { suggestedAction: `Filter with one or more of: ${FIELD_CACHE_KINDS.join(", ")} (default ['fields']).` }
-      );
-    }
-    if (!include.includes(kind)) include.push(kind);
-  }
-  const resourcesRaw = opts?.resources ?? WORKFLOW_RESOURCES;
-  if (!Array.isArray(resourcesRaw) || resourcesRaw.length === 0) {
-    throw new AutotaskConfigError("fieldCatalog: opts.resources must be a non-empty array of plan resource keys");
-  }
-  const targets = [];
-  for (const r of resourcesRaw) {
-    if (typeof r !== "string" || r.trim() === "") {
-      throw new AutotaskConfigError(
-        `fieldCatalog: opts.resources must contain non-empty plan resource key strings (got ${typeof r === "string" && r.trim() === "" ? "a blank string" : typeof r})`
-      );
-    }
-    const key = r.trim();
-    const fieldOp = fieldOps.get(key);
-    if (fieldOp === void 0) {
-      if (allResources.has(key)) {
-        throw new AutotaskConfigError(
-          `fieldCatalog: resource "${key}" has no field catalog \u2014 the vendor defines the entityInformation trio for the ${fieldOps.size} plan entity resources only`,
-          { suggestedAction: `Pass one of the ${fieldOps.size} field-capable plan keys (list them with autotask_catalog).` }
-        );
-      }
-      throw new AutotaskError(
-        `fieldCatalog: unknown resource "${key}" \u2014 the plan has ${fieldOps.size} field-capable resources`,
-        {
-          code: "RESOURCE_UNKNOWN",
-          category: "validation",
-          suggestedAction: "Pass the exact plan resource key (snake_case) from autotask_catalog (e.g. tickets, companies, configuration_items)."
-        }
-      );
-    }
-    if (!targets.includes(key)) targets.push(key);
-  }
-  const cost = targets.length * include.length;
-  if (cost > MAX_FIELD_CATALOG_WIRE) {
-    throw new AutotaskConfigError(
-      `fieldCatalog: ${targets.length} resource(s) \xD7 ${include.length} kind(s) = ${cost} metadata reads exceed the wire cap of ${MAX_FIELD_CATALOG_WIRE} \u2014 the call is refused above its cap (never truncated)`,
-      { suggestedAction: `Pass a smaller resources list or a narrower include set so the product stays \u2264 ${MAX_FIELD_CATALOG_WIRE}.` }
-    );
-  }
-  const cache = client.http.fieldCache;
-  const fresh = opts?.fresh === true;
-  const zone = client.config.zone ?? "unknown";
-  const rows = [];
-  let wireUsed = 0;
-  let anyPicklistValues = false;
-  for (const resource of targets) {
-    const fieldOp = fieldOps.get(resource);
-    if (fieldOp === void 0) continue;
-    const apiEntity = apiEntityFor(fieldOp);
-    const holder = client[camelKey(resource)];
-    const row = {
-      resource,
-      apiEntity,
-      udfCapable: udfOps.has(resource),
-      required: [],
-      readOnly: [],
-      queryable: [],
-      picklistFields: [],
-      cache: { hit: false, age: null },
-      wire: 0,
-      error: null
-    };
-    const fetches = {
-      info: () => holder?.getEntityInfo?.() ?? Promise.reject(new AutotaskError(`fieldCatalog: the client exposes no getEntityInfo read for "${resource}"`, { code: "INVALID_RESPONSE", category: "server" })),
-      fields: () => holder?.getFieldInfo?.() ?? Promise.reject(new AutotaskError(`fieldCatalog: the client exposes no getFieldInfo read for "${resource}"`, { code: "INVALID_RESPONSE", category: "server" })),
-      udf: () => holder?.getUdfInfo?.() ?? Promise.reject(new AutotaskError(`fieldCatalog: the client exposes no getUdfInfo read for "${resource}"`, { code: "INVALID_RESPONSE", category: "server" }))
-    };
-    if (fresh) cache?.invalidate(resource);
-    let allCached = true;
-    const ages = [];
-    for (const kind of include) {
-      const peek = cache !== void 0 && !fresh ? cache.peek(resource, kind) : { hit: false, age: null };
-      if (peek.hit !== true) allCached = false;
-      if (peek.hit === true && cache !== void 0) {
-        const value2 = cache.get(resource, kind);
-        if (kind === "info") row.info = value2 ?? null;
-        else {
-          const list = Array.isArray(value2) ? value2 : [];
-          const projected = list.map((f) => projectFieldRow(f));
-          if (kind === "fields") row.fields = projected;
-          else row.udf = projected;
-          for (const f of list) if (exposesPicklistValues(f)) anyPicklistValues = true;
-          if (kind === "fields") {
-            row.required = projected.filter((f) => f.isRequired).map((f) => f.name);
-            row.readOnly = projected.filter((f) => f.isReadOnly).map((f) => f.name);
-            row.queryable = projected.filter((f) => f.isQueryable).map((f) => f.name);
-            row.picklistFields = projected.filter((f) => f.isPickList).map((f) => f.name);
-          }
-        }
-        if (peek.age !== null) ages.push(peek.age);
-        continue;
-      }
-      let value;
-      try {
-        value = await fetches[kind]();
-      } catch (err) {
-        wireUsed += 1;
-        row.wire += 1;
-        if (row.error === null) {
-          const code = isAutotaskError(err) ? err.code : "NETWORK_ERROR";
-          const message = err instanceof Error ? err.message : String(err);
-          row.error = { code, message };
-        }
-        continue;
-      }
-      wireUsed += 1;
-      row.wire += 1;
-      if (kind === "info") {
-        row.info = value ?? null;
-      } else {
-        const list = Array.isArray(value) ? value : [];
-        const projected = list.map((f) => projectFieldRow(f));
-        if (kind === "fields") row.fields = projected;
-        else row.udf = projected;
-        for (const f of list) if (exposesPicklistValues(f)) anyPicklistValues = true;
-        if (kind === "fields") {
-          row.required = projected.filter((f) => f.isRequired).map((f) => f.name);
-          row.readOnly = projected.filter((f) => f.isReadOnly).map((f) => f.name);
-          row.queryable = projected.filter((f) => f.isQueryable).map((f) => f.name);
-          row.picklistFields = projected.filter((f) => f.isPickList).map((f) => f.name);
-        }
-      }
-    }
-    row.cache = allCached ? { hit: true, age: ages.length > 0 ? Math.max(...ages) : 0 } : { hit: false, age: null };
-    rows.push(row);
-  }
-  return {
-    zone,
-    label: zone,
-    cached: cache !== void 0,
-    ttlMs: cache?.ttlMs ?? null,
-    fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    rows,
-    wireUsed,
-    cap: MAX_FIELD_CATALOG_WIRE,
-    truncated: false,
-    counts: {
-      resources: targets.length,
-      fieldCapableResources: fieldOps.size,
-      udfCapableResources: udfOps.size,
-      cached: rows.filter((r) => r.cache.hit === true).length
-    },
-    honesty: {
-      picklistValues: anyPicklistValues ? "partial" : "unexposed",
-      note: FIELD_CATALOG_HONESTY_NOTE
-    }
-  };
-}
-
 // src/operations/recovery.ts
 var RECOVERY_CONFIRM = "operations.recovery";
 var RECOVERY_DEFAULT_LIMIT = 25;
@@ -1211,12 +1303,14 @@ function validateDispatchArgs(record, argsIn) {
   }
 }
 var PARAMS_BAG_KEYS = {
-  query: ["filter", "limit", "includeFields", "via"],
+  query: ["filter", "limit", "includeFields", "via", "latest", "noteChars", "fieldsPreset"],
   queryAll: ["filter", "maxRecords", "includeFields", "maxTotalRecords", "via"],
   count: ["filter"]
 };
 var BAG_KEY_SYNONYMS = {
   filters: "filter",
+  last: "latest",
+  // issue #59: the expected typo class (honoured only on `query`)
   lmit: "limit",
   page: "limit",
   pageSize: "limit",
@@ -1330,11 +1424,29 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
   validateParamsBag(record, args);
   const boundedQuery = record.kind === "primitive" && record.operation === "query";
   let holder = client[camelKey(record.resource)];
+  if (typeof holder === "function") {
+    holder = client[`${camelKey(record.resource)}Resource`] ?? holder;
+  }
   if (holder === void 0 && record.resource === "operations") {
     holder = {
       resolveAny: (identifier, opts2) => resolveAny(client, identifier, opts2),
       searchAcrossResources: (query, opts2) => searchAcrossResources(client, query, opts2),
       fetchMany: (items, opts2) => fetchMany(client, items, opts2),
+      // Issue #62: the generic aggregate + the cheap count — the
+      // groupBy/sum-absent mode is ONE vendor /query/count (the S12-C blind
+      // sentinel rides through); the group/sum modes walk the named
+      // <resource>.query op via the house bounded walk and fold client-side
+      // (truncation honesty: hasMore/totalScanned — no silent partial sums).
+      aggregate: (operation2, filter, opts2) => aggregate(client, operation2, filter, opts2),
+      // Issue #59 PR-B: the bulk fetch by ids — query-first chunked `id in`
+      // reads + the per-id `get` fallback (blind-surface-safe; per-item
+      // typed outcomes reuse the fetchMany shapes).
+      fetchByIds: (items, opts2) => fetchByIds(client, items, opts2),
+      // Issue #65: opt-in resource name expansion — per-id resources.get
+      // reads ONLY (never an id-in query — the resources table can be blind
+      // to count/query while per-id reads work); blind-marked rows for ids
+      // the API user cannot resolve; the name cache (default-on).
+      expandResourceNames: (ids, opts2) => expandResourceNames(client, ids, opts2),
       relationshipMap: (resourceKey) => relationshipMap(client, resourceKey),
       // Issue #11: the served blind-surface inventory (zero wire) + the
       // bounded caller-opted reachability sweep (read-only, confirmProbe-
@@ -1425,20 +1537,30 @@ async function invokeDelete(client, operation, args = [], opts = {}) {
   return invokeMode(client, operation, args, { ...opts, mode: "delete" });
 }
 export {
+  AGGREGATE_DEFAULT_LIMIT,
+  AGGREGATE_DEFAULT_TOP,
+  AGGREGATE_TOP_MAX,
   BLIND_SURFACE_KINDS,
   CREATE_BLOCKER_KINDS,
+  EXPAND_RESOURCE_NAMES_MAX_IDS,
+  FETCH_BY_IDS_CHUNK_SIZE,
+  FETCH_BY_IDS_MAX_ITEMS,
   FETCH_MANY_MAX_ITEMS,
   FIELD_CACHE_KINDS,
   FIELD_CATALOG_HONESTY_NOTE,
   INVOKE_OPTION_KEYS,
   MAX_FIELD_CATALOG_WIRE,
   PARAMS_BAG_KEYS,
+  PICKLIST_VALUE_NOT_SERVED_NOTE,
   RECOVERY_CONFIRM,
   RECOVERY_DEFAULT_LIMIT,
   RECOVERY_MAX_LIMIT,
   WORKFLOW_RESOURCES,
+  aggregate,
   blindSurfaces,
   createGuidance,
+  expandResourceNames,
+  fetchByIds,
   fetchMany,
   fieldCatalog,
   invoke,
@@ -1457,4 +1579,3 @@ export {
   validateInvokeOptions,
   validateParamsBag
 };
-//# sourceMappingURL=index.js.map