node-autotask 0.42.0 → 0.44.0

package/dist/operations/index.d.cts

@@ -1,20 +1,10 @@
-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-Cm_Xpt7X.cjs';
-export { bd as FIELD_CACHE_KINDS } from '../index-Cm_Xpt7X.cjs';
-import { I as Identifier, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-C3KFMnRT.cjs';
-export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-C3KFMnRT.cjs';
+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-YbEk0awP.cjs';
+import { AutotaskClient, ZoneName } from '../index.cjs';
+export { bd as FIELD_CACHE_KINDS } from '../index-YbEk0awP.cjs';
+import { Identifier, EmptyReasonInfo, PickListValue, FilterCondition } from '../index.cjs';
+export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-DgBA1JMH.cjs';
 import { CapabilityRecord } from '../capabilities.cjs';
-import { b as AutotaskConfigError } from '../base-CVx2VMSj.cjs';
-
-/** The `names` summary a labelled result carries ONLY when something was
- * left unlabelled: the cold-read cap was hit or a picklist could not be
- * resolved. Issue #287: the structured `truncated` / `capped` / catalogError
- * bookkeeping was trimmed — the note is the summary. */
-interface RowNamesSummary {
-    /** One line a reader can act on. */
-    note: string;
-    /** Picklist field -> why its `*Label` is null (the fieldCatalog honesty note / the value-not-served note). */
-    reasons?: Record<string, string>;
-}
+import { AutotaskConfigError } from '../index.cjs';
 
 /**
  * Cross-resource operations layer — shared types (ARCHITECTURE section 19.1,
@@ -94,19 +84,10 @@ interface FetchManyResult {
 interface ResolveAnyOptions {
     /** Resource keys to resolve against (default: the five workflow resources). */
     resources?: readonly string[];
-    /**
-     * Issue #287 (D7): the match mode (default `'exact'`).
-     * - `'exact'` — the per-resource exact resolution (numeric id first, then
-     *   exact on the primary text field); the historical behaviour.
-     * - `'auto'` — exact first (the same per-resource order); on a clean miss of a
-     *   NON-NUMERIC string identifier, a bounded case-insensitive CONTAINS on the
-     *   resource's primary text field (bounded by the resource's scan record cap —
-     *   default 500 records): exactly one hit resolves it (cost `'server-filter'`),
-     *   several hits report that resource as `RESOLUTION_AMBIGUOUS` with the
-     *   candidate ids, zero hits report the miss unchanged. A numeric id miss is
-     *   never re-scanned (the contains fallback is for text values only).
-     */
+    /** 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. */
     match?: 'exact' | 'auto';
+    /** 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. */
+    limit?: number;
 }
 /**
  * One resource's outcome. Unlike single-resource `resolve`, a miss does NOT
@@ -118,27 +99,20 @@ interface ResolveAnyResourceOutcome {
     value: Record<string, unknown> | null;
     /** How the match was found (or what was attempted). */
     resolutionCost: 'direct' | 'server-filter' | 'client-scan';
-    /**
-     * Records read by the bounded CLIENT scan fallback. The `match: 'auto'`
-     * server-filter contains fallback reads ZERO records client-side (the
-     * vendor applies the contains filter; the client receives at most the
-     * scan-cap matching rows) and reports `scanned: 0` with
-     * `resolutionCost: 'server-filter'`.
-     */
+    /** Records read by the bounded client scan. Server-filter contains outcomes report zero. */
     scanned: number;
-    /** True when the scan hit its cap (a complete non-match is unproven). */
+    /** True when a client scan or contains result hit its cap (completeness is unproven). */
     scanTruncated: boolean;
