node-autotask 0.33.0 → 0.37.0

package/dist/operations/index.d.cts

@@ -1,5 +1,5 @@
-import { a as AutotaskClient, ev as BlindSurfaceInfo, ew as RelationshipResource, ex as BlindSurfaceInventory, ey as BlindSurfaceRow, ez as CreateGuidanceRow, eA as CreateBlockerKind, eB as CreateGuidanceReport, Z as ZoneName, eC as FieldCacheKind, k as AutotaskConfigError } from '../index-Cq0VsfSz.cjs';
-export { eD as FIELD_CACHE_KINDS } from '../index-Cq0VsfSz.cjs';
+import { a as AutotaskClient, eF as BlindSurfaceInfo, eG as RelationshipResource, eH as BlindSurfaceInventory, eI as BlindSurfaceRow, eJ as CreateGuidanceValueRequirement, eK as CreateGuidanceRow, eL as CreateBlockerKind, eM as CreateGuidanceReport, Z as ZoneName, eN as FieldCacheKind, k as AutotaskConfigError } from '../index-g8J6Qiu1.cjs';
+export { eO as FIELD_CACHE_KINDS } from '../index-g8J6Qiu1.cjs';
 import { I as Identifier, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-m-7fOwFl.cjs';
 export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-m-7fOwFl.cjs';
 import { CapabilityRecord } from '../capabilities.cjs';
@@ -138,6 +138,13 @@ interface InvokeOptions {
      * under `dryRun: true` (no wire).
      */
     maxRetries?: number;
+    /**
+     * Issue #250: `true` makes a single-record `<resource>.get` bypass the read
+     * cache lookup and refresh the entry with the live response (a read-back
+     * after a write made elsewhere). Honoured ONLY on a `get` read; any other
+     * operation refuses it pre-request. Omitted/`false` = the cached default.
+     */
+    fresh?: boolean;
 }
 
 declare function searchAcrossResources(client: AutotaskClient, query: string, opts?: SearchAcrossResourcesOptions): Promise<SearchAcrossResourcesResult>;
@@ -280,6 +287,146 @@ 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';
+/** The closed opts bag. Exactly one scope key is required. */
+interface RevenueRollupOptions {
+    companyIDs?: number[];
+    /** `companies.ownerResourceID`, resolved to company ids (one projected query) before the walk. */
+    ownerResourceID?: number;
+    contractIDs?: number[];
+    tenantWide?: true;
+    /** 'YYYY-MM-DD', inclusive. */
+    dateFrom: string;
+    /** 'YYYY-MM-DD', inclusive; window ≤ 36 months. */
+    dateTo: string;
+    /** Ids or labels; default = the live labels that START with 'Recurring' or 'Fixed' (case-insensitive). */
+    contractTypes?: Array<number | string>;
+    contractCategories?: Array<number | string>;
+    /** Default ['vertical', 'contractType']. */
+    groupBy?: RevenueRollupDimension[];
+    /** Rows kept (default 100, cap 100); the tail folds into `rowsTruncated`. */
+    top?: number;
+    /** Vendor-call budget (default 90, or 150 with includeNonChargeable; cap 200). */
+    maxVendorCalls?: number;
+    /** Add per-row non-chargeable work (contract-covered and non-billable: value + hours), never added to revenue. Default false. */
+    includeNonChargeable?: boolean;
+}
+/** A dimension value: picklist text in `label`, vendor entity text (untrusted) in `name` (and, for lineOfBusiness, `division`). */
+interface RevenueRollupKey {
+    id: number | string | null;
+    label?: string;
+    name?: string;
+    division?: string;
+}
+interface RevenueRollupAmount {
+    amount: number;
+    lines: number;
+}
+/** Non-chargeable work: Σ internalCurrencyExtendedPrice (`value`), Σ quantity on labour lines (`hours`), line count. */
+interface RevenueRollupNonChargeableAmount {
+    value: number;
+    hours: number;
+    lines: number;
+}
+interface RevenueRollupNonChargeable {
+    contractCovered: RevenueRollupNonChargeableAmount;
+    nonBillable: RevenueRollupNonChargeableAmount;
+}
+interface RevenueRollupRow {
+    keys: Partial<Record<RevenueRollupDimension, RevenueRollupKey>>;
+    revenue: number;
+    credits: RevenueRollupAmount;
+    includedValue: number;
+    contracts: number;
+    items: number;
+    /** Only with includeNonChargeable; never part of `revenue`. */
+    nonChargeable?: RevenueRollupNonChargeable;
+}
+interface RevenueRollupResult {
+    window: {
+        dateFrom: string;
+        dateTo: string;
+        basis: 'invoiceDate';
+    };
+    scope: {
+        kind: 'companyIDs' | 'ownerResourceID' | 'contractIDs' | 'tenantWide';
+        ownerResourceID?: number;
+        ids?: number[];
+    };
+    groupBy: RevenueRollupDimension[];
+    top: number;
+    rows: RevenueRollupRow[];
+    rowsTruncated?: {
+        rows: number;
+        revenue: number;
+    };
+    totals: {
+        revenue: number;
+        credits: number;
+        includedValue: number;
+        contracts: number;
+        items: number;
+        nonChargeable?: RevenueRollupNonChargeable;
+    };
+    coverage: {
+        /** Logical vendor requests through the budget wrapper; transport retries (429 / 5xx, up to maxRetries each) are not counted. */
+        vendorCalls: number;
+        budget: number;
+        estimate: number;
+        /** vendorCalls as a share of the 10,000/h tenant limit (a floor: transport retries are not counted). */
+        tenantHourlyShare: string;
+        contractTypeMap: Record<string, string>;
+        contractCategoryMap?: Record<string, string>;
+        reconciliation: {
+            headerTotal: number;
+            lineTotal: number;
+            delta: number;
+            invoicesChecked: number;
+            invoicesMismatched: number;
+        };
+        /** Informational overlay, NOT an excluded bucket: zero-total invoices in scope and their lines (those lines are still folded into rows / the buckets). */
+        zeroTotalInvoices: {
+            count: number;
+        } & RevenueRollupAmount;
+        excluded: {
+            /** Header figures of the window's voided invoices in scope (company scopes: header companyID in scope). Absent for a contractIDs scope: an invoice header cannot be attributed to a contract. */
+            voidedInvoices?: {
+                count: number;
+                headerAmount: number;
+            };
+            uncontracted: RevenueRollupAmount;
+            otherContractTypes: Record<string, RevenueRollupAmount>;
+            otherContractCategories: Record<string, RevenueRollupAmount>;
+            unresolvedContracts: RevenueRollupAmount;
+            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;
+        };
+        /** Only when lineOfBusiness is grouped: in-scope lines with no LOB pointer (also their own "no LOB assigned" row). */
+        lineOfBusiness?: {
+            noPointer: RevenueRollupAmount;
+            note: string;
+        };
+        blindSurfaces: string[];
+        notes: string[];
+    };
+}
+/**
+ * `operations.revenueRollup` — see the module header.
+ *
+ * ```ts
+ * import { revenueRollup } from 'node-autotask/operations';
+ * const r = await revenueRollup(client, { tenantWide: true, dateFrom: '2025-07-01', dateTo: '2026-06-30' });
+ * ```
+ */
+declare function revenueRollup(client: AutotaskClient, opts: RevenueRollupOptions): Promise<RevenueRollupResult>;
+
 /** The pinned per-call item cap (total items per call, mixed resources — the issue's "500 ids" budget; over → CONFIG_ERROR pre-request, zero wire). */
 declare const FETCH_BY_IDS_MAX_ITEMS = 500;
 /** The pinned `id in` chunk size (250/chunk — the chunk query is a single page: 250 is well under the 500 vendor page max). */
@@ -430,38 +577,42 @@ declare function probeReachability(client: AutotaskClient, opts?: ProbeReachabil
  * Three sources answer that question, at three different coverages, and the
  * SDK used to leave the choice to each caller:
  *   1. `createGuidance.liveProvenPrefix` — the fields a live create actually
- *      demanded, in vendor-demand order (92 rows; the widest evidence);
- *   2. `zoneFacts.createRequiredSet` — the hand-authored zone set (6
- *      resources);
+ *      demanded, in vendor-demand order (the widest evidence);
+ *   2. `zoneFacts.createRequiredSet` — the hand-authored zone set;
  *   3. the vendor field catalog's `isRequired` — the spec opinion (wrong for
- *      68 of the 75 resources that carry a proven prefix).
+ *      most resources that carry a proven prefix).
  *
  * The order is FIXED and stated: live-proven > zone > spec, with the source
  * named on the result (`from`). Both plan shapes stay where they are; this
  * helper is the only place in the SDK that compares them.
  *
