node-autotask 0.21.0 → 0.24.0

package/dist/operations/index.js

@@ -24,8 +24,10 @@ import {
   RELATIONSHIP_MAP,
   RELATIONSHIP_ZONE,
   RecoveryTruncatedError,
+  UI_LINK_ENTITIES,
   WORKFLOW_RESOURCES,
   buildFilter,
+  buildUiLink,
   camelKey,
   clampPageSize,
   expandResourceNames,
@@ -34,13 +36,14 @@ import {
   fieldCatalog,
   isAutotaskError,
   isRecord,
-  normalizedConditions,
   parseIdentifier,
-  validateFetchManyItems
-} from "../chunk-KD6LOSAK.js";
+  uiLink,
+  validateFetchManyItems,
+  validateQueryFieldNames
+} from "../chunk-BBQBWVBE.js";
 import {
   CAPABILITIES
-} from "../chunk-DM67SXCO.js";
+} from "../chunk-WJD26CPN.js";
 
 // src/operations/searchAcrossResources.ts
 var DEFAULT_LIMIT = 25;
@@ -57,19 +60,35 @@ async function searchAcrossResources(client, query, opts = {}) {
     throw new AutotaskConfigError("searchAcrossResources: no resources requested");
   }
   const limit = clampPageSize(opts.limit ?? DEFAULT_LIMIT);
+  const totalLimit = opts.totalLimit;
+  if (totalLimit !== void 0 && !(Number.isInteger(totalLimit) && totalLimit >= 1)) {
+    throw new AutotaskConfigError("searchAcrossResources: totalLimit must be a positive integer");
+  }
   const results = [];
   const skipped = [];
+  const notSearched = [];
+  let remaining = totalLimit ?? Infinity;
+  let hitQuota = false;
   for (const key of keys) {
     const holder = resourceFor(client, key);
     if (holder === void 0 || typeof holder.search !== "function") {
       skipped.push(key);
       continue;
     }
-    const matches = await holder.search(text, { limit });
+    if (remaining <= 0) {
+      notSearched.push(key);
+      continue;
+    }
+    const ask = Math.min(limit, remaining);
+    const matches = await holder.search(text, { limit: ask });
     const rows = Array.isArray(matches) ? matches.filter((m) => typeof m === "object" && m !== null).map((m) => m) : [];
+    if (totalLimit !== void 0) rows.length = Math.min(rows.length, ask);
     results.push({ resource: key, matches: rows });
+    remaining -= rows.length;
+    if (rows.length === ask) hitQuota = true;
   }
-  return { query: text, results, skipped };
+  if (totalLimit === void 0) return { query: text, results, skipped };
+  return { query: text, results, skipped, notSearched, truncated: notSearched.length > 0 || hitQuota };
 }
 
 // src/operations/resolveAny.ts
@@ -213,39 +232,41 @@ 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;
+function parseOperationKey(operation, problems) {
   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`
-      );
-    }
+    return void 0;
+  }
+  const key = OP_RE.exec(operation)[1];
+  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 = [];
+  return key;
+}
+function parseFilterConditions(filter, problems) {
   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)}`);
-      }
-    }
+    return [];
+  }
+  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: [...] })");
+    return [];
   }
+  if (conds.length === 0) {
+    return [];
+  }
+  try {
+    return 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)}`);
+    return [];
+  }
+}
+function checkOptsBag(opts, problems) {
   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})`,