-    /**
-     * Candidate ids when the resource matched more than one record. The
-     * server-filter contains fallback's list is bounded by the scan record
-     * cap — a `RESOLUTION_AMBIGUOUS` outcome can carry up to the cap
-     * candidate ids (default 500).
-     */
+    /** Candidate ids on ambiguity or a cap-full contains result; contains candidates are bounded by limit. */
     candidates: (number | string)[];
     /** Error code when the resource could not resolve (e.g. `NOT_FOUND`, `CONFIG_ERROR`). */
     error?: string;
 }
 interface ResolveAnyResult {
+    /** Which lookup phase produced this result, including an empty contains sweep. */
+    matched: 'exact' | 'contains';
+    /** Full per-resource records from the fallback sweep; present exactly when matched is contains. */
+    contains?: SearchAcrossResourcesResult;
     identifier: number | string;
     /** One outcome per requested resource, in request order. */
     results: ResolveAnyResourceOutcome[];
@@ -189,6 +163,39 @@ declare function searchAcrossResources(client: AutotaskClient, query: string, op
 
 declare function resolveAny(client: AutotaskClient, identifier: number | string, opts?: ResolveAnyOptions): Promise<ResolveAnyResult>;
 
+/** Staff lookup with tenant-labelled API-user exclusions and honest metadata state. */
+
+interface ResolveStaffOptions {
+    /** Match only email; even a digit string is treated as email. */
+    emailOnly?: boolean;
+    /** Include API users in text matches (default false). Numeric ids always bypass exclusions. */
+    includeApiUsers?: boolean;
+    /** Maximum returned candidates, 1..10 (default 10); the matched count remains available. */
+    limit?: number;
+}
+interface ResolveStaffMatch {
+    record: Record<string, unknown>;
+    /** Present only when tenant labels identify API users AND this record has a labelled value. */
+    apiUser?: boolean;
+    /** The tenant's label, verbatim. */
+    licenseTypeLabel?: string;
+}
+interface ResolveStaffResult {
+    identifier: Identifier;
+    lookup: 'id' | 'text';
+    matches: ResolveStaffMatch[];
+    /** Matches found after exclusions, before the candidate limit; a lower bound when truncated. */
+    matchedCount: number;
+    /** More records may exist, or candidates were cut by limit. Never treat a truncated singleton as unique. */
+    truncated: boolean;
+    /** ok: API labels found; none: labels found but no API label; absent: no labels exposed; error: metadata read failed. */
+    metadataState: 'ok' | 'none' | 'absent' | 'error';
+    /** Label coverage when the existing client labels option is enabled. */
+    names?: RowNamesSummary;
+}
+/** 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 {
@@ -819,8 +826,8 @@ type SanitiseResult = Record<string, unknown>;
  *                    `metadata.untrustedFields` decides the field list.
  * @returns A promise for a NEW result object with the present untrusted
  *          fields wrapped (the input is never mutated) when the operation
- *          declares untrusted fields — or the input returned unchanged
- *          (the same reference) when it declares none.
+ *          declares untrusted fields or contains UDF values to fence; otherwise
+ *          the input is returned unchanged (the same reference).
  * @throws {AutotaskConfigError} an unknown (non-string/empty, or not-in-the-
  *          registry) operation — typed, zero wire.
  */
@@ -1321,4 +1328,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, 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 };
+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 };

package/dist/operations/index.d.ts