- * Value-conditioned prefixes: a prefix proven for one picklist value (e.g.
- * `contracts.create`'s type-1 `estimatedRevenue`/`estimatedHours`/
- * `estimatedCost`) is still returned whole with `from: 'live-proven'` — the
- * condition itself lives on the create-guidance row (`blocker.message` +
- * `vendorEvidence`), which a caller must read before treating the list as
- * unconditional. Never flatten a conditioned row into "all these fields are
- * always required"; the row's evidence is the qualifier.
+ * Value-conditioned fields: a field the row gates on a picklist value
+ * (`requiresByValue`, e.g. `contracts.create` needs `estimatedHours` only for
+ * `contractType` 1) is never returned as unconditionally required. It is
+ * removed from `fields`, and the gates are returned, typed, on `conditional`.
+ *
+ * `unproven` is true when no live create is known to succeed with the
+ * returned set: the plan row says the create still failed after the prefix,
+ * or the set is only the vendor spec's opinion.
  */
 
 /** Which source the returned field set came from (the precedence order). */
 type RequiredFieldsSource = 'live-proven' | 'zone' | 'spec';
 /** The effective required set + the source it came from. */
 interface EffectiveRequiredFields {
-    /** The required field names, in the source's own order (vendor-demand order for a live-proven prefix). */
+    /** The unconditionally required field names, in the source's own order (vendor-demand order for a live-proven prefix). Fields gated by a value are on `conditional`, not here. */
     fields: string[];
     /** `live-proven` (createGuidance.liveProvenPrefix) > `zone` (createRequiredSet) > `spec` (vendor isRequired). */
     from: RequiredFieldsSource;
+    /** True when no live create is known to succeed with this set (the plan row is unproven, or the set is the spec's opinion only). */
+    unproven: boolean;
+    /** The value-conditioned gates (`createGuidance.requiresByValue`); present only when the row declares some. Their fields are not in `fields`. */
+    conditional?: CreateGuidanceValueRequirement[];
 }
 /** The plan zone-fact shape this helper reads (both shapes stay plan-owned). */
 interface RequiredFieldsZoneFacts {
     createRequiredSet?: string[];
-    createGuidance?: Pick<CreateGuidanceRow, 'liveProvenPrefix' | 'unproven'> | null;
+    createGuidance?: Pick<CreateGuidanceRow, 'liveProvenPrefix' | 'unproven' | 'requiresByValue'> | null;
 }
 /** The spec-side record this helper reads (the vendor field catalog's projection). */
 interface RequiredFieldsRecord {
@@ -477,27 +628,30 @@ interface RequiredFieldsRecord {
  *   { requiredFields: vendorRequiredNames },   // from operations.fieldCatalog
  *   RELATIONSHIP_MAP.contacts.zoneFacts,       // the plan zone facts
  * );
- * // contacts: { fields: ['firstName', 'lastName', 'companyID', 'isActive'], from: 'live-proven' }
+ * // contacts: { fields: ['firstName', 'lastName', 'companyID', 'isActive'], from: 'live-proven', unproven: false }
  * ```
  *
  * An empty or absent higher source falls through to the next one; with no
- * source at all the result is `{ fields: [], from: 'spec' }` — the name of the
- * source is always stated, never a bare list.
+ * source at all the result is `{ fields: [], from: 'spec', unproven: true }` —
+ * the name of the source is always stated, never a bare list.
  */
 declare function effectiveRequiredFields(record?: RequiredFieldsRecord | null, zoneFacts?: RequiredFieldsZoneFacts | null): EffectiveRequiredFields;
 
-/** The closed blocker-kind set (the gate re-derives it; unknown kind → CONFIG_ERROR). */
 /**
- * The closed blocker-kind set served by `operations.createGuidance`.
- * Superset of issue #12's 8-value enumeration: the campaign decode produced
- * 14 rows that matched no named blocker (wall-adjacent create shapes with
- * verbatim vendor evidence) — the closed set gained `'unknown'` (9 kinds)
- * rather than forcing those rows into a misfitting class.
+ * The closed blocker-kind set served by `operations.createGuidance` (the gate
+ * re-derives it; an unknown kind is a CONFIG_ERROR on the filter).
+ *
+ * `'non-mutable'` is a create blocker: the vendor refuses the create write
+ * itself for the entity (no row carries it today). `'delete-absent'` is NOT a
+ * create blocker — a missing vendor DELETE is `deleteBoundary` — so the kind
+ * is reserved and no row carries it (the gate fails a row that does); it
+ * stays in the set so existing `kind` filters keep working. `'unknown'`
+ * covers wall-adjacent rows that match no named class.
  */
 declare const CREATE_BLOCKER_KINDS: readonly CreateBlockerKind[];
 /** One served create-guidance row: the plan row plus the effective required set (issue #219 N4). */
 interface ServedCreateGuidanceRow extends CreateGuidanceRow {
-    /** The effective create-required set + the source it came from (`live-proven` > `zone` > `spec`). Read `blocker`/`vendorEvidence` before treating a value-conditioned prefix as unconditional. */
+    /** The effective create-required set + the source it came from (`live-proven` > `zone` > `spec`). `fields` excludes value-gated fields (see `conditional`) and `unproven` says whether a live create is known to succeed with the set. */
     requiredFields: EffectiveRequiredFields;
 }
 /** The served report (the plan report with the effective required set on every row). */
@@ -682,7 +836,7 @@ interface FieldCatalogRow {
     resource: string;
     /** The vendor entity name (the path segment; plan-derived). */
     apiEntity: string;
-    /** True when the plan carries a `getUdfInfo` row for the resource (the vendor defines a UDF catalog endpoint for every entity resource — the catalog may answer an empty list). */
+    /** The plan resource's `udfCapable` flag, read from the registry record (`CapabilityRecord.udfCapable`, issue #254): true for the resources whose records carry `userDefinedFields`. Every vendor entity has a `getUdfInfo` catalog endpoint, so the `udf` include works on any row; that endpoint's presence does not make a resource UDF-capable. */
     udfCapable: boolean;
     /** The filter mechanism for a UDF name — present exactly when `udfCapable`: a filter on a UDF name is accepted only with the vendor's `udf: true` marker (a plain filter is refused), so the row states the marker rather than leaving a consumer to read the UDF rows' `isQueryable` (issue #219 N7). */
     udfFilter?: 'udf-marker';
@@ -745,7 +899,7 @@ interface FieldCatalogResult {
         resources: number;
         /** The plan's `getFieldInfo`-bearing resource count (the field-capable set). */
         fieldCapableResources: number;
-        /** The plan's `getUdfInfo`-bearing resource count (the vendor defines a UDF catalog endpoint for these; the narrower plan `udfCapable` flag — entities that actually carry UDFs — is a subset). */
+        /** The plan's `udfCapable` resource count (issue #254: the resources whose records carry `userDefinedFields` — not the wider set with a `getUdfInfo` catalog endpoint). */
         udfCapableResources: number;
         /** The rows served fully from the cache. */
         cached: number;
@@ -1067,4 +1221,4 @@ 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, ENTITY_TYPE_TO_RESOURCE, 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 FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, 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 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, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+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, ENTITY_TYPE_TO_RESOURCE, 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 FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, 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 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, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, revenueRollup, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };

package/dist/operations/index.d.ts

@@ -1,5 +1,5 @@
-import { a as AutotaskClient, ev as BlindSurfaceInfo, ew as RelationshipResource, ex as BlindSurfaceInventory, ey as BlindSurfaceRow, ez as CreateGuidanceRow, eA as CreateBlockerKind, eB as CreateGuidanceReport, Z as ZoneName, eC as FieldCacheKind, k as AutotaskConfigError } from '../index-BaeMHZPk.js';
-export { eD as FIELD_CACHE_KINDS } from '../index-BaeMHZPk.js';
+import { a as AutotaskClient, eF as BlindSurfaceInfo, eG as RelationshipResource, eH as BlindSurfaceInventory, eI as BlindSurfaceRow, eJ as CreateGuidanceValueRequirement, eK as CreateGuidanceRow, eL as CreateBlockerKind, eM as CreateGuidanceReport, Z as ZoneName, eN as FieldCacheKind, k as AutotaskConfigError } from '../index-DAFg_68I.js';
+export { eO as FIELD_CACHE_KINDS } from '../index-DAFg_68I.js';
 import { I as Identifier, cX as EmptyReasonInfo, e9 as PickListValue, a as FilterCondition } from '../index-m-7fOwFl.js';
 export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-m-7fOwFl.js';
 import { CapabilityRecord } from '../capabilities.js';
@@ -138,6 +138,13 @@ interface InvokeOptions {
      * under `dryRun: true` (no wire).
      */
     maxRetries?: number;
+    /**
+     * Issue #250: `true` makes a single-record `<resource>.get` bypass the read
+     * cache lookup and refresh the entry with the live response (a read-back
+     * after a write made elsewhere). Honoured ONLY on a `get` read; any other
+     * operation refuses it pre-request. Omitted/`false` = the cached default.
+     */
+    fresh?: boolean;
 }
 
 declare function searchAcrossResources(client: AutotaskClient, query: string, opts?: SearchAcrossResourcesOptions): Promise<SearchAcrossResourcesResult>;
@@ -280,6 +287,146 @@ 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';
+/** The closed opts bag. Exactly one scope key is required. */
+interface RevenueRollupOptions {
+    companyIDs?: number[];
+    /** `companies.ownerResourceID`, resolved to company ids (one projected query) before the walk. */
+    ownerResourceID?: number;
+    contractIDs?: number[];
+    tenantWide?: true;
+    /** 'YYYY-MM-DD', inclusive. */
+    dateFrom: string;
+    /** 'YYYY-MM-DD', inclusive; window ≤ 36 months. */
+    dateTo: string;
+    /** Ids or labels; default = the live labels that START with 'Recurring' or 'Fixed' (case-insensitive). */
+    contractTypes?: Array<number | string>;
+    contractCategories?: Array<number | string>;
+    /** Default ['vertical', 'contractType']. */
+    groupBy?: RevenueRollupDimension[];
+    /** Rows kept (default 100, cap 100); the tail folds into `rowsTruncated`. */
+    top?: number;
+    /** Vendor-call budget (default 90, or 150 with includeNonChargeable; cap 200). */
+    maxVendorCalls?: number;
+    /** Add per-row non-chargeable work (contract-covered and non-billable: value + hours), never added to revenue. Default false. */
+    includeNonChargeable?: boolean;
+}
+/** A dimension value: picklist text in `label`, vendor entity text (untrusted) in `name` (and, for lineOfBusiness, `division`). */
+interface RevenueRollupKey {
+    id: number | string | null;
+    label?: string;
+    name?: string;
+    division?: string;
+}
+interface RevenueRollupAmount {
+    amount: number;
+    lines: number;
+}
+/** Non-chargeable work: Σ internalCurrencyExtendedPrice (`value`), Σ quantity on labour lines (`hours`), line count. */
+interface RevenueRollupNonChargeableAmount {
+    value: number;
+    hours: number;
+    lines: number;
+}
+interface RevenueRollupNonChargeable {
+    contractCovered: RevenueRollupNonChargeableAmount;
+    nonBillable: RevenueRollupNonChargeableAmount;
+}
+interface RevenueRollupRow {
+    keys: Partial<Record<RevenueRollupDimension, RevenueRollupKey>>;
+    revenue: number;
+    credits: RevenueRollupAmount;
+    includedValue: number;
+    contracts: number;
+    items: number;
+    /** Only with includeNonChargeable; never part of `revenue`. */
+    nonChargeable?: RevenueRollupNonChargeable;
+}
+interface RevenueRollupResult {
+    window: {
+        dateFrom: string;
+        dateTo: string;
+        basis: 'invoiceDate';
+    };
+    scope: {
+        kind: 'companyIDs' | 'ownerResourceID' | 'contractIDs' | 'tenantWide';
+        ownerResourceID?: number;
+        ids?: number[];
+    };
+    groupBy: RevenueRollupDimension[];
+    top: number;
+    rows: RevenueRollupRow[];
+    rowsTruncated?: {
+        rows: number;
+        revenue: number;
+    };
+    totals: {
+        revenue: number;
+        credits: number;
+        includedValue: number;
+        contracts: number;
+        items: number;
+        nonChargeable?: RevenueRollupNonChargeable;
+    };
+    coverage: {
+        /** Logical vendor requests through the budget wrapper; transport retries (429 / 5xx, up to maxRetries each) are not counted. */
+        vendorCalls: number;
+        budget: number;
+        estimate: number;
+        /** vendorCalls as a share of the 10,000/h tenant limit (a floor: transport retries are not counted). */
+        tenantHourlyShare: string;
+        contractTypeMap: Record<string, string>;
+        contractCategoryMap?: Record<string, string>;
+        reconciliation: {
+            headerTotal: number;
+            lineTotal: number;
+            delta: number;
+            invoicesChecked: number;
+            invoicesMismatched: number;
+        };
+        /** Informational overlay, NOT an excluded bucket: zero-total invoices in scope and their lines (those lines are still folded into rows / the buckets). */
+        zeroTotalInvoices: {
+            count: number;
+        } & RevenueRollupAmount;
+        excluded: {
+            /** Header figures of the window's voided invoices in scope (company scopes: header companyID in scope). Absent for a contractIDs scope: an invoice header cannot be attributed to a contract. */
+            voidedInvoices?: {
+                count: number;
+                headerAmount: number;
+            };
+            uncontracted: RevenueRollupAmount;
+            otherContractTypes: Record<string, RevenueRollupAmount>;
+            otherContractCategories: Record<string, RevenueRollupAmount>;
+            unresolvedContracts: RevenueRollupAmount;
+            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;
+        };
+        /** Only when lineOfBusiness is grouped: in-scope lines with no LOB pointer (also their own "no LOB assigned" row). */
+        lineOfBusiness?: {
+            noPointer: RevenueRollupAmount;
+            note: string;
+        };
+        blindSurfaces: string[];
+        notes: string[];
+    };
+}
+/**
+ * `operations.revenueRollup` — see the module header.
+ *
+ * ```ts
+ * import { revenueRollup } from 'node-autotask/operations';
+ * const r = await revenueRollup(client, { tenantWide: true, dateFrom: '2025-07-01', dateTo: '2026-06-30' });
+ * ```
+ */
+declare function revenueRollup(client: AutotaskClient, opts: RevenueRollupOptions): Promise<RevenueRollupResult>;
+
 /** The pinned per-call item cap (total items per call, mixed resources — the issue's "500 ids" budget; over → CONFIG_ERROR pre-request, zero wire). */
 declare const FETCH_BY_IDS_MAX_ITEMS = 500;
 /** The pinned `id in` chunk size (250/chunk — the chunk query is a single page: 250 is well under the 500 vendor page max). */
@@ -430,38 +577,42 @@ declare function probeReachability(client: AutotaskClient, opts?: ProbeReachabil
  * Three sources answer that question, at three different coverages, and the
  * SDK used to leave the choice to each caller:
  *   1. `createGuidance.liveProvenPrefix` — the fields a live create actually
- *      demanded, in vendor-demand order (92 rows; the widest evidence);
- *   2. `zoneFacts.createRequiredSet` — the hand-authored zone set (6
- *      resources);
+ *      demanded, in vendor-demand order (the widest evidence);
+ *   2. `zoneFacts.createRequiredSet` — the hand-authored zone set;
  *   3. the vendor field catalog's `isRequired` — the spec opinion (wrong for
- *      68 of the 75 resources that carry a proven prefix).
+ *      most resources that carry a proven prefix).
  *
  * The order is FIXED and stated: live-proven > zone > spec, with the source
  * named on the result (`from`). Both plan shapes stay where they are; this
  * helper is the only place in the SDK that compares them.
  *
- * Value-conditioned prefixes: a prefix proven for one picklist value (e.g.
- * `contracts.create`'s type-1 `estimatedRevenue`/`estimatedHours`/
- * `estimatedCost`) is still returned whole with `from: 'live-proven'` — the
- * condition itself lives on the create-guidance row (`blocker.message` +
- * `vendorEvidence`), which a caller must read before treating the list as
- * unconditional. Never flatten a conditioned row into "all these fields are
- * always required"; the row's evidence is the qualifier.
+ * Value-conditioned fields: a field the row gates on a picklist value
+ * (`requiresByValue`, e.g. `contracts.create` needs `estimatedHours` only for
+ * `contractType` 1) is never returned as unconditionally required. It is
+ * removed from `fields`, and the gates are returned, typed, on `conditional`.
+ *
+ * `unproven` is true when no live create is known to succeed with the
+ * returned set: the plan row says the create still failed after the prefix,
+ * or the set is only the vendor spec's opinion.
  */
 
 /** Which source the returned field set came from (the precedence order). */
 type RequiredFieldsSource = 'live-proven' | 'zone' | 'spec';
 /** The effective required set + the source it came from. */
 interface EffectiveRequiredFields {
-    /** The required field names, in the source's own order (vendor-demand order for a live-proven prefix). */
+    /** The unconditionally required field names, in the source's own order (vendor-demand order for a live-proven prefix). Fields gated by a value are on `conditional`, not here. */
     fields: string[];
     /** `live-proven` (createGuidance.liveProvenPrefix) > `zone` (createRequiredSet) > `spec` (vendor isRequired). */
     from: RequiredFieldsSource;
+    /** True when no live create is known to succeed with this set (the plan row is unproven, or the set is the spec's opinion only). */
+    unproven: boolean;
+    /** The value-conditioned gates (`createGuidance.requiresByValue`); present only when the row declares some. Their fields are not in `fields`. */
+    conditional?: CreateGuidanceValueRequirement[];
 }
 /** The plan zone-fact shape this helper reads (both shapes stay plan-owned). */
 interface RequiredFieldsZoneFacts {
     createRequiredSet?: string[];
-    createGuidance?: Pick<CreateGuidanceRow, 'liveProvenPrefix' | 'unproven'> | null;
+    createGuidance?: Pick<CreateGuidanceRow, 'liveProvenPrefix' | 'unproven' | 'requiresByValue'> | null;
 }
 /** The spec-side record this helper reads (the vendor field catalog's projection). */
 interface RequiredFieldsRecord {
@@ -477,27 +628,30 @@ interface RequiredFieldsRecord {
  *   { requiredFields: vendorRequiredNames },   // from operations.fieldCatalog
  *   RELATIONSHIP_MAP.contacts.zoneFacts,       // the plan zone facts
  * );
- * // contacts: { fields: ['firstName', 'lastName', 'companyID', 'isActive'], from: 'live-proven' }
+ * // contacts: { fields: ['firstName', 'lastName', 'companyID', 'isActive'], from: 'live-proven', unproven: false }
  * ```
  *
  * An empty or absent higher source falls through to the next one; with no
- * source at all the result is `{ fields: [], from: 'spec' }` — the name of the
- * source is always stated, never a bare list.
+ * source at all the result is `{ fields: [], from: 'spec', unproven: true }` —
+ * the name of the source is always stated, never a bare list.
  */
 declare function effectiveRequiredFields(record?: RequiredFieldsRecord | null, zoneFacts?: RequiredFieldsZoneFacts | null): EffectiveRequiredFields;
 
-/** The closed blocker-kind set (the gate re-derives it; unknown kind → CONFIG_ERROR). */
 /**
- * The closed blocker-kind set served by `operations.createGuidance`.
- * Superset of issue #12's 8-value enumeration: the campaign decode produced
- * 14 rows that matched no named blocker (wall-adjacent create shapes with
- * verbatim vendor evidence) — the closed set gained `'unknown'` (9 kinds)
- * rather than forcing those rows into a misfitting class.
+ * The closed blocker-kind set served by `operations.createGuidance` (the gate
+ * re-derives it; an unknown kind is a CONFIG_ERROR on the filter).
+ *
+ * `'non-mutable'` is a create blocker: the vendor refuses the create write
+ * itself for the entity (no row carries it today). `'delete-absent'` is NOT a
+ * create blocker — a missing vendor DELETE is `deleteBoundary` — so the kind
+ * is reserved and no row carries it (the gate fails a row that does); it
+ * stays in the set so existing `kind` filters keep working. `'unknown'`
+ * covers wall-adjacent rows that match no named class.
  */
 declare const CREATE_BLOCKER_KINDS: readonly CreateBlockerKind[];
 /** One served create-guidance row: the plan row plus the effective required set (issue #219 N4). */
 interface ServedCreateGuidanceRow extends CreateGuidanceRow {
-    /** The effective create-required set + the source it came from (`live-proven` > `zone` > `spec`). Read `blocker`/`vendorEvidence` before treating a value-conditioned prefix as unconditional. */
+    /** The effective create-required set + the source it came from (`live-proven` > `zone` > `spec`). `fields` excludes value-gated fields (see `conditional`) and `unproven` says whether a live create is known to succeed with the set. */
     requiredFields: EffectiveRequiredFields;
 }
 /** The served report (the plan report with the effective required set on every row). */
@@ -682,7 +836,7 @@ interface FieldCatalogRow {
     resource: string;
     /** The vendor entity name (the path segment; plan-derived). */
     apiEntity: string;
-    /** True when the plan carries a `getUdfInfo` row for the resource (the vendor defines a UDF catalog endpoint for every entity resource — the catalog may answer an empty list). */
+    /** The plan resource's `udfCapable` flag, read from the registry record (`CapabilityRecord.udfCapable`, issue #254): true for the resources whose records carry `userDefinedFields`. Every vendor entity has a `getUdfInfo` catalog endpoint, so the `udf` include works on any row; that endpoint's presence does not make a resource UDF-capable. */
     udfCapable: boolean;
     /** The filter mechanism for a UDF name — present exactly when `udfCapable`: a filter on a UDF name is accepted only with the vendor's `udf: true` marker (a plain filter is refused), so the row states the marker rather than leaving a consumer to read the UDF rows' `isQueryable` (issue #219 N7). */
     udfFilter?: 'udf-marker';
@@ -745,7 +899,7 @@ interface FieldCatalogResult {
         resources: number;
         /** The plan's `getFieldInfo`-bearing resource count (the field-capable set). */
         fieldCapableResources: number;
-        /** The plan's `getUdfInfo`-bearing resource count (the vendor defines a UDF catalog endpoint for these; the narrower plan `udfCapable` flag — entities that actually carry UDFs — is a subset). */
+        /** The plan's `udfCapable` resource count (issue #254: the resources whose records carry `userDefinedFields` — not the wider set with a `getUdfInfo` catalog endpoint). */
         udfCapableResources: number;
         /** The rows served fully from the cache. */
         cached: number;
@@ -1067,4 +1221,4 @@ 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, ENTITY_TYPE_TO_RESOURCE, 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 FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, 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 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, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+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, ENTITY_TYPE_TO_RESOURCE, 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 FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, 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 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, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, revenueRollup, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };