node-autotask 0.44.0 → 0.45.0

package/dist/operations/index.d.ts

@@ -1,8 +1,8 @@
-import { el as RowNamesSummary, em as BlindSurfaceInfo, en as RelationshipResource, eo as BlindSurfaceInventory, ep as BlindSurfaceRow, eq as CreateGuidanceValueRequirement, er as CreateGuidanceRow, es as CreateBlockerKind, et as CreateGuidanceReport, be as FieldCacheKind } from '../index-D8FtzUGP.js';
+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';
 import { AutotaskClient, ZoneName } from '../index.js';
-export { bd as FIELD_CACHE_KINDS } from '../index-D8FtzUGP.js';
-import { Identifier, EmptyReasonInfo, PickListValue, FilterCondition } from '../index.js';
-export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-DgBA1JMH.js';
+export { f as FIELD_CACHE_KINDS } from '../index-C5g1H_hF.js';
+import { Identifier, EmptyReasonInfo, PickListValue } from '../index.js';
+export { a as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-c549LvOb.js';
 import { CapabilityRecord } from '../capabilities.js';
 import { AutotaskConfigError } from '../index.js';
 
@@ -196,66 +196,6 @@ interface ResolveStaffResult {
 /** Active email/userName/name lookup; numeric ids fetch directly regardless of active/licence status. */
 declare function resolveStaff(client: AutotaskClient, identifier: Identifier, opts?: ResolveStaffOptions): Promise<ResolveStaffResult>;
 
-/** The pinned per-call item cap (over → CONFIG_ERROR pre-request, zero wire). */
-declare const FETCH_MANY_MAX_ITEMS = 20;
-interface FetchManyOptions {
-    /** May LOWER the {@link FETCH_MANY_MAX_ITEMS} cap (integer >= 1) — never raise it. */
-    maxItems?: number;
-    /**
-     * Opt-in live field validation (issue #66): when `true`, each item's
-     * requested `fields` are validated against the tenant's LIVE entity field
-     * metadata (the cached metadata channel — a warm fieldCache costs zero
-     * wire; a cold run is one `entityInformation/fields` GET per distinct
-     * resource in the batch) instead of the vendored-spec field set alone.
-     * When a resource's metadata is unavailable the validation falls back to
-     * the vendored-spec field set for THAT resource (unavailability never
-     * throws and never blocks the batch); when available the live set is
-     * authoritative — a field it lacks is refused even if the spec lists it,
-     * and a live field the spec lacks (e.g. `time_entries` `postedDate`) is
-     * accepted. Default `false` = today's vendored-spec-only validation,
-     * bit-for-bit (zero metadata wire).
-     */
-    liveFields?: boolean;
-    /** Issue #276: label siblings on the found records (`statusLabel`, `contractIDName`, …). Default true; false = raw records. */
-    names?: boolean;
-}
-interface ValidateFetchManyValidation {
-    /**
-     * The resolved authoritative per-resource field sets (the `liveFields`
-     * mode, issue #66): the live entity field set when available, `null` when
-     * that resource's metadata read rejected (the vendored-spec fallback was
-     * applied at resolution). Absent / no entry = the vendored-spec set.
-     */
-    fieldSetsByResource?: ReadonlyMap<string, readonly string[] | null>;
-    /** Run the field-NAME membership check (the live mode's shape-only pass passes `false`). */
-    fieldCheck?: boolean;
-}
-/**
- * The pre-request validation (zero wire): one `CONFIG_ERROR` carries the
- * COMPLETE problem list for ALL items (shape, limits, unknown resource,
- * string id, unknown field key) — the caller fixes everything in one round.
- *
- * `validation` (the `liveFields` mode, issue #66): the resolved
- * authoritative per-resource field sets to validate `fields` against; absent
- * = the vendored-spec sets, bit-for-bit the default.
- */
-declare function validateFetchManyItems(items: unknown, cap: number, opName?: string, capRef?: string, validation?: ValidateFetchManyValidation): void;
-/**
- * Fetch up to 20 single records across mixed resources in ONE call
- * (sequential GETs; per-item typed partial failure; the op throws only
- * pre-request).
- *
- * ```ts
- * import { fetchMany } from 'node-autotask/operations';
- * const { results, ok, failed } = await fetchMany(client, [
- *   { resource: 'tickets', id: 527119 },
- *   { resource: 'tickets', id: 527118, fields: ['id', 'title', 'status'] },
- *   { resource: 'projects', id: 693 },
- * ]);
- * ```
- */
-declare function fetchMany(client: AutotaskClient, items: readonly FetchManyItem[], opts?: FetchManyOptions): Promise<FetchManyResult>;
-
 /** The group-row cap (top may lower it, never raise it). */
 declare const AGGREGATE_TOP_MAX = 100;
 /** The default group-row count. */
@@ -354,7 +294,7 @@ interface AggregateResult {
  */
 declare function aggregate(client: AutotaskClient, operation: string, filter: unknown, opts?: AggregateOptions): Promise<AggregateResult>;
 
-type RevenueRollupDimension = 'vertical' | 'contractType' | 'contractCategory' | 'company' | 'month' | 'billingItemKind' | 'contract' | 'lineOfBusiness' | 'resource' | 'billingCode';
+type RevenueRollupDimension = 'vertical' | 'contractType' | 'company' | 'month' | 'contract' | 'lineOfBusiness';
 /** The closed opts bag. Exactly one scope key is required. */
 interface RevenueRollupOptions {
     companyIDs?: number[];
@@ -468,10 +408,6 @@ interface RevenueRollupResult {
             unresolvedCompanies: RevenueRollupAmount;
             /** Only when lineOfBusiness is grouped: a line association (or its level1/level2) the id-in fetch did not return. */
             unresolvedAssociations?: RevenueRollupAmount;
-            /** Only when resource is grouped: a labour line's time entry (or its resource) the id-in fetch did not return. */
-            unresolvedTimeEntries?: RevenueRollupAmount;
-            /** Only when billingCode is grouped: a line billing code the id-in fetch did not return. */
-            unresolvedBillingCodes?: RevenueRollupAmount;
             /** Only with includeNonChargeable: invoiced and uninvoiced non-chargeable lines whose row could not be resolved (a contract, company or join miss; amount = Σ value). */
             unresolvedNonChargeable?: RevenueRollupAmount;
         };
@@ -540,105 +476,6 @@ declare function fetchByIds(client: AutotaskClient, items: readonly FetchManyIte
  */
 declare function relationshipMap(client: AutotaskClient, resourceKey: string): Promise<RelationshipResource>;
 
-/** The closed blind-class set (the gate clause 14 validates against this). */
-type BlindSurfaceKind = 'unowned-blind' | 'fully-blind' | 'unfiltered-blind' | 'unknown';
-/** The valid blind classes (served in the typed refusals — deterministic text). */
-declare const BLIND_SURFACE_KINDS: readonly BlindSurfaceKind[];
-/** The optional filter bag for `operations.blindSurfaces`. */
-interface BlindSurfaceOptions {
-    /** The plan resource key (e.g. `tickets`) — narrows the row set to that resource. Unknown keys throw the typed `RESOURCE_UNKNOWN`. */
-    resource?: string;
-    /** The blind class — narrows the row set to one class. Unknown kinds throw the typed `CONFIG_ERROR`. */
-    kind?: BlindSurfaceKind;
-}
-/**
- * Serve the plan-pinned blind-surface inventory (ZERO wire).
- *
- * ```ts
- * import { blindSurfaces } from 'node-autotask/operations';
- * const inv = await blindSurfaces(client);            // all 116 surfaces
- * const t = await blindSurfaces(client, { resource: 'tickets' });   // one resource
- * const b = await blindSurfaces(client, { kind: 'unfiltered-blind' }); // one class
- * // inv.counts — { total: 116, dataFull: 46, blind: 69, pinned: 6 } (always artifact-wide)
- * // inv.dataFull — the resources whose unfiltered reads are safe
- * // inv.remedies — the generic + per-resource (pinned trio) remedy text
- * ```
- *
- * The counts describe the WHOLE pinned artifact regardless of the filter —
- * only `surfaces` narrows (the counts are the drift-pinned discovery fact).
- *
- * @param client The wired client (unused — zero wire by construction).
- * @param opts   The optional filter ({ resource?, kind? }).
- */
-declare function blindSurfaces(client: AutotaskClient, opts?: BlindSurfaceOptions): Promise<BlindSurfaceInventory>;
-
-/** The optional sweep bag for `operations.probeReachability`. */
-interface ProbeReachabilityOptions {
-    /** 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). */
-    resources?: string[];
-    /** Rows per surface (1-2; default 2). Out of range → CONFIG_ERROR. */
-    limit?: number;
-    /** 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). */
-    maxWireCalls?: number;
-    /** REQUIRED. Without it the op refuses with CONFIG_ERROR before any request (the deliberate act is the caller's). */
-    confirmProbe?: true;
-}
-/**
- * One probe outcome (the pinned row + the live probe result). The pinned
- * fields reuse the GENERATED `BlindSurfaceRow` (the plan's ops/kind/proof
- * unions — a plan change re-derives them here; no hand-duplicated unions
- * that could drift, post-verification F4).
- */
-type ProbeSurfaceRow = Omit<BlindSurfaceRow, 'unfilteredRows'> & {
-    /** The LIVE observed unfiltered row count (null when the probe failed). */
-    unfilteredRows: number | null;
-    /** The probe outcome for this surface. */
-    probe: {
-        ok: boolean;
-        /** The bounded reads this probe issued (0 = refused pre-probe, 1 = one bounded read). */
-        wire: number;
-        /** The recorded failure (never thrown; the sweep keeps going). */
-        error: {
-            code: string;
-            message: string;
-        } | null;
-    };
-};
-/** The sweep result. */
-interface ProbeReachabilityResult {
-    results: ProbeSurfaceRow[];
-    /**
-     * The bounded probe reads actually issued — one per probed surface, so it
-     * can never exceed `cap` (the cap bounds the SURFACE SET; transport
-     * retries inside a probe are additional wire and are not counted — the
-     * raw wire total can therefore exceed `cap` slightly).
-     */
-    wireUsed: number;
-    /** The wire cap the call ran under. */
-    cap: number;
-    /** Always false: over-cap requests REFUSE (CONFIG_ERROR) — they are never silently truncated. */
-    truncated: boolean;
-}
-/**
- * Run the bounded reachability sweep (caller-opted, read-only).
- *
- * ```ts
- * import { probeReachability } from 'node-autotask/operations';
- * const res = await probeReachability(client, {
- *   resources: ['contacts', 'resources', 'companies'],
- *   limit: 2,            // 1-2, default 2
- *   maxWireCalls: 40,    // default 40, refused above 80
- *   confirmProbe: true,  // REQUIRED
- * });
- * // res.wireUsed — the probes issued (≤ cap); res.results — one row per
- * // requested surface (probe.ok false + probe.error where one failed)
- * ```
- *
- * @param client The wired client (the probes issue bounded queryBounded reads).
- * @param opts   The sweep bag ({ resources?, limit?, maxWireCalls?, confirmProbe? }).
- */
-declare function probeReachability(client: AutotaskClient, opts?: ProbeReachabilityOptions): Promise<ProbeReachabilityResult>;
-
 /**
  * `effectiveRequiredFields` — the ONE precedence rule for "what does a create
  * really require" (issue #219 N4).
@@ -1103,123 +940,6 @@ interface ExpandResourceNamesResult {
  */
 declare function expandResourceNames(client: AutotaskClient, ids: readonly Identifier[], opts?: ExpandResourceNamesOptions): Promise<ExpandResourceNamesResult>;
 
-/** The exact confirmation string the destructive apply requires (R4 style: the op key). */
-declare const RECOVERY_CONFIRM = "operations.recovery";
-/** The default TOTAL match cap of the marker search. */
-declare const RECOVERY_DEFAULT_LIMIT = 25;
-/** The hard TOTAL match cap (a CONFIG_ERROR above it — pre-request, zero wire). */
-declare const RECOVERY_MAX_LIMIT = 100;
-/** The one-call recovery/cleanup input (all validation is pre-request, zero wire). */
-interface RecoveryInput {
-    /** The plan resource key (e.g. 'companies'). Unknown → typed RESOURCE_UNKNOWN. */
-    resource: string;
-    /** The marker the write stamped into a name-like field (searched with `contains`). */
-    marker: string;
-    /**
-     * The name-like vendor field to filter on (API casing). Default: the
-     * plan's markerField for the resource; REQUIRED when the resource has no
-     * markerField (a CONFIG_ERROR names the model's fields as the candidates).
-     */
-    field?: string;
-    /** Parent scope (parent-scoped child resources only — narrows the search on the parent FK). */
-    parentId?: number;
-    /** Extra leaf filter conditions narrowing the search (e.g. `{ field: 'status', op: 'eq', value: 'open' }`). */
-    filter?: FilterCondition[];
-    /** The TOTAL match cap (default 25, max 100). */
-    limit?: number;
-    /** 'find' (default — a read) | 'delete' (destructive — dry-run-first, confirm-gated apply). */
-    action?: 'find' | 'delete';
-    /**
-     * The apply confirmation for `action: 'delete'` (the exact op key —
-     * `operations.recovery`). Accepted on the INPUT as well as in
-     * {@link RecoveryOptions.confirm} so the MCP tool path can apply a delete:
-     * the tool bag has no confirm slot, so the input object rides it (the SDK
-     * options path stays the canonical form; the two are equivalent).
-     */
-    confirm?: string;
-}
-/** One matched record (the id is null when unrepresentable — see unsafeId). */
-interface RecoveryMatch {
-    /** The record's id (null when beyond Number.MAX_SAFE_INTEGER — never a silent skip). */
-    id: number | null;
-    /** The marker field's value in the matched record. */
-    value: string | number | boolean | null;
-}
-/** The delete-boundary fact carried in every recovery result. */
-interface RecoveryDeleteBoundary {
-    /** False when the vendor defines no DELETE for the resource (cleanup is UI-only). */
-    available: boolean;
-    /** The spec-derived boundary note (available=false) — null when the boundary is available. */
-    reason: string | null;
-    /** The authority op that answers for the record (null — the boundary is spec-derived). */
-    authority: string | null;
-}
-/** The one-call recovery/cleanup result (issue #9). */
-interface RecoveryResult {
-    /** The resource key the op ran against. */
-    resource: string;
-    /** The marker searched. */
-    marker: string;
-    /** The field the marker was searched on. */
-    field: string;
-    /** The action that ran ('find' | 'delete'). */
-    action: 'find' | 'delete';
-    /** The matched records (empty = the marker matched nothing in the bounded scan). */
-    matches: RecoveryMatch[];
-    /** Records returned by the single bounded query. */
-    scanned: number;
-    /**
-     * Always false in a returned result: a cap-tripped search REFUSES with
-     * RECOVERY_TRUNCATED before any result exists (never a silent truncation).
-     */
-    truncated: boolean;
-    /** The spec-derived delete boundary (zero wire — the plan audit). */
-    delete: RecoveryDeleteBoundary;
-    /** True when ANY match's id is unrepresentable (beyond Number.MAX_SAFE_INTEGER — P1). */
-    unsafeId: boolean;
-    /** The manual cleanup note (delete-less resources) — null when the boundary is available. */
-    cleanup: {
-        manual: boolean;
-        note: string;
-    } | null;
-    /** Delete apply only: the per-id outcome (code = the typed code of a failed per-id DELETE). */
-    deleted?: Array<{
-        id: number;
-        verified: boolean;
-        code?: string;
-    }>;
-    /** Delete dry run only: the envelope marker (the apply path omits it). */
-    simulated?: boolean;
-    /** The dry-run flag the op ran under (the governor appends dry-run-first). */
-    dryRun?: boolean;
-}
-/** The op options (the governor's trailing bag lands here). */
-interface RecoveryOptions {
-    /** Simulate (default true — dry-run-first; the governor appends the governed flag). */
-    dryRun?: boolean;
-    /** The exact confirmation string for the delete apply (RECOVERY_CONFIRM). */
-    confirm?: string;
-}
-/**
- * Run the one-call recovery/cleanup op.
- *
- * ```ts
- * import { recovery } from 'node-autotask/operations';
- * // Find the scratch record the write just created (one bounded query, zero mutating wire):
- * const r = await recovery(client, { resource: 'companies', marker: 'FULL100W-1791110339' });
- * // r.delete.available === false + r.cleanup.note — the spec says the vendor has no DELETE.
- *
- * // Where the vendor DOES allow it (delete available):
- * const dry = await recovery(client, { resource: 'configuration_item_dns_records', marker: 'm', parentId: 42 }, { dryRun: true });
- * const applied = await recovery(client, { resource: 'configuration_item_dns_records', marker: 'm', parentId: 42, action: 'delete' }, { dryRun: false, confirm: 'operations.recovery' });
- * ```
- *
- * @param client  The wired client (the op runs against the resource's own bounded-query surface).
- * @param input   The recovery input (see {@link RecoveryInput}).
- * @param opts    The op options (dryRun / confirm — the governor appends the governed bag).
- */
-declare function recovery(client: AutotaskClient, input: RecoveryInput, opts?: RecoveryOptions): Promise<RecoveryResult>;
-
 /** True for an operation that needs a deliberate act before it runs (R4). */
 declare function needsConfirmation(record: CapabilityRecord): boolean;
 /**
@@ -1328,5 +1048,5 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[] | Record<string, unknown>, opts?: InvokeOptions): Promise<unknown>;
 
-export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, BLIND_SURFACE_KINDS, BlindSurfaceRow, CREATE_BLOCKER_KINDS, EXPAND_RESOURCE_NAMES_MAX_IDS, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, FieldCacheKind, INVOKE_OPTION_KEYS, MAX_FIELD_CATALOG_WIRE, MIN_FIELD_CATALOG_MAX_BYTES, PARAMS_BAG_KEYS, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, RowNamesSummary, UI_LINK_ENTITIES, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resolveStaff, revenueRollup, sanitiseResult, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
-export type { AggregateGroup, AggregateOptions, AggregateResult, BlindSurfaceKind, BlindSurfaceOptions, CreateGuidanceOptions, DateBucket, DerivationRule, EffectiveRequiredFields, ExpandResourceNameRow, ExpandResourceNamesOptions, ExpandResourceNamesResult, FetchByIdsOptions, FetchManyItem, FetchManyItemError, FetchManyItemResult, FetchManyOptions, FetchManyResult, FieldCatalogCompactFieldRow, FieldCatalogFieldRow, FieldCatalogOptions, FieldCatalogResult, FieldCatalogRow, FieldCatalogRowError, FieldCatalogTrimKind, FieldCatalogTruncation, FieldDerivation, InvokeMode, InvokeOptions, ProbeReachabilityOptions, ProbeReachabilityResult, ProbeSurfaceRow, RecoveryDeleteBoundary, RecoveryInput, RecoveryMatch, RecoveryOptions, RecoveryResult, 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 };
+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 };
+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 };