node-autotask 0.43.0 → 0.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/MCP_TOOL_CATALOG.json +156 -1253
  3. package/MCP_TOOL_MANIFEST.md +154 -220
  4. package/MCP_TOOL_OVERRIDES.json +8 -62
  5. package/N8N_MCP_MANIFEST.json +128 -705
  6. package/N8N_MCP_MANIFEST.md +43 -63
  7. package/README.md +10 -28
  8. package/capabilities.json +15315 -22219
  9. package/dist/{base-CVx2VMSj.d.cts → base-BVoYDlVA.d.cts} +2 -1
  10. package/dist/{base-CVx2VMSj.d.ts → base-BVoYDlVA.d.ts} +2 -1
  11. package/dist/capabilities.cjs +2 -2
  12. package/dist/capabilities.d.cts +2 -1
  13. package/dist/capabilities.d.ts +2 -1
  14. package/dist/capabilities.js +1 -1
  15. package/dist/{chunk-5VHSLJMR.js → chunk-A6LHCJQP.js} +30 -9
  16. package/dist/{chunk-JY2BWYXY.js → chunk-ASMCTZO2.js} +15314 -22218
  17. package/dist/{chunk-TH7B5H4P.cjs → chunk-DC3PY4EF.cjs} +1839 -1407
  18. package/dist/{chunk-4EFXIE53.js → chunk-DXKXQHCX.js} +5 -5
  19. package/dist/{chunk-SK3GYRNA.cjs → chunk-JO6WI763.cjs} +143 -143
  20. package/dist/{chunk-Q23JULNN.js → chunk-NSW7JPVS.js} +11529 -13319
  21. package/dist/{chunk-KTEDPS4X.js → chunk-O4PIPUS4.js} +1583 -1151
  22. package/dist/{chunk-MJTKK3QG.cjs → chunk-SN4BMQ2N.cjs} +31 -10
  23. package/dist/{chunk-5BDUMDAQ.cjs → chunk-VXVYFJH3.cjs} +15314 -22218
  24. package/dist/{chunk-VFLAMMIJ.cjs → chunk-YMBVKVK4.cjs} +10604 -12394
  25. package/dist/{index-C7rMJ4IV.d.ts → index-C5g1H_hF.d.ts} +1080 -1288
  26. package/dist/{index-Cm_Xpt7X.d.cts → index-Db0SNnQn.d.cts} +1080 -1288
  27. package/dist/{index-C3KFMnRT.d.cts → index-c549LvOb.d.cts} +332 -331
  28. package/dist/{index-C3KFMnRT.d.ts → index-c549LvOb.d.ts} +332 -331
  29. package/dist/index.cjs +23 -23
  30. package/dist/index.d.cts +15 -41
  31. package/dist/index.d.ts +15 -41
  32. package/dist/index.js +8 -8
  33. package/dist/operations/index.cjs +5 -2234
  34. package/dist/operations/index.d.cts +51 -323
  35. package/dist/operations/index.d.ts +51 -323
  36. package/dist/operations/index.js +30 -2259
  37. package/dist/pool.cjs +9 -9
  38. package/dist/pool.d.cts +4 -3
  39. package/dist/pool.d.ts +4 -3
  40. package/dist/pool.js +5 -5
  41. package/dist/resources/index.cjs +5 -5
  42. package/dist/resources/index.d.cts +2 -2
  43. package/dist/resources/index.d.ts +2 -2
  44. package/dist/resources/index.js +8 -8
  45. package/dist/types/index.d.cts +1 -1
  46. package/dist/types/index.d.ts +1 -1
  47. package/dist/untrusted.cjs +2 -2
  48. package/dist/untrusted.d.cts +14 -5
  49. package/dist/untrusted.d.ts +14 -5
  50. package/dist/untrusted.js +1 -1
  51. package/docs/API.md +321 -334
  52. package/docs/LIVE-TESTING.md +4 -6
  53. package/docs/N8N-ADAPTER.md +26 -26
  54. package/examples/mcp/schemas.ts +2 -0
  55. package/examples/mcp/tools-read.ts +3 -2
  56. package/n8n-mcp.curation.json +3 -3
  57. package/package.json +10 -9