@@ -257,58 +278,63 @@ function validateAggregate(operation, filter, opts) {
       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 dateSets = resourceKey !== void 0 ? MODEL_DATE_FIELDS[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 [];
+}
+function checkSumFields(name, fields, oracles, problems) {
+  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 (oracles.fieldSets === void 0 || !oracles.fieldSets.includes(f)) {
+      problems.push(`${name}: "${f}" is not a field of ${oracles.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);
     }
-    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;
+}
+function parseGroupSpec(f, oracles, problems) {
+  const { resourceKey, fieldSets, dateSets } = oracles;
+  const at = f.indexOf("@");
+  if (at === -1) {
+    if (fieldSets === void 0 || !fieldSets.includes(f)) {
+      problems.push(`groupBy: "${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)`);
+      return void 0;
     }
-    return out;
-  };
+    return { name: f, base: f };
+  }
+  const base = f.slice(0, at);
+  const suffix = f.slice(at + 1);
+  if (!AGGREGATE_DATE_BUCKETS.includes(suffix)) {
+    problems.push(`groupBy: "${f}": unknown bucket suffix "${suffix}" \u2014 the closed set is month | week | year (the suffix applies to date-typed fields only)`);
+    return void 0;
+  }
+  if (fieldSets === void 0 || !fieldSets.includes(base)) {
+    problems.push(`groupBy: "${f}": "${base}" 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)`);
+    return void 0;
+  }
+  if (dateSets === void 0 || !dateSets.includes(base)) {
+    problems.push(`groupBy: "${f}": "${base}" is not a date field of ${resourceKey} (the @month/@week/@year bucket suffix applies to date-typed fields of the resource's vendored model \u2014 exact vendor field names via operations.fieldCatalog)`);
+    return void 0;
+  }
+  return { name: f, base, bucket: suffix };
+}
+function parseGroupBy(opts, oracles, problems) {
   const groupBy = [];
-  if (opts.groupBy !== void 0) {
-    if (!Array.isArray(opts.groupBy) || opts.groupBy.length === 0 || opts.groupBy.some((f) => typeof f !== "string" || f.trim() === "")) {
-      problems.push("groupBy must be a non-empty array of exact vendor field names (a date-typed field may carry the closed bucket suffix @month | @week | @year \u2014 discover them via operations.fieldCatalog)");
-    } else {
-      for (const f of opts.groupBy) {
-        const at = f.indexOf("@");
-        if (at === -1) {
-          if (fieldSets === void 0 || !fieldSets.includes(f)) {
-            problems.push(`groupBy: "${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 {
-            groupBy.push({ name: f, base: f });
-          }
-          continue;
-        }
-        const base = f.slice(0, at);
-        const suffix = f.slice(at + 1);
-        if (!AGGREGATE_DATE_BUCKETS.includes(suffix)) {
-          problems.push(`groupBy: "${f}": unknown bucket suffix "${suffix}" \u2014 the closed set is month | week | year (the suffix applies to date-typed fields only)`);
-          continue;
-        }
-        if (fieldSets === void 0 || !fieldSets.includes(base)) {
-          problems.push(`groupBy: "${f}": "${base}" 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)`);
-          continue;
-        }
-        if (dateSets === void 0 || !dateSets.includes(base)) {
-          problems.push(`groupBy: "${f}": "${base}" is not a date field of ${resourceKey} (the @month/@week/@year bucket suffix applies to date-typed fields of the resource's vendored model \u2014 exact vendor field names via operations.fieldCatalog)`);
-          continue;
-        }
-        groupBy.push({ name: f, base, bucket: suffix });
-      }
-    }
+  if (opts.groupBy === void 0) return groupBy;
+  if (!Array.isArray(opts.groupBy) || opts.groupBy.length === 0 || opts.groupBy.some((f) => typeof f !== "string" || f.trim() === "")) {
+    problems.push("groupBy must be a non-empty array of exact vendor field names (a date-typed field may carry the closed bucket suffix @month | @week | @year \u2014 discover them via operations.fieldCatalog)");
+    return groupBy;
+  }
+  for (const f of opts.groupBy) {
+    const spec = parseGroupSpec(f, oracles, problems);
+    if (spec !== void 0) groupBy.push(spec);
   }
-  const sum = checkFields("sum", opts.sum);
+  return groupBy;
+}
+function parseTopAndLimit(opts, problems) {
   let top = AGGREGATE_DEFAULT_TOP;
   if (opts.top !== void 0) {
     if (!Number.isInteger(opts.top)) {
@@ -325,6 +351,21 @@ function validateAggregate(operation, filter, opts) {
       limit = Math.min(Math.max(opts.limit, 1), BOUNDED_QUERY_MAX_LIMIT);
     }
   }
+  return { top, limit };
+}
+function validateAggregate(operation, filter, opts) {
+  const problems = [];
+  const resourceKey = parseOperationKey(operation, problems);
+  const conditions = parseFilterConditions(filter, problems);
+  checkOptsBag(opts, problems);
+  const oracles = {
+    resourceKey,
+    fieldSets: resourceKey !== void 0 ? MODEL_FIELD_SETS[resourceKey] : void 0,
+    dateSets: resourceKey !== void 0 ? MODEL_DATE_FIELDS[resourceKey] : void 0
+  };
+  const groupBy = parseGroupBy(opts, oracles, problems);
+  const sum = checkSumFields("sum", opts.sum, oracles, problems);
+  const { top, limit } = parseTopAndLimit(opts, problems);
   if (problems.length > 0) {
     throw new AutotaskConfigError(
       `aggregate: ${problems.length} problem(s) found pre-request (zero wire was issued)
@@ -334,27 +375,9 @@ function validateAggregate(operation, filter, opts) {
   }
   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 });
+function foldGroups(items, v) {
   const groups = /* @__PURE__ */ new Map();
-  for (const item of res.items) {
+  for (const item of items) {
     const key = {};
     const values = [];
     for (const spec of v.groupBy) {
@@ -374,7 +397,28 @@ async function aggregate(client, operation, filter, opts = {}) {
       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));
+  return [...groups.values()].sort((a, b) => b.count - a.count || (a.keyOrder < b.keyOrder ? -1 : a.keyOrder > b.keyOrder ? 1 : 0));
+}
+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 sorted = foldGroups(res.items, v);
   const top = sorted.slice(0, v.top);
   const result = {
     mode: v.groupBy.length > 0 ? "group" : "sum",
@@ -646,8 +690,7 @@ function parseMatchId(record) {
   }
   return { id: null, unsafe: true };
 }
-async function recovery(client, input, opts = {}) {
-  const operation = RECOVERY_CONFIRM;
+function validateRecoveryInput(input, operation) {
   if (!isRecord(input)) {
     configError(
       `recovery: input must be an object { resource, marker, ... } (got ${typeof input})`,
@@ -679,6 +722,9 @@ async function recovery(client, input, opts = {}) {
       "Pass action: 'delete' for the destructive path (dry-run-first; the apply requires the confirm string)."
     );
   }
+  return { resource, marker, action };
+}
+function resolveRecoveryTarget(client, resource, operation) {
   const entry = RELATIONSHIP_MAP[resource];
   if (entry === void 0) {
     throw new AutotaskError(
@@ -699,6 +745,9 @@ async function recovery(client, input, opts = {}) {
       "Use a resource with a query surface, or address the record by id directly (get/fetchMany)."
     );
   }
+  return { entry, holder };
+}
+function resolveMarkerField(input, resource, operation) {
   const field = input.field !== void 0 ? String(input.field) : MARKER_FIELDS[resource];
   if (typeof field !== "string" || field.trim() === "") {
     configError(
@@ -707,55 +756,126 @@ async function recovery(client, input, opts = {}) {
       "Pass input.field \u2014 a name-like vendor field the marker was stamped into (see the resource model in autotask_describe / autotask_catalog)."
     );
   }
-  let parentId;
-  if (input.parentId !== void 0) {
-    if (!Number.isInteger(input.parentId) || input.parentId < 0) {
-      configError(
-        `recovery: input.parentId must be a non-negative integer (got ${String(input.parentId)})`,
-        operation,
-        "Pass the parent record id (e.g. the ticket id for a ticket note)."
-      );
-    }
-    parentId = input.parentId;
-    if (entry.parent === null || entry.parent.field === null) {
-      configError(
-        `recovery: ${resource} is not a parent-scoped child resource \u2014 input.parentId does not apply`,
-        operation,
-        `Drop input.parentId (the search runs unscoped), or pass the child resource that IS scoped under ${resource}.`
-      );
-    }
+  return field;
+}
+function resolveParentId(input, entry, resource, operation) {
+  if (input.parentId === void 0) return void 0;
+  if (!Number.isInteger(input.parentId) || input.parentId < 0) {
+    configError(
+      `recovery: input.parentId must be a non-negative integer (got ${String(input.parentId)})`,
+      operation,
+      "Pass the parent record id (e.g. the ticket id for a ticket note)."
+    );
+  }
+  if (entry.parent === null || entry.parent.field === null) {
+    configError(
+      `recovery: ${resource} is not a parent-scoped child resource \u2014 input.parentId does not apply`,
+      operation,
+      `Drop input.parentId (the search runs unscoped), or pass the child resource that IS scoped under ${resource}.`
+    );
   }
+  return input.parentId;
+}
+function resolveExtraFilter(input, operation) {
   const extra = [];
-  if (input.filter !== void 0) {
-    if (!Array.isArray(input.filter)) {
+  if (input.filter === void 0) return extra;
+  if (!Array.isArray(input.filter)) {
+    configError(
+      `recovery: input.filter must be an array of leaf filter conditions (got ${typeof input.filter})`,
+      operation,
+      "Pass e.g. [{ field: 'status', op: 'eq', value: 'open' }] \u2014 leaf conditions only."
+    );
+  }
+  for (const c of input.filter) {
+    if (!isRecord(c) || typeof c.op !== "string" || c.op === "and" || c.op === "or") {
       configError(
-        `recovery: input.filter must be an array of leaf filter conditions (got ${typeof input.filter})`,
+        "recovery: input.filter accepts only plain leaf conditions ({ field, op, value }) \u2014 no grouping",
         operation,
-        "Pass e.g. [{ field: 'status', op: 'eq', value: 'open' }] \u2014 leaf conditions only."
+        "Pass flat leaf conditions; grouping operators are not supported here."
       );
     }
-    for (const c of input.filter) {
-      if (!isRecord(c) || typeof c.op !== "string" || c.op === "and" || c.op === "or") {
-        configError(
-          "recovery: input.filter accepts only plain leaf conditions ({ field, op, value }) \u2014 no grouping",
-          operation,
-          "Pass flat leaf conditions; grouping operators are not supported here."
-        );
-      }
-      extra.push(c);
-    }
+    extra.push(c);
   }
-  let limit = RECOVERY_DEFAULT_LIMIT;
-  if (input.limit !== void 0) {
-    if (!Number.isInteger(input.limit) || input.limit < 1 || input.limit > RECOVERY_MAX_LIMIT) {
-      configError(
-        `recovery: input.limit must be an integer 1..${RECOVERY_MAX_LIMIT} (got ${String(input.limit)})`,
+  return extra;
+}
+function resolveLimit(input, operation) {
+  if (input.limit === void 0) return RECOVERY_DEFAULT_LIMIT;
+  if (!Number.isInteger(input.limit) || input.limit < 1 || input.limit > RECOVERY_MAX_LIMIT) {
+    configError(
+      `recovery: input.limit must be an integer 1..${RECOVERY_MAX_LIMIT} (got ${String(input.limit)})`,
+      operation,
+      `Raise the marker precision instead of the cap, or pass limit up to ${RECOVERY_MAX_LIMIT}.`
+    );
+  }
+  return input.limit;
+}
+async function applyRecoveryDeletes(holder, matches, parentId, resource, operation) {
+  const deleteMethod = holder.delete;
+  if (deleteMethod === void 0) {
+    throw new DeleteBoundaryError(
+      `recovery: ${resource} has no delete method on the client \u2014 the boundary is marked available in the plan but the typed delete surface is missing`,
+      {
         operation,
-        `Raise the marker precision instead of the cap, or pass limit up to ${RECOVERY_MAX_LIMIT}.`
-      );
+        suggestedAction: "Report the registry drift (plan says deletable, client exposes no delete) \u2014 or clean up via the Autotask UI.",
+        details: { resource }
+      }
+    );
+  }
+  const deleted = [];
+  for (const match of matches) {
+    const id = match.id;
+    let verify = "error";
+    let code;
+    try {
+      if (parentId !== void 0) {
+        await deleteMethod.call(holder, parentId, id, { dryRun: false });
+      } else {
+        await deleteMethod.call(holder, id, { dryRun: false });
+      }
+      try {
+        if (parentId !== void 0) {
+          await holder.get.call(holder, parentId, id);
+          verify = "still-present";
+        } else {
+          await holder.get.call(holder, id);
+          verify = "still-present";
+        }
+      } catch (err) {
+        if (err instanceof NotFoundError) verify = "not-found";
+        else {
+          verify = "error";
+          code = isAutotaskError(err) ? err.code : "SERVER_ERROR";
+        }
+      }
+    } catch (err) {
+      code = isAutotaskError(err) ? err.code : "SERVER_ERROR";
     }
-    limit = input.limit;
+    deleted.push({ id, verified: verify === "not-found", code });
   }
+  return deleted;
+}
+function collectMatches(items, field) {
+  const matches = [];
+  const unsafeIds = [];
+  items.forEach((record, idx) => {
+    const parsed = parseMatchId(record);
+    if (parsed.unsafe) unsafeIds.push(idx);
+    const value = record[field];
+    matches.push({
+      id: parsed.id,
+      value: typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : null
+    });
+  });
+  return { matches, unsafeIds };
+}
+async function recovery(client, input, opts = {}) {
+  const operation = RECOVERY_CONFIRM;
+  const { resource, marker, action } = validateRecoveryInput(input, operation);
+  const { entry, holder } = resolveRecoveryTarget(client, resource, operation);
+  const field = resolveMarkerField(input, resource, operation);
+  const parentId = resolveParentId(input, entry, resource, operation);
+  const extra = resolveExtraFilter(input, operation);
+  const limit = resolveLimit(input, operation);
   const boundaryNote = DELETE_BOUNDARY_NOTES[resource];
   const boundary = {
     available: boundaryNote === void 0,
@@ -805,17 +925,7 @@ async function recovery(client, input, opts = {}) {
       }
     );
   }
-  const matches = [];
-  const unsafeIds = [];
-  query.items.forEach((record, idx) => {
-    const parsed = parseMatchId(record);
-    if (parsed.unsafe) unsafeIds.push(idx);
-    const value = record[field];
-    matches.push({
-      id: parsed.id,
-      value: typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : null
-    });
-  });
+  const { matches, unsafeIds } = collectMatches(query.items, field);
   const unsafeId = unsafeIds.length > 0;
   const base = {
     resource,
@@ -844,54 +954,11 @@ async function recovery(client, input, opts = {}) {
       }
     );
   }
-  const deleteMethod = holder.delete;
-  if (deleteMethod === void 0) {
-    throw new DeleteBoundaryError(
-      `recovery: ${resource} has no delete method on the client \u2014 the boundary is marked available in the plan but the typed delete surface is missing`,
-      {
-        operation,
-        suggestedAction: "Report the registry drift (plan says deletable, client exposes no delete) \u2014 or clean up via the Autotask UI.",
-        details: { resource }
-      }
-    );
-  }
-  const deleted = [];
-  for (const match of matches) {
-    const id = match.id;
-    let verify = "error";
-    let code;
-    try {
-      if (parentId !== void 0) {
-        await deleteMethod.call(holder, parentId, id, { dryRun: false });
-      } else {
-        await deleteMethod.call(holder, id, { dryRun: false });
-      }
-      try {
-        if (parentId !== void 0) {
-          await holder.get.call(holder, parentId, id);
-          verify = "still-present";
-        } else {
-          await holder.get.call(holder, id);
-          verify = "still-present";
-        }
-      } catch (err) {
-        if (err instanceof NotFoundError) verify = "not-found";
-        else {
-          verify = "error";
-          code = isAutotaskError(err) ? err.code : "SERVER_ERROR";
-        }
-      }
-    } catch (err) {
-      code = isAutotaskError(err) ? err.code : "SERVER_ERROR";
-    }
-    deleted.push({ id, verified: verify === "not-found", code });
-  }
+  const deleted = await applyRecoveryDeletes(holder, matches, parentId, resource, operation);
   return { ...base, deleted, dryRun: false };
 }
 
-// src/operations/invoke.ts
-var RECORDS = CAPABILITIES;
-var byId = new Map(RECORDS.map((r) => [r.id, r]));
+// src/operations/invoke/modes.ts
 function needsConfirmation(record) {
   return record.effect === "destructive" || (record.flags ?? []).includes("requiresApproval");
 }
@@ -924,6 +991,8 @@ function crossModeRefusal(operation, effect, mode) {
   const target = actual === "read" ? `Route it through the read mode (${MODE_SDK[actual]} / ${MODE_TOOL[actual]}).` : actual === "write" ? `Route it through the write mode (${MODE_SDK[actual]} / ${MODE_TOOL[actual]} \u2014 dry-run first).` : `Deletes have their own tool (${MODE_TOOL[actual]}) and require confirm: "${operation}".`;
   return `invoke: "${operation}" is ${subject} (effect=${effect}) \u2014 refused on the ${mode} path (${MODE_TOOL[mode]} routes effect=${MODE_EFFECT[mode]} operations only). ${target}`;
 }
+
+// src/operations/invoke/validate.ts
 function isSafeNonNegativeInteger(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
@@ -957,8 +1026,11 @@ function validateDispatchArgs(record, argsIn) {
   const schema = record.inputSchema ?? {};
   const names = Object.keys(schema);
   if (args.length > names.length) {
+    const bagName = names.find((n) => schema[n].properties);
+    const surplus = args[names.length];
+    const bagHint = bagName && surplus !== null && typeof surplus === "object" && !Array.isArray(surplus) ? ` \u2014 options go inside the single ${bagName} object` : "";
     throw new AutotaskConfigError(
-      `invoke: "${operation}" declares ${names.length} positional arg(s) (${declaredArgList(record)}) but ${args.length} were passed \u2014 extra args are refused, not dropped (v0.2.0 silently dropped them)`,
+      `invoke: "${operation}" declares ${names.length} positional arg(s) (${declaredArgList(record)}) but ${args.length} were passed \u2014 extra args are refused${bagHint}`,
       {
         operation,
         suggestedAction: `Pass exactly the declared args in order (${declaredArgList(record)}); dryRun/confirm/lastModifiedDate travel through the invoke options, never the args.`
@@ -985,6 +1057,8 @@ function validateDispatchArgs(record, argsIn) {
     }
   }
 }
+
+// src/operations/invoke/inputSets.ts
 var PARAMS_BAG_KEYS = {
   query: ["filter", "limit", "includeFields", "via", "latest", "noteChars", "fieldsPreset", "fieldCheck"],
   // No registry row DECLARES `queryAll` today (a plan decision: the raw walk is
@@ -1050,116 +1124,6 @@ function validateParamsBag(record, args) {
     }
   );
 }
-async function liveFieldNames(holder) {
-  const reader = holder.getFieldInfo;
-  if (typeof reader !== "function") return null;
-  try {
-    const rows = await reader.call(holder);
-    if (!Array.isArray(rows)) return null;
-    const names = [];
-    for (const row of rows) {
-      if (typeof row.name === "string") names.push(row.name);
-    }
-    return names.length > 0 ? names : null;
-  } catch (err) {
-    if (!isAutotaskError(err) || err.code === "ABORTED") throw err;
-    return null;
-  }
-}
-var UNKNOWN_NAME_LIST_CAP = 20;
-var UNKNOWN_NAME_DISPLAY_CHARS = 80;
-function formatUnknownNameList(names) {
-  const listed = names.slice(0, UNKNOWN_NAME_LIST_CAP).map((n) => `"${n.length > UNKNOWN_NAME_DISPLAY_CHARS ? `${n.slice(0, UNKNOWN_NAME_DISPLAY_CHARS)}\u2026` : n}"`).join(", ");
-  const more = names.length > UNKNOWN_NAME_LIST_CAP ? ` (and ${names.length - UNKNOWN_NAME_LIST_CAP} more)` : "";
-  return `${listed}${more}`;
-}
-function collectFilterFieldNames(conditions) {
-  const out = [];
-  const walk = (conds) => {
-    for (const cond of conds) {
-      if (!isRecord(cond)) continue;
-      if (cond.op === "and" || cond.op === "or") {
-        if (Array.isArray(cond.items)) walk(cond.items);
-        continue;
-      }
-      if (cond.udf === true) continue;
-      if (typeof cond.field === "string" && cond.field.length > 0) out.push(cond.field);
-    }
-  };
-  walk(conditions);
-  return out;
-}
-async function validateQueryFieldNames(record, holder, args) {
-  const bag = args[0];
-  if (!isRecord(bag)) return;
-  const fieldCheck = bag["fieldCheck"];
-  if (fieldCheck !== void 0 && typeof fieldCheck !== "boolean") {
-    throw new AutotaskConfigError(
-      `invoke: "${record.id}" params bag fieldCheck must be a boolean (got ${typeof fieldCheck}) \u2014 the request was not issued`,
-      { operation: record.id, suggestedAction: "Pass fieldCheck: true (default) or fieldCheck: false (disable the field-name checks \u2014 includeFields AND filter condition names)." }
-    );
-  }
-  const includeFields = bag["includeFields"];
-  let includeNames;
-  if (includeFields !== void 0) {
-    let shapeOk = Array.isArray(includeFields);
-    const names = [];
-    if (shapeOk) {
-      for (const entry of includeFields) {
-        if (typeof entry !== "string" || entry.length === 0) {
-          shapeOk = false;
-          break;
-        }
-        names.push(entry);
-      }
-    }
-    if (!shapeOk) {
-      throw new AutotaskConfigError(
-        `invoke: "${record.id}" params bag includeFields must be an array of non-empty field-name strings \u2014 the request was not issued`,
-        {
-          operation: record.id,
-          suggestedAction: 'Pass includeFields as an array of exact vendor field names, e.g. ["id", "title"]; the live set is in operations.fieldCatalog.'
-        }
-      );
-    }
-    includeNames = names;
-  }
-  let filterNames;
-  if (bag["filter"] !== void 0) {
-    const conditions = normalizedConditions(bag["filter"]);
-    filterNames = collectFilterFieldNames(conditions ?? []);
-  }
-  if (fieldCheck === false) return;
-  const hasInclude = includeNames !== void 0 && includeNames.length > 0;
-  const hasFilter = filterNames !== void 0 && filterNames.length > 0;
-  if (!hasInclude && !hasFilter) return;
-  const live = await liveFieldNames(holder);
-  let known;
-  let liveOnlyExempt = [];
-  if (live !== null) {
-    known = live;
-  } else {
-    const vendored = MODEL_FIELD_SETS[record.resource];
-    liveOnlyExempt = Array.isArray(record.metadata?.liveOnlyFields) ? record.metadata.liveOnlyFields : [];
-    known = vendored === void 0 ? void 0 : [...vendored, ...liveOnlyExempt];
-  }
-  if (known === void 0) return;
-  const authority = live !== null ? "the tenant's live entity field metadata" : liveOnlyExempt.length > 0 ? "the vendored spec (src/field-sets.ts) + the plan-pinned live-only fields (exempt from the vendored refusal)" : "the vendored spec (src/field-sets.ts)";
-  const unknownInclude = hasInclude ? includeNames.filter((name) => !known.includes(name)) : [];
-  const unknownFilter = hasFilter ? [...new Set(filterNames.filter((name) => !known.includes(name)))] : [];
-  if (unknownInclude.length === 0 && unknownFilter.length === 0) return;
-  const parts = [];
-  if (unknownInclude.length > 0) parts.push(`includeFields has unknown field name(s) ${formatUnknownNameList(unknownInclude)}`);
-  if (unknownFilter.length > 0) parts.push(`filter condition(s) carry unknown field name(s) ${formatUnknownNameList(unknownFilter)}`);
-  const wireClause = record.operation === "count" ? "the count request was not issued" : "the query POST was not issued";
-  throw new AutotaskConfigError(
-    `invoke: "${record.id}" ${parts.join("; ")} against ${authority} \u2014 ${wireClause}`,
-    {
-      operation: record.id,
-      suggestedAction: `Use exact vendor field names (operations.fieldCatalog lists the live set for the entity); pass fieldCheck: false to disable this name check. The authority here was ${authority}.`
-    }
-  );
-}
 var INVOKE_OPTION_KEYS = ["dryRun", "confirm", "lastModifiedDate", "maxRetries", "mode"];
 function validateInvokeOptions(opts, operation) {
   if (opts === void 0 || opts === null) return;
@@ -1187,8 +1151,25 @@ function unknownKeysRefusal(raw, validKeys, subject, operation) {
     }
   );
 }
-async function invokeMode(client, operation, argsIn = [], opts = {}) {
-  const args = argsIn ?? [];
+
+// src/operations/invoke/registry.ts
+var RECORDS = CAPABILITIES;
+var byId = new Map(RECORDS.map((r) => [r.id, r]));
+
+// src/operations/invoke/dispatch.ts
+var INVOKE_MAX_INLINE_BYTES = 1024 * 1024;
+function bufferResult(buf) {
+  if (buf.byteLength <= INVOKE_MAX_INLINE_BYTES) {
+    return { encoding: "base64", byteLength: buf.byteLength, truncated: false, data: buf.toString("base64") };
+  }
+  return {
+    encoding: "base64",
+    byteLength: buf.byteLength,
+    truncated: true,
+    note: `Body exceeds the ${INVOKE_MAX_INLINE_BYTES}-byte inline limit and was not returned; call the resource's download method directly.`
+  };
+}
+function resolveRecord(operation) {
   const record = byId.get(operation);
   if (record === void 0) {
     throw new AutotaskConfigError(
@@ -1196,6 +1177,9 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
       { operation, suggestedAction: "List the registry (the ./capabilities subpath) for the exact operation key." }
     );
   }
+  return record;
+}
+function governPreRequest(record, operation, opts) {
   validateInvokeOptions(opts, operation);
   const mode = opts.mode;
   if (mode !== void 0 && MODE_BY_EFFECT[record.effect] !== mode) {
@@ -1207,8 +1191,7 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
       { operation, suggestedAction: "Pass dryRun: true (simulate) or dryRun: false (apply) as a real boolean." }
     );
   }
-  const isWrite = record.effect !== "read";
-  if (!isWrite && opts.dryRun === true) {
+  if (record.effect === "read" && opts.dryRun === true) {
     throw new AutotaskConfigError(
       `invoke: "${operation}" is a read \u2014 dryRun is not applicable (reads issue their request as-is)`,
       { operation }
@@ -1221,53 +1204,57 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
       "Pass confirm equal to the operation key to acknowledge the deliberate act."
     );
   }
-  validateDispatchArgs(record, args);
-  validateParamsBag(record, args);
-  const boundedQuery = record.kind === "primitive" && record.operation === "query";
-  const countedQuery = record.kind === "primitive" && record.operation === "count";
-  let holder = client[camelKey(record.resource)];
+}
+function operationsHolder(client) {
+  return {
+    resolveAny: (identifier, opts) => resolveAny(client, identifier, opts),
+    searchAcrossResources: (query, opts) => searchAcrossResources(client, query, opts),
+    fetchMany: (items, opts) => fetchMany(client, items, opts),
+    // 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: (operation, filter, opts) => aggregate(client, operation, filter, opts),
+    // 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, opts) => fetchByIds(client, items, opts),
+    // 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, opts) => expandResourceNames(client, ids, opts),
+    relationshipMap: (resourceKey) => relationshipMap(client, resourceKey),
+    // Issue #11: the served blind-surface inventory (zero wire) + the
+    // bounded caller-opted reachability sweep (read-only, confirmProbe-
+    // required — the op's own pre-request gates keep it deliberate).
+    blindSurfaces: (opts) => blindSurfaces(client, opts),
+    probeReachability: (opts) => probeReachability(client, opts),
+    // Issue #12: the served zone-fact create-guidance catalog (zero wire).
+    createGuidance: (opts) => createGuidance(client, opts),
+    // Issue #202: ExecuteCommand deep links — pure, zero wire.
+    uiLink: (input) => uiLink(client, input),
+    // Issue #31: the opt-in live field-metadata channel — N bounded
+    // entityInformation GETs (the op's own cap refuses over-cap fan-outs
+    // pre-request; per-resource failures are recorded on the row and
+    // never abort the call).
+    fieldCatalog: (opts) => fieldCatalog(client, opts),
+    // Issue #9: the one-call recovery/cleanup op — effect write in the
+    // registry (the governor's dry-run-first applies to it); the op's own
+    // confirm gate makes the destructive action deliberate (the governor
+    // forwards the caller's confirm through the trailing bag below).
+    recovery: (input, opts) => recovery(client, input, opts)
+  };
+}
+function resolveHolder(client, record, operation) {
+  const clientBag = client;
+  let holder = clientBag[camelKey(record.resource)];
   if (typeof holder === "function") {
-    holder = client[`${camelKey(record.resource)}Resource`] ?? holder;
+    holder = clientBag[`${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-
-      // required — the op's own pre-request gates keep it deliberate).
-      blindSurfaces: (opts2) => blindSurfaces(client, opts2),
-      probeReachability: (opts2) => probeReachability(client, opts2),
-      // Issue #12: the served zone-fact create-guidance catalog (zero wire).
-      createGuidance: (opts2) => createGuidance(client, opts2),
-      // Issue #31: the opt-in live field-metadata channel — N bounded
-      // entityInformation GETs (the op's own cap refuses over-cap fan-outs
-      // pre-request; per-resource failures are recorded on the row and
-      // never abort the call).
-      fieldCatalog: (opts2) => fieldCatalog(client, opts2),
-      // Issue #9: the one-call recovery/cleanup op — effect write in the
-      // registry (the governor's dry-run-first applies to it); the op's own
-      // confirm gate makes the destructive action deliberate (the governor
-      // forwards the caller's confirm through the trailing bag below).
-      recovery: (input, opts2) => recovery(client, input, opts2)
-    };
+    holder = operationsHolder(client);
   }
   if (holder === void 0) {
     throw new AutotaskConfigError(
@@ -1275,15 +1262,13 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
       { operation }
     );
   }
-  if (boundedQuery || countedQuery) await validateQueryFieldNames(record, holder, args);
-  const methodName = boundedQuery ? "queryBounded" : record.operation;
-  const method = holder[methodName];
-  if (typeof method !== "function") {
-    throw new AutotaskConfigError(
-      `invoke: "${record.resource}.${methodName}" is not a callable method on the client`,
-      { operation }
-    );
-  }
+  return holder;
+}
+var BAG_RIDING_ARGS = {
+  createIfNotExists: ["dedupFields"],
+  moveConfigurationItem: ["destinationCompanyId"]
+};
+function buildMutationOpts(opts, isWrite) {
   const dryRun = isWrite ? opts.dryRun !== false : false;
   const mutationOpts = { dryRun };
   if (isWrite && opts.lastModifiedDate !== void 0) {
@@ -1295,10 +1280,9 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
   if (isWrite && opts.confirm !== void 0) {
     mutationOpts.confirm = opts.confirm;
   }
-  const BAG_RIDING_ARGS = {
-    createIfNotExists: ["dedupFields"],
-    moveConfigurationItem: ["destinationCompanyId"]
-  };
+  return mutationOpts;
+}
+function buildCallArgs(record, args, mutationOpts, isWrite) {
   const declaredNames = Object.keys(record.inputSchema ?? {});
   const bagRiding = new Set(BAG_RIDING_ARGS[record.operation] ?? []);
   let positional = args;
@@ -1315,21 +1299,34 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
     while (callArgs.length < declaredPositional.length) callArgs.push(void 0);
     callArgs.push(mutationOpts);
   }
-  const result = await method.apply(holder, callArgs);
-  return Buffer.isBuffer(result) ? bufferResult(result) : result;
+  return callArgs;
 }
-var INVOKE_MAX_INLINE_BYTES = 1024 * 1024;
-function bufferResult(buf) {
-  if (buf.byteLength <= INVOKE_MAX_INLINE_BYTES) {
-    return { encoding: "base64", byteLength: buf.byteLength, truncated: false, data: buf.toString("base64") };
+async function invokeMode(client, operation, argsIn = [], opts = {}) {
+  const args = argsIn ?? [];
+  const record = resolveRecord(operation);
+  governPreRequest(record, operation, opts);
+  validateDispatchArgs(record, args);
+  validateParamsBag(record, args);
+  const boundedQuery = record.kind === "primitive" && record.operation === "query";
+  const countedQuery = record.kind === "primitive" && record.operation === "count";
+  const holder = resolveHolder(client, record, operation);
+  if (boundedQuery || countedQuery) await validateQueryFieldNames(record, holder, args);
+  const methodName = boundedQuery ? "queryBounded" : record.operation;
+  const method = holder[methodName];
+  if (typeof method !== "function") {
+    throw new AutotaskConfigError(
+      `invoke: "${record.resource}.${methodName}" is not a callable method on the client`,
+      { operation }
+    );
   }
-  return {
-    encoding: "base64",
-    byteLength: buf.byteLength,
-    truncated: true,
-    note: `Body exceeds the ${INVOKE_MAX_INLINE_BYTES}-byte inline limit and was not returned; call the resource's download method directly.`
-  };
+  const isWrite = record.effect !== "read";
+  const mutationOpts = buildMutationOpts(opts, isWrite);
+  const callArgs = buildCallArgs(record, args, mutationOpts, isWrite);
+  const result = await method.apply(holder, callArgs);
+  return Buffer.isBuffer(result) ? bufferResult(result) : result;
 }
+
+// src/operations/invoke/wrappers.ts
 async function invoke(client, operation, args = [], opts = {}) {
   return invokeMode(client, operation, args, { ...opts, mode: void 0 });
 }
@@ -1362,9 +1359,11 @@ export {
   RECOVERY_CONFIRM,
   RECOVERY_DEFAULT_LIMIT,
   RECOVERY_MAX_LIMIT,
+  UI_LINK_ENTITIES,
   WORKFLOW_RESOURCES,
   aggregate,
   blindSurfaces,
+  buildUiLink,
   createGuidance,
   dateBucketLabel,
   expandResourceNames,
@@ -1381,6 +1380,7 @@ export {
   relationshipMap,
   resolveAny,
   searchAcrossResources,
+  uiLink,
   unknownKeysRefusal,
   validateDispatchArgs,
   validateFetchManyItems,