@@ -1,20 +1,10 @@
-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';
-export { bd as FIELD_CACHE_KINDS } from '../index-C7rMJ4IV.js';
-import { I as Identifier, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-C3KFMnRT.js';
-export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-C3KFMnRT.js';
+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 { 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';
 import { CapabilityRecord } from '../capabilities.js';
-import { b as AutotaskConfigError } from '../base-CVx2VMSj.js';
-
-/** The `names` summary a labelled result carries ONLY when something was
- * left unlabelled: the cold-read cap was hit or a picklist could not be
- * resolved. Issue #287: the structured `truncated` / `capped` / catalogError
- * bookkeeping was trimmed — the note is the summary. */
-interface RowNamesSummary {
-    /** One line a reader can act on. */
-    note: string;
-    /** Picklist field -> why its `*Label` is null (the fieldCatalog honesty note / the value-not-served note). */
-    reasons?: Record<string, string>;
-}
+import { AutotaskConfigError } from '../index.js';
 
 /**
  * Cross-resource operations layer — shared types (ARCHITECTURE section 19.1,
@@ -94,19 +84,10 @@ interface FetchManyResult {
 interface ResolveAnyOptions {
     /** Resource keys to resolve against (default: the five workflow resources). */
     resources?: readonly string[];
-    /**
-     * Issue #287 (D7): the match mode (default `'exact'`).
-     * - `'exact'` — the per-resource exact resolution (numeric id first, then
-     *   exact on the primary text field); the historical behaviour.
-     * - `'auto'` — exact first (the same per-resource order); on a clean miss of a
-     *   NON-NUMERIC string identifier, a bounded case-insensitive CONTAINS on the
-     *   resource's primary text field (bounded by the resource's scan record cap —
-     *   default 500 records): exactly one hit resolves it (cost `'server-filter'`),
-     *   several hits report that resource as `RESOLUTION_AMBIGUOUS` with the
-     *   candidate ids, zero hits report the miss unchanged. A numeric id miss is
-     *   never re-scanned (the contains fallback is for text values only).
-     */
+    /** 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. */
     match?: 'exact' | 'auto';
+    /** 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. */
+    limit?: number;
 }
 /**
  * One resource's outcome. Unlike single-resource `resolve`, a miss does NOT
@@ -118,27 +99,20 @@ interface ResolveAnyResourceOutcome {
     value: Record<string, unknown> | null;
     /** How the match was found (or what was attempted). */
     resolutionCost: 'direct' | 'server-filter' | 'client-scan';
-    /**
-     * Records read by the bounded CLIENT scan fallback. The `match: 'auto'`
-     * server-filter contains fallback reads ZERO records client-side (the
-     * vendor applies the contains filter; the client receives at most the
-     * scan-cap matching rows) and reports `scanned: 0` with
-     * `resolutionCost: 'server-filter'`.
-     */
+    /** Records read by the bounded client scan. Server-filter contains outcomes report zero. */
     scanned: number;
-    /** True when the scan hit its cap (a complete non-match is unproven). */
+    /** True when a client scan or contains result hit its cap (completeness is unproven). */
     scanTruncated: boolean;
-    /**
-     * Candidate ids when the resource matched more than one record. The
-     * server-filter contains fallback's list is bounded by the scan record
-     * cap — a `RESOLUTION_AMBIGUOUS` outcome can carry up to the cap
-     * candidate ids (default 500).
-     */
+    /** Candidate ids on ambiguity or a cap-full contains result; contains candidates are bounded by limit. */
     candidates: (number | string)[];
     /** Error code when the resource could not resolve (e.g. `NOT_FOUND`, `CONFIG_ERROR`). */
     error?: string;
 }
 interface ResolveAnyResult {
+    /** Which lookup phase produced this result, including an empty contains sweep. */
+    matched: 'exact' | 'contains';
+    /** Full per-resource records from the fallback sweep; present exactly when matched is contains. */
+    contains?: SearchAcrossResourcesResult;
     identifier: number | string;
     /** One outcome per requested resource, in request order. */
     results: ResolveAnyResourceOutcome[];
@@ -189,6 +163,39 @@ declare function searchAcrossResources(client: AutotaskClient, query: string, op
 
 declare function resolveAny(client: AutotaskClient, identifier: number | string, opts?: ResolveAnyOptions): Promise<ResolveAnyResult>;
 
+/** Staff lookup with tenant-labelled API-user exclusions and honest metadata state. */
+
+interface ResolveStaffOptions {
+    /** Match only email; even a digit string is treated as email. */
+    emailOnly?: boolean;
+    /** Include API users in text matches (default false). Numeric ids always bypass exclusions. */
+    includeApiUsers?: boolean;
+    /** Maximum returned candidates, 1..10 (default 10); the matched count remains available. */
+    limit?: number;
+}
+interface ResolveStaffMatch {
+    record: Record<string, unknown>;
+    /** Present only when tenant labels identify API users AND this record has a labelled value. */
+    apiUser?: boolean;
+    /** The tenant's label, verbatim. */
+    licenseTypeLabel?: string;
+}
+interface ResolveStaffResult {
+    identifier: Identifier;
+    lookup: 'id' | 'text';
+    matches: ResolveStaffMatch[];
+    /** Matches found after exclusions, before the candidate limit; a lower bound when truncated. */
+    matchedCount: number;
+    /** More records may exist, or candidates were cut by limit. Never treat a truncated singleton as unique. */
+    truncated: boolean;
+    /** ok: API labels found; none: labels found but no API label; absent: no labels exposed; error: metadata read failed. */
+    metadataState: 'ok' | 'none' | 'absent' | 'error';
+    /** Label coverage when the existing client labels option is enabled. */
+    names?: RowNamesSummary;
+}
+/** 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 {
@@ -819,8 +826,8 @@ type SanitiseResult = Record<string, unknown>;
  *                    `metadata.untrustedFields` decides the field list.
  * @returns A promise for a NEW result object with the present untrusted
  *          fields wrapped (the input is never mutated) when the operation
- *          declares untrusted fields — or the input returned unchanged
- *          (the same reference) when it declares none.
+ *          declares untrusted fields or contains UDF values to fence; otherwise
+ *          the input is returned unchanged (the same reference).
  * @throws {AutotaskConfigError} an unknown (non-string/empty, or not-in-the-
  *          registry) operation — typed, zero wire.
  */
@@ -1321,4 +1328,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, 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 };
+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 };