@@ -1,20 +1,10 @@
1
- import { a as AutotaskClient, el as BlindSurfaceInfo, em as RelationshipResource, en as BlindSurfaceInventory, eo as BlindSurfaceRow, ep as CreateGuidanceValueRequirement, eq as CreateGuidanceRow, er as CreateBlockerKind, es as CreateGuidanceReport, Z as ZoneName, be as FieldCacheKind } from '../index-C7rMJ4IV.js';
2
- export { bd as FIELD_CACHE_KINDS } from '../index-C7rMJ4IV.js';
3
- import { I as Identifier, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-C3KFMnRT.js';
4
- export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-C3KFMnRT.js';
1
+ import { R as RowNamesSummary, B as BlindSurfaceInfo, b as RelationshipResource, C as CreateGuidanceValueRequirement, c as CreateGuidanceRow, d as CreateBlockerKind, e as CreateGuidanceReport, F as FieldCacheKind } from '../index-C5g1H_hF.js';
2
+ import { AutotaskClient, ZoneName } from '../index.js';
3
+ export { f as FIELD_CACHE_KINDS } from '../index-C5g1H_hF.js';
4
+ import { Identifier, EmptyReasonInfo, PickListValue } from '../index.js';
5
+ export { a as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-c549LvOb.js';
5
6
  import { CapabilityRecord } from '../capabilities.js';
6
- import { b as AutotaskConfigError } from '../base-CVx2VMSj.js';
7
-
8
- /** The `names` summary a labelled result carries ONLY when something was
9
- * left unlabelled: the cold-read cap was hit or a picklist could not be
10
- * resolved. Issue #287: the structured `truncated` / `capped` / catalogError
11
- * bookkeeping was trimmed — the note is the summary. */
12
- interface RowNamesSummary {
13
- /** One line a reader can act on. */
14
- note: string;
15
- /** Picklist field -> why its `*Label` is null (the fieldCatalog honesty note / the value-not-served note). */
16
- reasons?: Record<string, string>;
17
- }
7
+ import { AutotaskConfigError } from '../index.js';
18
8
 
19
9
  /**
20
10
  * Cross-resource operations layer — shared types (ARCHITECTURE section 19.1,
@@ -94,19 +84,10 @@ interface FetchManyResult {
94
84
  interface ResolveAnyOptions {
95
85
  /** Resource keys to resolve against (default: the five workflow resources). */
96
86
  resources?: readonly string[];
97
- /**
98
- * Issue #287 (D7): the match mode (default `'exact'`).
99
- * - `'exact'` — the per-resource exact resolution (numeric id first, then
100
- * exact on the primary text field); the historical behaviour.
101
- * - `'auto'` — exact first (the same per-resource order); on a clean miss of a
102
- * NON-NUMERIC string identifier, a bounded case-insensitive CONTAINS on the
103
- * resource's primary text field (bounded by the resource's scan record cap —
104
- * default 500 records): exactly one hit resolves it (cost `'server-filter'`),
105
- * several hits report that resource as `RESOLUTION_AMBIGUOUS` with the
106
- * candidate ids, zero hits report the miss unchanged. A numeric id miss is
107
- * never re-scanned (the contains fallback is for text values only).
108
- */
87
+ /** Default exact. Auto runs a contains sweep only after EVERY exact lookup cleanly misses; numeric ids never fall back. Hits, ambiguity, truncation and faults suppress the sweep. */
109
88
  match?: 'exact' | 'auto';
89
+ /** Maximum contains matches per resource: integer 1..500. Defaults to the configured resolution.maxScanRecords capped at 500; an explicit limit may narrow, never raise that cap. Exact lookup sizes are unchanged. A full result is conservatively marked truncated. */
90
+ limit?: number;
110
91
  }
111
92
  /**
112
93
  * One resource's outcome. Unlike single-resource `resolve`, a miss does NOT
@@ -118,27 +99,20 @@ interface ResolveAnyResourceOutcome {
118
99
  value: Record<string, unknown> | null;
119
100
  /** How the match was found (or what was attempted). */
120
101
  resolutionCost: 'direct' | 'server-filter' | 'client-scan';
121
- /**
122
- * Records read by the bounded CLIENT scan fallback. The `match: 'auto'`
123
- * server-filter contains fallback reads ZERO records client-side (the
124
- * vendor applies the contains filter; the client receives at most the
125
- * scan-cap matching rows) and reports `scanned: 0` with
126
- * `resolutionCost: 'server-filter'`.
127
- */
102
+ /** Records read by the bounded client scan. Server-filter contains outcomes report zero. */
128
103
  scanned: number;
129
- /** True when the scan hit its cap (a complete non-match is unproven). */
104
+ /** True when a client scan or contains result hit its cap (completeness is unproven). */
130
105
  scanTruncated: boolean;
131
- /**
132
- * Candidate ids when the resource matched more than one record. The
133
- * server-filter contains fallback's list is bounded by the scan record
134
- * cap — a `RESOLUTION_AMBIGUOUS` outcome can carry up to the cap
135
- * candidate ids (default 500).
136
- */
106
+ /** Candidate ids on ambiguity or a cap-full contains result; contains candidates are bounded by limit. */
137
107
  candidates: (number | string)[];
138
108
  /** Error code when the resource could not resolve (e.g. `NOT_FOUND`, `CONFIG_ERROR`). */
139
109
  error?: string;
140
110
  }