package/dist/operations/index.js

@@ -61,6 +61,7 @@ import {
   isRecord,
   labelRows,
   monthsInWindow,
+  normalizeOwnField,
   normalizedConditions,
   num,
   parseIdentifier,
@@ -70,13 +71,13 @@ import {
   validateFetchManyItems,
   validateQueryFieldNames,
   validateWalkBag
-} from "../chunk-AETFO6BO.js";
+} from "../chunk-LYI5FRPX.js";
 import {
   CAPABILITIES
-} from "../chunk-WP33PQVM.js";
+} from "../chunk-N6IWPGHB.js";
 import {
   deepMarkUntrusted
-} from "../chunk-5VHSLJMR.js";
+} from "../chunk-A6LHCJQP.js";
 
 // src/operations/searchAcrossResources.ts
 var DEFAULT_LIMIT = 25;
@@ -147,6 +148,11 @@ async function resolveAny(client, identifier, opts = {}) {
   if (match !== "exact" && match !== "auto") {
     throw new AutotaskConfigError(`resolveAny: match must be 'exact' or 'auto' (got ${JSON.stringify(match)})`);
   }
+  if (opts.limit !== void 0 && (!Number.isInteger(opts.limit) || opts.limit < 1 || opts.limit > 500)) {
+    throw new AutotaskConfigError("resolveAny: limit must be an integer 1..500");
+  }
+  const configuredCap = Math.min(client.config?.resolution?.maxScanRecords ?? 500, 500);
+  const limit = Math.min(opts.limit ?? configuredCap, configuredCap);
   const results = [];
   for (const key of keys) {
     const holder = resourceFor2(client, key);
@@ -164,7 +170,7 @@ async function resolveAny(client, identifier, opts = {}) {
     }
     try {
       const r = await holder.resolveDetailed(identifier);
-      let outcome = {
+      const outcome = {
         resource: key,
         value: r.value ?? null,
         resolutionCost: r.resolutionCost,
@@ -172,22 +178,6 @@ async function resolveAny(client, identifier, opts = {}) {
         scanTruncated: r.scanTruncated,
         candidates: (r.candidates ?? []).map((c) => c.id)
       };
-      if (match === "auto" && outcome.value === null && typeof identifier === "string") {
-        const hits = await holder.resolveContainsMatches(identifier);
-        if (hits.length === 1) {
-          outcome = { resource: key, value: hits[0], resolutionCost: "server-filter", scanned: 0, scanTruncated: false, candidates: [] };
-        } else if (hits.length > 1) {
-          outcome = {
-            resource: key,
-            value: null,
-            resolutionCost: "server-filter",
-            scanned: 0,
-            scanTruncated: false,
-            candidates: hits.map((h) => h.id).filter((id) => typeof id === "number"),
-            error: "RESOLUTION_AMBIGUOUS"
-          };
-        }
-      }
       results.push(outcome);
     } catch (err) {
       let code;
@@ -214,8 +204,104 @@ async function resolveAny(client, identifier, opts = {}) {
       });
     }
   }
-  const matches = results.filter((r) => r.value !== null).map((r) => r.resource);
-  return { identifier, results, matches };
+  const cleanMiss = results.every((r) => r.value === null && r.candidates.length === 0 && !r.scanTruncated && (r.error === void 0 || r.error === "NOT_FOUND"));
+  if (match === "auto" && typeof identifier === "string" && !/^\d+$/.test(identifier.trim()) && cleanMiss) {
+    const contains = await searchAcrossResources(client, identifier, { resources: keys, limit });
+    for (const row of contains.results) {
+      const outcome = results.find((r) => r.resource === row.resource);
+      if (outcome === void 0 || row.matches.length === 0) continue;
+      const truncated = row.matches.length >= limit;
+      outcome.resolutionCost = "server-filter";
+      outcome.scanned = 0;
+      outcome.scanTruncated = truncated;
+      if (row.matches.length === 1 && !truncated) {
+        outcome.value = row.matches[0];
+        delete outcome.error;
+      } else {
+        outcome.candidates = row.matches.map((r) => r.id).filter((id) => typeof id === "number" || typeof id === "string");
+        outcome.error = truncated ? "RESOLUTION_TRUNCATED" : "RESOLUTION_AMBIGUOUS";
+      }
+    }
+    return { identifier, results, matches: results.filter((r) => r.value !== null).map((r) => r.resource), matched: "contains", contains };
+  }
+  return { identifier, results, matches: results.filter((r) => r.value !== null).map((r) => r.resource), matched: "exact" };
+}
+
+// src/operations/resolveStaff.ts
+async function staffLabels(client) {
+  const out = { api: {}, labels: {}, state: "absent" };
+  try {
+    const catalog = await fieldCatalog(client, { resources: ["resources"], fields: ["licenseType", "userType"], labels: true });
+    const row = catalog.rows[0];
+    if (row === void 0 || row.error !== null) return { ...out, state: "error" };
+    for (const field of row.fields ?? []) {
+      if (!field.picklistValues?.length) continue;
+      const labels = /* @__PURE__ */ new Map();
+      out.labels[field.name] = labels;
+      for (const value of field.picklistValues) {
+        if (typeof value.label !== "string") continue;
+        labels.set(String(value.value), value.label);
+        if (/\bapi\b/i.test(value.label)) (out.api[field.name] ??= /* @__PURE__ */ new Set()).add(String(value.value));
+      }
+    }
+    out.state = Object.keys(out.api).length > 0 ? "ok" : Object.keys(out.labels).length > 0 ? "none" : "absent";
+    return out;
+  } catch {
+    return { ...out, state: "error" };
+  }
+}
+function staffFilter(text, api, emailOnly) {
+  const base = [
+    { field: "isActive", op: "eq", value: true },
+    ...Object.entries(api).map(([field, values]) => ({ field, op: "notIn", value: [...values] }))
+  ];
+  if (emailOnly) return [...base, { field: "email", op: "eq", value: text }];
+  const words = text.split(/\s+/);
+  const names = words.length === 1 ? [{ field: "firstName", op: "eq", value: text }, { field: "lastName", op: "eq", value: text }] : Array.from({ length: words.length - 1 }, (_, i) => ({ op: "and", items: [
+    { field: "firstName", op: "eq", value: words.slice(0, i + 1).join(" ") },
+    { field: "lastName", op: "eq", value: words.slice(i + 1).join(" ") }
+  ] }));
+  return [...base, { op: "or", items: [{ field: "email", op: "eq", value: text }, { field: "userName", op: "eq", value: text }, ...names] }];
+}
+async function resolveStaff(client, identifier, opts = {}) {
+  if (!isRecord(opts) || ![Object.prototype, null].includes(Object.getPrototypeOf(opts))) {
+    throw new AutotaskConfigError("resolveStaff: opts must be a plain options object");
+  }
+  const keys = ["emailOnly", "includeApiUsers", "limit"];
+  const unknown = Object.keys(opts).filter((key) => !keys.includes(key));
+  if (unknown.length > 0) {
+    const listed = unknown.slice(0, 10).map((key) => JSON.stringify(key.length > 40 ? `${key.slice(0, 40)}\u2026` : key)).join(", ");
+    throw new AutotaskConfigError(`resolveStaff: unknown opts key(s) ${listed}${unknown.length > 10 ? ` (and ${unknown.length - 10} more)` : ""} \u2014 the bag is closed: ${keys.join(", ")}`);
+  }
+  for (const key of ["emailOnly", "includeApiUsers"]) {
+    if (opts[key] !== void 0 && typeof opts[key] !== "boolean") {
+      throw new AutotaskConfigError(`resolveStaff: ${key} must be a boolean`);
+    }
+  }
+  const limit = opts.limit === void 0 ? 10 : opts.limit;
+  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 10) throw new AutotaskConfigError("resolveStaff: limit must be an integer 1..10");
+  if (typeof identifier !== "number" && typeof identifier !== "string") throw new AutotaskConfigError("resolveStaff: identifier must be a number or string");
+  const text = String(identifier).trim();
+  if (text === "") throw new AutotaskConfigError("resolveStaff: identifier must be non-empty");
+  if (typeof identifier === "number") parseIdentifier(identifier, "resolveStaff identifier");
+  const id = !opts.emailOnly && (typeof identifier === "number" || /^\d+$/.test(text)) ? parseIdentifier(identifier, "resolveStaff identifier") : void 0;
+  const meta = await staffLabels(client);
+  const isApi = (record) => Object.entries(meta.api).some(([field, values]) => record[field] != null && values.has(String(record[field])));
+  const match = (record) => {
+    const known = meta.state === "ok" && Object.entries(meta.labels).some(([field, labels]) => record[field] != null && labels.has(String(record[field])));
+    const label = meta.labels.licenseType?.get(String(record.licenseType));
+    return { record, ...known ? { apiUser: isApi(record) } : {}, ...label === void 0 ? {} : { licenseTypeLabel: label } };
+  };
+  if (id !== void 0) {
+    const record = await client.resources.get(id);
+    const matches = [match(record)];
+    return { identifier, lookup: "id", matches, matchedCount: matches.length, truncated: false, metadataState: meta.state };
+  }
+  const page = await client.resources.queryBounded({ filter: staffFilter(text, opts.includeApiUsers ? {} : meta.api, opts.emailOnly === true), limit: 50 });
+  const rawRows = page.items;
+  const labelled = readNamesOpt(client, void 0, "resolveStaff") ? await labelRows(client, "resources", rawRows) : void 0;
+  const rows = (labelled?.rows ?? rawRows).filter((record) => opts.includeApiUsers || !isApi(record)).sort((a, b) => Number(isApi(a)) - Number(isApi(b)));
+  return { identifier, lookup: "text", matches: rows.slice(0, limit).map(match), matchedCount: rows.length, truncated: page.hasMore || rows.length > limit, metadataState: meta.state, ...labelled?.names === void 0 ? {} : { names: labelled.names } };
 }
 
 // src/operations/aggregate.ts