141
111
  interface ResolveAnyResult {
112
+ /** Which lookup phase produced this result, including an empty contains sweep. */
113
+ matched: 'exact' | 'contains';
114
+ /** Full per-resource records from the fallback sweep; present exactly when matched is contains. */
115
+ contains?: SearchAcrossResourcesResult;
142
116
  identifier: number | string;
143
117
  /** One outcome per requested resource, in request order. */
144
118
  results: ResolveAnyResourceOutcome[];
@@ -189,65 +163,38 @@ declare function searchAcrossResources(client: AutotaskClient, query: string, op
189
163
 
190
164
  declare function resolveAny(client: AutotaskClient, identifier: number | string, opts?: ResolveAnyOptions): Promise<ResolveAnyResult>;
191
165
 
192
- /** The pinned per-call item cap (over → CONFIG_ERROR pre-request, zero wire). */
193
- declare const FETCH_MANY_MAX_ITEMS = 20;
194
- interface FetchManyOptions {
195
- /** May LOWER the {@link FETCH_MANY_MAX_ITEMS} cap (integer >= 1) — never raise it. */
196
- maxItems?: number;
197
- /**
198
- * Opt-in live field validation (issue #66): when `true`, each item's
199
- * requested `fields` are validated against the tenant's LIVE entity field
200
- * metadata (the cached metadata channel — a warm fieldCache costs zero
201
- * wire; a cold run is one `entityInformation/fields` GET per distinct
202
- * resource in the batch) instead of the vendored-spec field set alone.
203
- * When a resource's metadata is unavailable the validation falls back to
204
- * the vendored-spec field set for THAT resource (unavailability never
205
- * throws and never blocks the batch); when available the live set is
206
- * authoritative — a field it lacks is refused even if the spec lists it,
207
- * and a live field the spec lacks (e.g. `time_entries` `postedDate`) is
208
- * accepted. Default `false` = today's vendored-spec-only validation,
209
- * bit-for-bit (zero metadata wire).
210
- */
211
- liveFields?: boolean;
212
- /** Issue #276: label siblings on the found records (`statusLabel`, `contractIDName`, …). Default true; false = raw records. */
213
- names?: boolean;
166
+ /** Staff lookup with tenant-labelled API-user exclusions and honest metadata state. */
167
+
168
+ interface ResolveStaffOptions {
169
+ /** Match only email; even a digit string is treated as email. */
170
+ emailOnly?: boolean;
171
+ /** Include API users in text matches (default false). Numeric ids always bypass exclusions. */
172
+ includeApiUsers?: boolean;
173
+ /** Maximum returned candidates, 1..10 (default 10); the matched count remains available. */
174
+ limit?: number;
214
175
  }
215
- interface ValidateFetchManyValidation {
216
- /**
217
- * The resolved authoritative per-resource field sets (the `liveFields`
218
- * mode, issue #66): the live entity field set when available, `null` when
219
- * that resource's metadata read rejected (the vendored-spec fallback was
220
- * applied at resolution). Absent / no entry = the vendored-spec set.
221
- */
222
- fieldSetsByResource?: ReadonlyMap<string, readonly string[] | null>;
223
- /** Run the field-NAME membership check (the live mode's shape-only pass passes `false`). */
224
- fieldCheck?: boolean;
176
+ interface ResolveStaffMatch {
177
+ record: Record<string, unknown>;
178
+ /** Present only when tenant labels identify API users AND this record has a labelled value. */
179
+ apiUser?: boolean;
180
+ /** The tenant's label, verbatim. */
181
+ licenseTypeLabel?: string;
225
182
  }
226
- /**
227
- * The pre-request validation (zero wire): one `CONFIG_ERROR` carries the
228
- * COMPLETE problem list for ALL items (shape, limits, unknown resource,
229
- * string id, unknown field key) — the caller fixes everything in one round.
230
- *
231
- * `validation` (the `liveFields` mode, issue #66): the resolved
232
- * authoritative per-resource field sets to validate `fields` against; absent
233
- * = the vendored-spec sets, bit-for-bit the default.
234
- */
235
- declare function validateFetchManyItems(items: unknown, cap: number, opName?: string, capRef?: string, validation?: ValidateFetchManyValidation): void;
236
- /**
237
- * Fetch up to 20 single records across mixed resources in ONE call
238
- * (sequential GETs; per-item typed partial failure; the op throws only
239
- * pre-request).
240
- *
241
- * ```ts
242
- * import { fetchMany } from 'node-autotask/operations';
243
- * const { results, ok, failed } = await fetchMany(client, [
244
- * { resource: 'tickets', id: 527119 },
245
- * { resource: 'tickets', id: 527118, fields: ['id', 'title', 'status'] },
246
- * { resource: 'projects', id: 693 },
247
- * ]);
248
- * ```
249
- */
250
- declare function fetchMany(client: AutotaskClient, items: readonly FetchManyItem[], opts?: FetchManyOptions): Promise<FetchManyResult>;
183
+ interface ResolveStaffResult {
184
+ identifier: Identifier;
185
+ lookup: 'id' | 'text';
186
+ matches: ResolveStaffMatch[];
187
+ /** Matches found after exclusions, before the candidate limit; a lower bound when truncated. */
188
+ matchedCount: number;
189
+ /** More records may exist, or candidates were cut by limit. Never treat a truncated singleton as unique. */
190
+ truncated: boolean;
191
+ /** ok: API labels found; none: labels found but no API label; absent: no labels exposed; error: metadata read failed. */
192
+ metadataState: 'ok' | 'none' | 'absent' | 'error';
193
+ /** Label coverage when the existing client labels option is enabled. */
194
+ names?: RowNamesSummary;
195
+ }
196
+ /** Active email/userName/name lookup; numeric ids fetch directly regardless of active/licence status. */
197
+ declare function resolveStaff(client: AutotaskClient, identifier: Identifier, opts?: ResolveStaffOptions): Promise<ResolveStaffResult>;
251
198
 
252
199
  /** The group-row cap (top may lower it, never raise it). */
253
200
  declare const AGGREGATE_TOP_MAX = 100;
@@ -347,7 +294,7 @@ interface AggregateResult {
347
294
  */
348
295
  declare function aggregate(client: AutotaskClient, operation: string, filter: unknown, opts?: AggregateOptions): Promise<AggregateResult>;
349
296
 
350
- type RevenueRollupDimension = 'vertical' | 'contractType' | 'contractCategory' | 'company' | 'month' | 'billingItemKind' | 'contract' | 'lineOfBusiness' | 'resource' | 'billingCode';
297
+ type RevenueRollupDimension = 'vertical' | 'contractType' | 'company' | 'month' | 'contract' | 'lineOfBusiness';
351
298
  /** The closed opts bag. Exactly one scope key is required. */
352
299
  interface RevenueRollupOptions {
353
300
  companyIDs?: number[];
@@ -461,10 +408,6 @@ interface RevenueRollupResult {
461
408
  unresolvedCompanies: RevenueRollupAmount;
462
409
  /** Only when lineOfBusiness is grouped: a line association (or its level1/level2) the id-in fetch did not return. */
463
410
  unresolvedAssociations?: RevenueRollupAmount;
464
- /** Only when resource is grouped: a labour line's time entry (or its resource) the id-in fetch did not return. */
465
- unresolvedTimeEntries?: RevenueRollupAmount;
466
- /** Only when billingCode is grouped: a line billing code the id-in fetch did not return. */
467
- unresolvedBillingCodes?: RevenueRollupAmount;
468
411
  /** Only with includeNonChargeable: invoiced and uninvoiced non-chargeable lines whose row could not be resolved (a contract, company or join miss; amount = Σ value). */
469
412
  unresolvedNonChargeable?: RevenueRollupAmount;
470
413
  };
@@ -533,105 +476,6 @@ declare function fetchByIds(client: AutotaskClient, items: readonly FetchManyIte
533
476
  */
534
477
  declare function relationshipMap(client: AutotaskClient, resourceKey: string): Promise<RelationshipResource>;
535
478
 
536
- /** The closed blind-class set (the gate clause 14 validates against this). */
537
- type BlindSurfaceKind = 'unowned-blind' | 'fully-blind' | 'unfiltered-blind' | 'unknown';
538
- /** The valid blind classes (served in the typed refusals — deterministic text). */
539
- declare const BLIND_SURFACE_KINDS: readonly BlindSurfaceKind[];
540
- /** The optional filter bag for `operations.blindSurfaces`. */
541
- interface BlindSurfaceOptions {
542
- /** The plan resource key (e.g. `tickets`) — narrows the row set to that resource. Unknown keys throw the typed `RESOURCE_UNKNOWN`. */
543
- resource?: string;
544
- /** The blind class — narrows the row set to one class. Unknown kinds throw the typed `CONFIG_ERROR`. */
545
- kind?: BlindSurfaceKind;
546
- }
547
- /**
548
- * Serve the plan-pinned blind-surface inventory (ZERO wire).
549
- *
550
- * ```ts
551
- * import { blindSurfaces } from 'node-autotask/operations';
552
- * const inv = await blindSurfaces(client); // all 116 surfaces
553
- * const t = await blindSurfaces(client, { resource: 'tickets' }); // one resource
554
- * const b = await blindSurfaces(client, { kind: 'unfiltered-blind' }); // one class
555
- * // inv.counts — { total: 116, dataFull: 46, blind: 69, pinned: 6 } (always artifact-wide)
556
- * // inv.dataFull — the resources whose unfiltered reads are safe
557
- * // inv.remedies — the generic + per-resource (pinned trio) remedy text
558
- * ```
559
- *
560
- * The counts describe the WHOLE pinned artifact regardless of the filter —
561
- * only `surfaces` narrows (the counts are the drift-pinned discovery fact).
562
- *
563
- * @param client The wired client (unused — zero wire by construction).
564
- * @param opts The optional filter ({ resource?, kind? }).
565
- */
566
- declare function blindSurfaces(client: AutotaskClient, opts?: BlindSurfaceOptions): Promise<BlindSurfaceInventory>;
567
-
568
- /** The optional sweep bag for `operations.probeReachability`. */
569
- interface ProbeReachabilityOptions {
570
- /** The plan resource keys to probe. Omitted → the 70 non-data-full pinned surfaces (the 69 blind + ticket_history); that set exceeds the default cap, so probing it requires an explicit `maxWireCalls` (≤ 80). */
571
- resources?: string[];
572
- /** Rows per surface (1-2; default 2). Out of range → CONFIG_ERROR. */
573
- limit?: number;
574
- /** The hard cap for this call (default 40) — it bounds the number of probed surfaces (one bounded read each); transport retries on a probe are not counted against it. Refused above 80; a requested set larger than the cap is refused pre-request (refused, never truncated). */
575
- maxWireCalls?: number;
576
- /** REQUIRED. Without it the op refuses with CONFIG_ERROR before any request (the deliberate act is the caller's). */
577
- confirmProbe?: true;
578
- }
579
- /**
580
- * One probe outcome (the pinned row + the live probe result). The pinned
581
- * fields reuse the GENERATED `BlindSurfaceRow` (the plan's ops/kind/proof
582
- * unions — a plan change re-derives them here; no hand-duplicated unions
583
- * that could drift, post-verification F4).
584
- */
585
- type ProbeSurfaceRow = Omit<BlindSurfaceRow, 'unfilteredRows'> & {
586
- /** The LIVE observed unfiltered row count (null when the probe failed). */
587
- unfilteredRows: number | null;
588
- /** The probe outcome for this surface. */
589
- probe: {
590
- ok: boolean;
591
- /** The bounded reads this probe issued (0 = refused pre-probe, 1 = one bounded read). */
592
- wire: number;
593
- /** The recorded failure (never thrown; the sweep keeps going). */
594
- error: {
595
- code: string;
596
- message: string;
597
- } | null;
598
- };
599
- };
600
- /** The sweep result. */
601
- interface ProbeReachabilityResult {
602
- results: ProbeSurfaceRow[];
603
- /**
604
- * The bounded probe reads actually issued — one per probed surface, so it
605
- * can never exceed `cap` (the cap bounds the SURFACE SET; transport
606
- * retries inside a probe are additional wire and are not counted — the
607
- * raw wire total can therefore exceed `cap` slightly).
608
- */
609
- wireUsed: number;
610
- /** The wire cap the call ran under. */
611
- cap: number;
612
- /** Always false: over-cap requests REFUSE (CONFIG_ERROR) — they are never silently truncated. */
613
- truncated: boolean;
614
- }
615
- /**
616
- * Run the bounded reachability sweep (caller-opted, read-only).
617
- *
618
- * ```ts
619
- * import { probeReachability } from 'node-autotask/operations';
620
- * const res = await probeReachability(client, {
621
- * resources: ['contacts', 'resources', 'companies'],
622
- * limit: 2, // 1-2, default 2
623
- * maxWireCalls: 40, // default 40, refused above 80
624
- * confirmProbe: true, // REQUIRED
625
- * });
626
- * // res.wireUsed — the probes issued (≤ cap); res.results — one row per
627
- * // requested surface (probe.ok false + probe.error where one failed)
628
- * ```
629
- *
630
- * @param client The wired client (the probes issue bounded queryBounded reads).
631
- * @param opts The sweep bag ({ resources?, limit?, maxWireCalls?, confirmProbe? }).
632
- */
633
- declare function probeReachability(client: AutotaskClient, opts?: ProbeReachabilityOptions): Promise<ProbeReachabilityResult>;
634
-
635
479
  /**
636
480
  * `effectiveRequiredFields` — the ONE precedence rule for "what does a create
637
481
  * really require" (issue #219 N4).
@@ -819,8 +663,8 @@ type SanitiseResult = Record<string, unknown>;
819
663
  * `metadata.untrustedFields` decides the field list.
820
664
  * @returns A promise for a NEW result object with the present untrusted
821
665
  * fields wrapped (the input is never mutated) when the operation
822
- * declares untrusted fields — or the input returned unchanged
823
- * (the same reference) when it declares none.
666
+ * declares untrusted fields or contains UDF values to fence; otherwise
667
+ * the input is returned unchanged (the same reference).
824
668
  * @throws {AutotaskConfigError} an unknown (non-string/empty, or not-in-the-
825
669
  * registry) operation — typed, zero wire.
826
670
  */
@@ -1096,123 +940,6 @@ interface ExpandResourceNamesResult {
1096
940
  */
1097
941
  declare function expandResourceNames(client: AutotaskClient, ids: readonly Identifier[], opts?: ExpandResourceNamesOptions): Promise<ExpandResourceNamesResult>;
1098
942
 
1099
- /** The exact confirmation string the destructive apply requires (R4 style: the op key). */
1100
- declare const RECOVERY_CONFIRM = "operations.recovery";
1101
- /** The default TOTAL match cap of the marker search. */
1102
- declare const RECOVERY_DEFAULT_LIMIT = 25;
1103
- /** The hard TOTAL match cap (a CONFIG_ERROR above it — pre-request, zero wire). */
1104
- declare const RECOVERY_MAX_LIMIT = 100;
1105
- /** The one-call recovery/cleanup input (all validation is pre-request, zero wire). */
1106
- interface RecoveryInput {
1107
- /** The plan resource key (e.g. 'companies'). Unknown → typed RESOURCE_UNKNOWN. */
1108
- resource: string;
1109
- /** The marker the write stamped into a name-like field (searched with `contains`). */
1110
- marker: string;
1111
- /**
1112
- * The name-like vendor field to filter on (API casing). Default: the
1113
- * plan's markerField for the resource; REQUIRED when the resource has no
1114
- * markerField (a CONFIG_ERROR names the model's fields as the candidates).
1115
- */
1116
- field?: string;
1117
- /** Parent scope (parent-scoped child resources only — narrows the search on the parent FK). */
1118
- parentId?: number;
1119
- /** Extra leaf filter conditions narrowing the search (e.g. `{ field: 'status', op: 'eq', value: 'open' }`). */
1120
- filter?: FilterCondition[];
1121
- /** The TOTAL match cap (default 25, max 100). */
1122
- limit?: number;
1123
- /** 'find' (default — a read) | 'delete' (destructive — dry-run-first, confirm-gated apply). */
1124
- action?: 'find' | 'delete';
1125
- /**
1126
- * The apply confirmation for `action: 'delete'` (the exact op key —
1127
- * `operations.recovery`). Accepted on the INPUT as well as in
1128
- * {@link RecoveryOptions.confirm} so the MCP tool path can apply a delete:
1129
- * the tool bag has no confirm slot, so the input object rides it (the SDK
1130
- * options path stays the canonical form; the two are equivalent).
1131
- */
1132
- confirm?: string;
1133
- }
1134
- /** One matched record (the id is null when unrepresentable — see unsafeId). */
1135
- interface RecoveryMatch {
1136
- /** The record's id (null when beyond Number.MAX_SAFE_INTEGER — never a silent skip). */
1137
- id: number | null;
1138
- /** The marker field's value in the matched record. */
1139
- value: string | number | boolean | null;
1140
- }
1141
- /** The delete-boundary fact carried in every recovery result. */
1142
- interface RecoveryDeleteBoundary {
1143
- /** False when the vendor defines no DELETE for the resource (cleanup is UI-only). */
1144
- available: boolean;
1145
- /** The spec-derived boundary note (available=false) — null when the boundary is available. */
1146
- reason: string | null;
1147
- /** The authority op that answers for the record (null — the boundary is spec-derived). */
1148
- authority: string | null;
1149
- }
1150
- /** The one-call recovery/cleanup result (issue #9). */
1151
- interface RecoveryResult {
1152
- /** The resource key the op ran against. */
1153
- resource: string;
1154
- /** The marker searched. */
1155
- marker: string;
1156
- /** The field the marker was searched on. */
1157
- field: string;
1158
- /** The action that ran ('find' | 'delete'). */
1159
- action: 'find' | 'delete';
1160
- /** The matched records (empty = the marker matched nothing in the bounded scan). */
1161
- matches: RecoveryMatch[];
1162
- /** Records returned by the single bounded query. */
1163
- scanned: number;
1164
- /**
1165
- * Always false in a returned result: a cap-tripped search REFUSES with
1166
- * RECOVERY_TRUNCATED before any result exists (never a silent truncation).
1167
- */
1168
- truncated: boolean;
1169
- /** The spec-derived delete boundary (zero wire — the plan audit). */
1170
- delete: RecoveryDeleteBoundary;
1171
- /** True when ANY match's id is unrepresentable (beyond Number.MAX_SAFE_INTEGER — P1). */
1172
- unsafeId: boolean;
1173
- /** The manual cleanup note (delete-less resources) — null when the boundary is available. */
1174
- cleanup: {
1175
- manual: boolean;
1176
- note: string;
1177
- } | null;
1178
- /** Delete apply only: the per-id outcome (code = the typed code of a failed per-id DELETE). */
1179
- deleted?: Array<{
1180
- id: number;
1181
- verified: boolean;
1182
- code?: string;
1183
- }>;
1184
- /** Delete dry run only: the envelope marker (the apply path omits it). */
1185
- simulated?: boolean;
1186
- /** The dry-run flag the op ran under (the governor appends dry-run-first). */
1187
- dryRun?: boolean;
1188
- }
1189
- /** The op options (the governor's trailing bag lands here). */
1190
- interface RecoveryOptions {
1191
- /** Simulate (default true — dry-run-first; the governor appends the governed flag). */
1192
- dryRun?: boolean;
1193
- /** The exact confirmation string for the delete apply (RECOVERY_CONFIRM). */
1194
- confirm?: string;
1195
- }
1196
- /**
1197
- * Run the one-call recovery/cleanup op.
1198
- *
1199
- * ```ts
1200
- * import { recovery } from 'node-autotask/operations';
1201
- * // Find the scratch record the write just created (one bounded query, zero mutating wire):
1202
- * const r = await recovery(client, { resource: 'companies', marker: 'FULL100W-1791110339' });
1203
- * // r.delete.available === false + r.cleanup.note — the spec says the vendor has no DELETE.
1204
- *
1205
- * // Where the vendor DOES allow it (delete available):
1206
- * const dry = await recovery(client, { resource: 'configuration_item_dns_records', marker: 'm', parentId: 42 }, { dryRun: true });
1207
- * const applied = await recovery(client, { resource: 'configuration_item_dns_records', marker: 'm', parentId: 42, action: 'delete' }, { dryRun: false, confirm: 'operations.recovery' });
1208
- * ```
1209
- *
1210
- * @param client The wired client (the op runs against the resource's own bounded-query surface).
1211
- * @param input The recovery input (see {@link RecoveryInput}).
1212
- * @param opts The op options (dryRun / confirm — the governor appends the governed bag).
1213
- */
1214
- declare function recovery(client: AutotaskClient, input: RecoveryInput, opts?: RecoveryOptions): Promise<RecoveryResult>;
1215
-
1216
943
  /** True for an operation that needs a deliberate act before it runs (R4). */
1217
944
  declare function needsConfirmation(record: CapabilityRecord): boolean;
1218
945
  /**
@@ -1321,4 +1048,5 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
1321
1048
  */
1322
1049
  declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[] | Record<string, unknown>, opts?: InvokeOptions): Promise<unknown>;
1323
1050
 
1324
- export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, type DerivationRule, EXPAND_RESOURCE_NAMES_MAX_IDS, type EffectiveRequiredFields, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogCompactFieldRow, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldCatalogTrimKind, type FieldCatalogTruncation, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, MIN_FIELD_CATALOG_MAX_BYTES, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type RequiredFieldsRecord, type RequiredFieldsSource, type RequiredFieldsZoneFacts, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type RevenueRollupAmount, type RevenueRollupDimension, type RevenueRollupKey, type RevenueRollupNonChargeable, type RevenueRollupNonChargeableAmount, type RevenueRollupOptions, type RevenueRollupResult, type RevenueRollupRow, type RowNamesSummary, type SanitiseResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, type ServedCreateGuidanceReport, type ServedCreateGuidanceRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, revenueRollup, sanitiseResult, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
1051
+ export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, CREATE_BLOCKER_KINDS, EXPAND_RESOURCE_NAMES_MAX_IDS, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, FieldCacheKind, INVOKE_OPTION_KEYS, MAX_FIELD_CATALOG_WIRE, MIN_FIELD_CATALOG_MAX_BYTES, PARAMS_BAG_KEYS, RowNamesSummary, UI_LINK_ENTITIES, WORKFLOW_RESOURCES, aggregate, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, relationshipMap, resolveAny, resolveStaff, revenueRollup, sanitiseResult, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateInvokeOptions, validateParamsBag };
1052
+ export type { AggregateGroup, AggregateOptions, AggregateResult, CreateGuidanceOptions, DateBucket, DerivationRule, EffectiveRequiredFields, ExpandResourceNameRow, ExpandResourceNamesOptions, ExpandResourceNamesResult, FetchByIdsOptions, FetchManyItem, FetchManyItemError, FetchManyItemResult, FetchManyResult, FieldCatalogCompactFieldRow, FieldCatalogFieldRow, FieldCatalogOptions, FieldCatalogResult, FieldCatalogRow, FieldCatalogRowError, FieldCatalogTrimKind, FieldCatalogTruncation, FieldDerivation, InvokeMode, InvokeOptions, RequiredFieldsRecord, RequiredFieldsSource, RequiredFieldsZoneFacts, ResolveAnyOptions, ResolveAnyResourceOutcome, ResolveAnyResult, ResolveStaffMatch, ResolveStaffOptions, ResolveStaffResult, RevenueRollupAmount, RevenueRollupDimension, RevenueRollupKey, RevenueRollupNonChargeable, RevenueRollupNonChargeableAmount, RevenueRollupOptions, RevenueRollupResult, RevenueRollupRow, SanitiseResult, SearchAcrossResourcesOptions, SearchAcrossResourcesResult, SearchAcrossResourcesRow, ServedCreateGuidanceReport, ServedCreateGuidanceRow, UiLinkEntity, UiLinkInput, UiLinkResult };