@@ -400,7 +486,7 @@ async function checkFieldNames(resourceKey, conditions, opts, problems) {
   const strings = (v) => Array.isArray(v) ? v.filter((f) => typeof f === "string" && f.trim() !== "") : [];
   const groupBy = strings(opts.groupBy);
   const found = await findUnknownFieldNames(record, void 0, {
-    filter: collectFilterFieldNames(conditions, resourceKey),
+    filter: collectFilterFieldNames(conditions, resourceKey, "operations.aggregate"),
     groupBy: groupBy.map((f) => f.split("@")[0]),
     sum: strings(opts.sum)
   });
@@ -422,6 +508,13 @@ async function validateAggregate(operation, filter, opts) {
   const resourceKey = parseOperationKey(operation, problems);
   const conditions = parseFilterConditions(filter, problems);
   checkOptsBag(opts, problems);
+  if (resourceKey !== void 0) {
+    opts = {
+      ...opts,
+      ...Array.isArray(opts.groupBy) ? { groupBy: opts.groupBy.map((f) => typeof f === "string" ? normalizeOwnField(resourceKey, f) : f) } : {},
+      ...Array.isArray(opts.sum) ? { sum: opts.sum.map((f) => typeof f === "string" ? normalizeOwnField(resourceKey, f) : f) } : {}
+    };
+  }
   const oracles = {
     resourceKey,
     dateSets: resourceKey !== void 0 ? MODEL_DATE_FIELDS[resourceKey] : void 0
@@ -1437,8 +1530,7 @@ async function sanitiseResult(client, result, operation) {
     );
   }
   const fields = record.metadata?.untrustedFields;
-  if (!Array.isArray(fields) || fields.length === 0) return result;
-  return deepMarkUntrusted(result, fields);
+  return deepMarkUntrusted(result, Array.isArray(fields) ? fields : []);
 }
 
 // src/operations/recovery.ts
@@ -1994,8 +2086,7 @@ async function guardUnscopedQueryWalk(holder, operation, bag) {
   const walk = typeof bag?.["walk"] === "object" && bag?.["walk"] !== null ? bag?.["walk"] : void 0;
   const maxRows = typeof walk?.maxRows === "number" ? walk.maxRows : void 0;
   const effectiveLimit = typeof limit === "number" ? limit : BOUNDED_QUERY_DEFAULT_LIMIT;
-  let walked = typeof latest === "number" ? Math.max(effectiveLimit, latest) : effectiveLimit;
-  if (maxRows !== void 0) walked = Math.min(walked, maxRows);
+  const walked = maxRows ?? (typeof latest === "number" ? Math.max(effectiveLimit, latest) : effectiveLimit);
   if (walked <= UNSCOPED_WALK_THRESHOLD || hasIdScope(filter)) return {};
   let conditions;
   try {
@@ -2089,6 +2180,7 @@ function governPreRequest(record, operation, opts) {
 }
 function operationsHolder(client) {
   return {
+    resolveStaff: (identifier, opts) => resolveStaff(client, identifier, opts),
     resolveAny: (identifier, opts) => resolveAny(client, identifier, opts),
     searchAcrossResources: (query, opts) => searchAcrossResources(client, query, opts),
     fetchMany: (items, opts) => fetchMany(client, items, opts),
@@ -2244,7 +2336,7 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
     scopeNote = (await guardUnscopedQueryWalk(holder, record.id, args[0])).note;
   }
   const result = await method.apply(holder, callArgs);
-  if (labelQuery && Array.isArray(result?.items)) {
+  if (labelQuery && args[0]?.["walk"] === void 0 && Array.isArray(result?.items)) {
     const bounded = result;
     const labelled = await labelRows(client, record.resource, bounded.items);
     return { ...bounded, items: labelled.rows, ...labelled.names !== void 0 ? { names: labelled.names } : {}, ...scopeNote !== void 0 ? { scopeNote } : {} };
@@ -2307,6 +2399,7 @@ export {
   recovery,
   relationshipMap,
   resolveAny,
+  resolveStaff,
   revenueRollup,
   sanitiseResult,
   searchAcrossResources,

package/dist/pool.cjs

@@ -1,21 +1,21 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
 
-var _chunkMYL34QU5cjs = require('./chunk-MYL34QU5.cjs');
-require('./chunk-HD5BRA3Z.cjs');
+var _chunkKWQSGWY5cjs = require('./chunk-KWQSGWY5.cjs');
+require('./chunk-6WLGHKIU.cjs');
 
 
 
 
-var _chunkSEFJJY4Jcjs = require('./chunk-SEFJJY4J.cjs');
-require('./chunk-VEOSOIU4.cjs');
-require('./chunk-MJTKK3QG.cjs');
+var _chunkEMYDC5SGcjs = require('./chunk-EMYDC5SG.cjs');
+require('./chunk-PH3ESYAF.cjs');
+require('./chunk-SN4BMQ2N.cjs');
 
 // src/pool.ts
 var _crypto = require('crypto');
 function createClientPool(options = {}) {
   const maxSize = _nullishCoalesce(options.maxSize, () => ( 128));
   if (!Number.isInteger(maxSize) || maxSize < 1) {
-    throw new (0, _chunkSEFJJY4Jcjs.AutotaskConfigError)(
+    throw new (0, _chunkEMYDC5SGcjs.AutotaskConfigError)(
       `ClientPool maxSize must be a positive integer (got ${String(options.maxSize)})`
     );
   }
@@ -30,7 +30,7 @@ function createClientPool(options = {}) {
       readCaches.set(key, existing);
       return existing;
     }
-    const created = _chunkSEFJJY4Jcjs.buildReadCache.call(void 0, config);
+    const created = _chunkEMYDC5SGcjs.buildReadCache.call(void 0, config);
     if (created === void 0) return void 0;
     readCaches.set(key, created);
     while (readCaches.size > maxSize) {
@@ -47,7 +47,7 @@ function createClientPool(options = {}) {
     return { ...config, cache };
   }
   function keyFor(config) {
-    const resolved = _chunkSEFJJY4Jcjs.resolveCredentials.call(void 0, config);
+    const resolved = _chunkEMYDC5SGcjs.resolveCredentials.call(void 0, config);
     const tuple = [
       resolved.userName,
       resolved.apiIntegrationCode,
@@ -70,7 +70,7 @@ function createClientPool(options = {}) {
         const oldest = entries.keys().next().value;
         if (oldest !== void 0) entries.delete(oldest);
       }
-      const client = new (0, _chunkMYL34QU5cjs.AutotaskClient)(withSharedCache(config, sharedCacheFor(key, config)));
+      const client = new (0, _chunkKWQSGWY5cjs.AutotaskClient)(withSharedCache(config, sharedCacheFor(key, config)));
       entries.set(key, client);
       return client;
     },

package/dist/pool.d.cts

@@ -1,5 +1,5 @@
-import { A as AutotaskConfig, a as AutotaskClient } from './index-Cm_Xpt7X.cjs';
-import './index-C3KFMnRT.cjs';
+import { AutotaskConfig, AutotaskClient } from './index.cjs';
+import './index-DgBA1JMH.cjs';
 
 interface ClientPoolOptions {
     /** Bounded LRU capacity (positive integer). Default 128. */
@@ -44,4 +44,5 @@ interface ClientPool {
  */
 declare function createClientPool(options?: ClientPoolOptions): ClientPool;
 
-export { type ClientPool, type ClientPoolOptions, createClientPool };
+export { createClientPool };
+export type { ClientPool, ClientPoolOptions };

package/dist/pool.d.ts

@@ -1,5 +1,5 @@
-import { A as AutotaskConfig, a as AutotaskClient } from './index-C7rMJ4IV.js';
-import './index-C3KFMnRT.js';
+import { AutotaskConfig, AutotaskClient } from './index.js';
+import './index-DgBA1JMH.js';
 
 interface ClientPoolOptions {
     /** Bounded LRU capacity (positive integer). Default 128. */
@@ -44,4 +44,5 @@ interface ClientPool {
  */
 declare function createClientPool(options?: ClientPoolOptions): ClientPool;
 
-export { type ClientPool, type ClientPoolOptions, createClientPool };
+export { createClientPool };
+export type { ClientPool, ClientPoolOptions };