@uipath/uipath-typescript 1.4.1 → 1.5.0

package/dist/index.cjs

@@ -4652,6 +4652,8 @@ const MAESTRO_ENDPOINTS = {
         INSTANCE_STATUS_BY_DATE: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/InstanceStatusByDate`,
         /** Top processes ranked by total duration */
         TOP_PROCESSES_BY_DURATION: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/TopProcessesByDuration`,
+        /** Instance stats (counts by status + duration percentiles) */
+        INSTANCE_COUNT_BY_STATUS: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/InstanceCountByStatus`,
         /** Element count by status for agentic instances (process and case) */
         ELEMENT_COUNT_BY_STATUS: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/ElementCountByStatus`,
     },
@@ -5013,7 +5015,7 @@ class EmbeddedTokenManager {
  * SDK's public API.
  */
 /** SDK version placeholder — patched by the SDK publish workflow. */
-const SDK_VERSION = '1.4.1';
+const SDK_VERSION = '1.5.0';
 const CLOUD_ROLE_NAME = 'uipath-ts-sdk';
 const SDK_SERVICE_NAME = 'UiPath.TypeScript.Sdk';
 const SDK_LOGGER_NAME = 'uipath-ts-sdk-telemetry';
@@ -6980,7 +6982,16 @@ function toISOUtc(value) {
     return isNaN(date.getTime()) ? value : date.toISOString();
 }
 /**
- * Transforms data by mapping fields according to the provided field mapping
+ * Transforms data by renaming each key in `data` exactly once, using the
+ * mapping (`sourceField → targetField`). Keys not present in the mapping
+ * pass through unchanged. The original (pre-rename) key is dropped — the
+ * result contains only the renamed key.
+ *
+ * Each rename is independent. If the mapping happens to contain chained
+ * entries (`a → b` and `b → c`), they do NOT compose: a field named `a`
+ * in `data` becomes `b` (not `c`), because the renames are applied based
+ * on the original data's keys, not the running result.
+ *
  * @param data The source data to transform
  * @param fieldMapping Object mapping source field names to target field names
  * @returns Transformed data with mapped field names
@@ -7003,21 +7014,28 @@ function toISOUtc(value) {
  * //   { userId: '123', name: 'john' },
  * //   { userId: '456', name: 'jane' }
  * // ]
+ *
+ * // No chaining — `a → b` does not become `a → c` even if the map has `b → c`.
+ * transformData({ a: 1 }, { a: 'b', b: 'c' });
+ * // result = { b: 1 }
  * ```
  */
 function transformData(data, fieldMapping) {
+    // Pass null/undefined through unchanged — callers (e.g. AttachmentService.getById)
+    // may invoke this on optional fields that an OData `select` excluded.
+    if (data == null) {
+        return data;
+    }
     // Handle array of objects
     if (Array.isArray(data)) {
         return data.map(item => transformData(item, fieldMapping));
     }
-    // Handle single object
-    const result = { ...data };
-    for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-        if (sourceField in result) {
-            const value = result[sourceField];
-            delete result[sourceField];
-            result[targetField] = value;
-        }
+    // Walk the ORIGINAL data's keys, look up each in the mapping. One rename
+    // per data key — no mutation of an in-progress result, so chains can't form.
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const renamedKey = fieldMapping[key] ?? key;
+        result[renamedKey] = value;
     }
     return result;
 }
@@ -7295,6 +7313,79 @@ function transformRequest(data, responseMap) {
     }
     return result;
 }
+/**
+ * OData query-string keys whose values may contain field identifiers that
+ * need rewriting from SDK names → API names.
+ */
+const ODATA_FIELD_PARAM_KEYS = ['filter', 'orderby', 'select', 'expand'];
+/**
+ * Matches one token at a time in an OData expression:
+ *   1. A single-quoted string literal, allowing the `''` escape sequence —
+ *      consumed atomically so identifiers inside the literal can't match.
+ *   2. An OData identifier (`[A-Za-z_][A-Za-z0-9_]*`).
+ * Anything else (whitespace, operators, parens, commas) is left alone by
+ * `String.prototype.replace`, which only substitutes matched substrings.
+ */
+const ODATA_TOKEN_RE = /'(?:[^']|'')*'|[A-Za-z_][A-Za-z0-9_]*/g;
+/**
+ * Rewrites SDK field identifiers to API field identifiers inside an OData
+ * expression string (`$filter`, `$orderby`, `$select`, `$expand`).
+ *
+ * Field maps (e.g. `JobMap`) rename API fields → SDK fields on responses, so
+ * SDK consumers see the renamed names. Without this rewrite, the same name
+ * in a `filter` string would be forwarded verbatim and the API (which still
+ * uses the original name) would reject it.
+ *
+ * Quoted string literals (with the OData `''` escape) are preserved exactly:
+ * the token regex consumes them whole, so identifiers inside literals never
+ * match. Identifier tokens are looked up in the reversed field map.
+ *
+ * @example
+ * ```typescript
+ * const requestMap = { processName: 'releaseName' };
+ * rewriteODataIdentifiers("processName eq 'processName'", requestMap);
+ * // "releaseName eq 'processName'"  — identifier rewritten, literal preserved
+ * ```
+ */
+function rewriteODataIdentifiers(expression, requestMap) {
+    if (!expression)
+        return expression;
+    return expression.replace(ODATA_TOKEN_RE, (match) => match.startsWith("'") ? match : (requestMap[match] ?? match));
+}
+/**
+ * Symmetric counterpart of {@link transformRequest} for OData query options:
+ * rewrites SDK field identifiers inside the recognized OData string params
+ * (`filter`, `orderby`, `select`, `expand`) to their API names using the
+ * reversed form of a response field map. Returns a shallow copy with the
+ * relevant values rewritten; other keys pass through unchanged.
+ *
+ * Use at the OData edge so SDK consumers can refer to renamed fields by
+ * their SDK name throughout — for reading the response and for filtering /
+ * sorting / projecting / expanding.
+ *
+ * @param options The OData query options as authored with SDK field names
+ * @param responseMap The response field map (API → SDK); reversed internally
+ *
+ * @example
+ * ```typescript
+ * // JobMap renames releaseName → processName on responses.
+ * transformOptions({ filter: "processName eq 'X'" }, JobMap);
+ * // { filter: "releaseName eq 'X'" }
+ * ```
+ */
+function transformOptions(options, responseMap) {
+    const requestMap = reverseMap(responseMap);
+    if (Object.keys(requestMap).length === 0)
+        return options;
+    const result = { ...options };
+    for (const key of ODATA_FIELD_PARAM_KEYS) {
+        const value = result[key];
+        if (typeof value === 'string') {
+            result[key] = rewriteODataIdentifiers(value, requestMap);
+        }
+    }
+    return result;
+}
 /**
  * Transforms an array-based dictionary with separate keys and values arrays
  * into a standard JavaScript object/record
@@ -9861,6 +9952,21 @@ __decorate([
     track('Choicesets.DeleteValuesById')
 ], ChoiceSetService.prototype, "deleteValuesById", null);
 
+/**
+ * Maps API field names (countOf*) to SDK field names (*Count) for InstanceStats,
+ * aligning naming with ElementStats and other count-suffixed conventions.
+ */
+const InstanceStatsMap = {
+    countOfAllInstances: 'totalCount',
+    countOfRunning: 'runningCount',
+    countOfTransitioning: 'transitioningCount',
+    countOfPaused: 'pausedCount',
+    countOfFaulted: 'faultedCount',
+    countOfCompleted: 'completedCount',
+    countOfCancelled: 'cancelledCount',
+    countOfDeleted: 'deletedCount'
+};
+
 /**
  * Maestro Process Models
  * Model classes for Maestro processes
@@ -9886,7 +9992,26 @@ function createProcessMethods(processData, service) {
                 throw new Error('Process key is undefined');
             if (!processData.packageId)
                 throw new Error('Package ID is undefined');
-            return service.getElementStats(processData.processKey, processData.packageId, startTime, endTime, packageVersion);
+            return service.getElementStats({
+                processKey: processData.processKey,
+                packageId: processData.packageId,
+                packageVersion,
+                startTime,
+                endTime,
+            });
+        },
+        getInstanceStats(startTime, endTime, packageVersion) {
+            if (!processData.processKey)
+                throw new Error('Process key is undefined');
+            if (!processData.packageId)
+                throw new Error('Package ID is undefined');
+            return service.getInstanceStats({
+                processKey: processData.processKey,
+                packageId: processData.packageId,
+                packageVersion,
+                startTime,
+                endTime,
+            });
         }
     };
 }
@@ -9949,24 +10074,21 @@ async function fetchInstanceStatusTimeline(postFn, startTime, endTime, isCaseMan
     return response.data ?? [];
 }
 /**
- * Builds the request body for the ElementCountByStatus endpoint.
+ * Builds the commonParams request body for Insights RTM endpoints
+ * that filter by process key, package, time range, and version.
  *
- * @param processKey - Process key to filter by
- * @param packageId - Package identifier
- * @param startTime - Start of the time range to query
- * @param endTime - End of the time range to query
- * @param packageVersion - Package version to filter by
- * @returns Request body for the ElementCountByStatus endpoint
+ * @param request - Process scope + time range to aggregate over
+ * @returns Request body with commonParams
  * @internal
  */
-function buildElementCountByStatusBody(processKey, packageId, startTime, endTime, packageVersion) {
+function buildInsightsCommonBody(request) {
     return {
         commonParams: {
-            processKey,
-            packageId,
-            startTime: startTime.getTime(),
-            endTime: endTime.getTime(),
-            version: packageVersion
+            processKey: request.processKey,
+            packageId: request.packageId,
+            startTime: request.startTime.getTime(),
+            endTime: request.endTime.getTime(),
+            version: request.packageVersion
         }
     };
 }
@@ -10220,7 +10342,26 @@ function createCaseMethods(caseData, service) {
                 throw new Error('Process key is undefined');
             if (!caseData.packageId)
                 throw new Error('Package ID is undefined');
-            return service.getElementStats(caseData.processKey, caseData.packageId, startTime, endTime, packageVersion);
+            return service.getElementStats({
+                processKey: caseData.processKey,
+                packageId: caseData.packageId,
+                packageVersion,
+                startTime,
+                endTime,
+            });
+        },
+        getInstanceStats(startTime, endTime, packageVersion) {
+            if (!caseData.processKey)
+                throw new Error('Process key is undefined');
+            if (!caseData.packageId)
+                throw new Error('Package ID is undefined');
+            return service.getInstanceStats({
+                processKey: caseData.processKey,
+                packageId: caseData.packageId,
+                packageVersion,
+                startTime,
+                endTime,
+            });
         }
     };
 }
@@ -11084,22 +11225,22 @@ class MaestroProcessesService extends BaseService {
      * Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
      * duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a process.
      *
-     * @param processKey - Process key to filter by
-     * @param packageId - Package identifier
-     * @param startTime - Start of the time range to query
-     * @param endTime - End of the time range to query
-     * @param packageVersion - Package version to filter by
+     * @param request - Process scope + time range to aggregate over
      * @returns Promise resolving to an array of {@link ElementStats}
      * @example
      * ```typescript
-     * // Get element metrics for a process
-     * const elements = await maestroProcesses.getElementStats(
-     *   '<processKey>',
-     *   '<packageId>',
-     *   new Date('2026-04-01'),
-     *   new Date(),
-     *   '1.0.1'
-     * );
+     * // First, list processes to find the processKey, packageId, and available versions
+     * const processes = await maestroProcesses.getAll();
+     * const process = processes[0];
+     *
+     * // Get element metrics for that process
+     * const elements = await maestroProcesses.getElementStats({
+     *   processKey: process.processKey,
+     *   packageId: process.packageId,
+     *   packageVersion: process.packageVersions[0],
+     *   startTime: new Date('2026-04-01'),
+     *   endTime: new Date(),
+     * });
      *
      * // Analyze element performance
      * for (const element of elements) {
@@ -11107,12 +11248,58 @@ class MaestroProcessesService extends BaseService {
      *   console.log(`  Success: ${element.successCount}, Failed: ${element.failCount}`);
      *   console.log(`  Avg duration: ${element.avgDurationMs}ms, P95: ${element.p95DurationMs}ms`);
      * }
+     *
+     * // Using bound method on a process — auto-fills processKey and packageId
+     * const boundElements = await process.getElementStats(
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   process.packageVersions[0]
+     * );
      * ```
      */
-    async getElementStats(processKey, packageId, startTime, endTime, packageVersion) {
-        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.ELEMENT_COUNT_BY_STATUS, buildElementCountByStatusBody(processKey, packageId, startTime, endTime, packageVersion));
+    async getElementStats(request) {
+        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.ELEMENT_COUNT_BY_STATUS, buildInsightsCommonBody(request));
         return data ?? [];
     }
+    /**
+     * Get instance stats for a process.
+     *
+     * Returns total instance counts broken down by status (running, completed, faulted, etc.)
+     * and the average execution duration for all instances of a process within a time range.
+     *
+     * @param request - Process scope + time range to aggregate over
+     * @returns Promise resolving to {@link InstanceStats}
+     * @example
+     * ```typescript
+     * // First, list processes to find the processKey, packageId, and available versions
+     * const processes = await maestroProcesses.getAll();
+     * const process = processes[0];
+     *
+     * // Get instance status breakdown for that process
+     * const counts = await maestroProcesses.getInstanceStats({
+     *   processKey: process.processKey,
+     *   packageId: process.packageId,
+     *   packageVersion: process.packageVersions[0],
+     *   startTime: new Date('2026-04-01'),
+     *   endTime: new Date(),
+     * });
+     *
+     * console.log(`Total: ${counts.totalCount}`);
+     * console.log(`Running: ${counts.runningCount}, Completed: ${counts.completedCount}`);
+     * console.log(`Faulted: ${counts.faultedCount}, Avg duration: ${counts.avgDurationMs}ms`);
+     *
+     * // Using bound method on a process — auto-fills processKey and packageId
+     * const boundCounts = await process.getInstanceStats(
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   process.packageVersions[0]
+     * );
+     * ```
+     */
+    async getInstanceStats(request) {
+        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.INSTANCE_COUNT_BY_STATUS, buildInsightsCommonBody(request));
+        return transformData(data, InstanceStatsMap);
+    }
 }
 __decorate([
     track('MaestroProcesses.GetAll')
@@ -11138,6 +11325,9 @@ __decorate([
 __decorate([
     track('MaestroProcesses.GetElementStats')
 ], MaestroProcessesService.prototype, "getElementStats", null);
+__decorate([
+    track('MaestroProcesses.GetInstanceStats')
+], MaestroProcessesService.prototype, "getInstanceStats", null);
 
 /**
  * Service class for Maestro Process Incidents
@@ -11445,34 +11635,79 @@ class CasesService extends BaseService {
      * Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
      * duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a case.
      *
-     * @param processKey - Process key to filter by
-     * @param packageId - Package identifier
-     * @param startTime - Start of the time range to query
-     * @param endTime - End of the time range to query
-     * @param packageVersion - Package version to filter by
+     * @param request - Process scope + time range to aggregate over
      * @returns Promise resolving to an array of {@link ElementStats}
      * @example
      * ```typescript
-     * // Get element metrics for a case
-     * const elements = await cases.getElementStats(
-     *   '<processKey>',
-     *   '<packageId>',
-     *   new Date('2026-04-01'),
-     *   new Date(),
-     *   '1.0.1'
-     * );
+     * // First, list cases to find the processKey, packageId, and available versions
+     * const allCases = await cases.getAll();
+     * const caseItem = allCases[0];
+     *
+     * // Get element metrics for that case
+     * const elements = await cases.getElementStats({
+     *   processKey: caseItem.processKey,
+     *   packageId: caseItem.packageId,
+     *   packageVersion: caseItem.packageVersions[0],
+     *   startTime: new Date('2026-04-01'),
+     *   endTime: new Date(),
+     * });
      *
      * // Find elements with failures
      * const failedElements = elements.filter(e => e.failCount > 0);
      * for (const element of failedElements) {
      *   console.log(`Failed element: ${element.elementId}, failures: ${element.failCount}`);
      * }
+     *
+     * // Using bound method on a case — auto-fills processKey and packageId
+     * const boundElements = await caseItem.getElementStats(
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   caseItem.packageVersions[0]
+     * );
      * ```
      */
-    async getElementStats(processKey, packageId, startTime, endTime, packageVersion) {
-        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.ELEMENT_COUNT_BY_STATUS, buildElementCountByStatusBody(processKey, packageId, startTime, endTime, packageVersion));
+    async getElementStats(request) {
+        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.ELEMENT_COUNT_BY_STATUS, buildInsightsCommonBody(request));
         return data ?? [];
     }
+    /**
+     * Get instance stats for a case.
+     *
+     * Returns total instance counts broken down by status (running, completed, faulted, etc.)
+     * and the average execution duration for all instances of a case within a time range.
+     *
+     * @param request - Process scope + time range to aggregate over
+     * @returns Promise resolving to {@link InstanceStats}
+     * @example
+     * ```typescript
+     * // First, list cases to find the processKey, packageId, and available versions
+     * const allCases = await cases.getAll();
+     * const caseItem = allCases[0];
+     *
+     * // Get instance status breakdown for that case
+     * const counts = await cases.getInstanceStats({
+     *   processKey: caseItem.processKey,
+     *   packageId: caseItem.packageId,
+     *   packageVersion: caseItem.packageVersions[0],
+     *   startTime: new Date('2026-04-01'),
+     *   endTime: new Date(),
+     * });
+     *
+     * console.log(`Total: ${counts.totalCount}`);
+     * console.log(`Completed: ${counts.completedCount}, Faulted: ${counts.faultedCount}`);
+     *
+     * // Using bound method on a case — auto-fills processKey and packageId
+     * const boundCounts = await caseItem.getInstanceStats(
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   caseItem.packageVersions[0]
+     * );
+     * ```
+     */
+    async getInstanceStats(request) {
+        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.INSTANCE_COUNT_BY_STATUS, buildInsightsCommonBody(request));
+        return transformData(data, InstanceStatsMap);
+    }
     /**
      * Extract a readable case name from the packageId
      * @param packageId - The full package identifier
@@ -11513,6 +11748,9 @@ __decorate([
 __decorate([
     track('Cases.GetElementStats')
 ], CasesService.prototype, "getElementStats", null);
+__decorate([
+    track('Cases.GetInstanceStats')
+], CasesService.prototype, "getInstanceStats", null);
 
 /**
  * Maps fields for Case Instance entities to ensure consistent naming
@@ -13970,8 +14208,9 @@ class JobService extends FolderScopedService {
      * const folderJobs = await jobs.getAll({ folderId: <folderId> });
      *
      * // With filtering
-     * const runningJobs = await jobs.getAll({
-     *   filter: "state eq 'Running'"
+     * const recentInvoiceJobs = await jobs.getAll({
+     *   filter: "processName eq 'InvoiceBot'",
+     *   orderby: 'createdTime desc',
      * });
      *
      * // First page with pagination
@@ -13994,6 +14233,10 @@ class JobService extends FolderScopedService {
             const rawJob = transformData(pascalToCamelCaseKeys(job), JobMap);
             return createJobWithMethods(rawJob, this);
         };
+        // Rewrite renamed SDK field names → API names inside OData strings
+        // before delegating, mirroring the transformRequest pattern used for
+        // request bodies.
+        const apiOptions = options ? transformOptions(options, JobMap) : options;
         return PaginationHelpers.getAll({
             serviceAccess: this.createPaginationServiceAccess(),
             getEndpoint: () => JOB_ENDPOINTS.GET_ALL,
@@ -14009,7 +14252,7 @@ class JobService extends FolderScopedService {
                     countParam: ODATA_OFFSET_PARAMS.COUNT_PARAM,
                 },
             },
-        }, options);
+        }, apiOptions);
     }
     /**
      * Gets a job by its unique key (GUID).
@@ -14046,8 +14289,8 @@ class JobService extends FolderScopedService {
             throw new ValidationError({ message: 'folderId is required for getById' });
         }
         const headers = createHeaders({ [FOLDER_ID]: folderId });
-        const keysToPrefix = Object.keys(options ?? {});
-        const apiOptions = options ? addPrefixToKeys(options, ODATA_PREFIX, keysToPrefix) : {};
+        const apiFieldOptions = options ? transformOptions(options, JobMap) : {};
+        const apiOptions = addPrefixToKeys(apiFieldOptions, ODATA_PREFIX, Object.keys(apiFieldOptions));
         const response = await this.get(JOB_ENDPOINTS.GET_BY_KEY(id), {
             params: apiOptions,
             headers,
@@ -14350,6 +14593,9 @@ exports.JobState = void 0;
     JobState["Stopped"] = "Stopped";
     JobState["Suspended"] = "Suspended";
     JobState["Resumed"] = "Resumed";
+    JobState["Cancelled"] = "Cancelled";
+    /** Server-side fallback for an unrecognized or missing job state. */
+    JobState["Unknown"] = "Unknown";
 })(exports.JobState || (exports.JobState = {}));
 
 /**
@@ -15071,9 +15317,9 @@ exports.AgentListSortColumn = void 0;
     AgentListSortColumn["HealthScore"] = "HealthScore";
     AgentListSortColumn["LastIncident"] = "LastIncident";
     AgentListSortColumn["FolderName"] = "FolderName";
-    /** Quantity of AGU (Agent Units) consumed */
+    /** Quantity of Agent Units consumed */
     AgentListSortColumn["QuantityAGU"] = "QuantityAGU";
-    /** Quantity of PLTU (Platform Units) consumed */
+    /** Quantity of Platform Units consumed */
     AgentListSortColumn["QuantityPLTU"] = "QuantityPLTU";
     AgentListSortColumn["FolderPath"] = "FolderPath";
 })(exports.AgentListSortColumn || (exports.AgentListSortColumn = {}));
@@ -15095,6 +15341,30 @@ exports.AgentErrorSortColumn = void 0;
     AgentErrorSortColumn["LastSeenFolderName"] = "LastSeenFolderName";
     AgentErrorSortColumn["LastSeenFolderPath"] = "LastSeenFolderPath";
 })(exports.AgentErrorSortColumn || (exports.AgentErrorSortColumn = {}));
+/**
+ * Agent type, used to filter consumption results.
+ *
+ * Wire format is the string name, per the API's `StringEnumConverter` serialization.
+ */
+exports.AgentType = void 0;
+(function (AgentType) {
+    AgentType["Autonomous"] = "Autonomous";
+    AgentType["Conversational"] = "Conversational";
+    AgentType["Coded"] = "Coded";
+})(exports.AgentType || (exports.AgentType = {}));
+/**
+ * Job execution mode filter accepted by the summary endpoints.
+ *
+ * Wire format is the string name (`"Debug"` / `"Runtime"`), per the API's
+ * `StringEnumConverter` serialization.
+ */
+exports.AgentExecutionType = void 0;
+(function (AgentExecutionType) {
+    /** Test runs */
+    AgentExecutionType["Debug"] = "Debug";
+    /** Production runs */
+    AgentExecutionType["Runtime"] = "Runtime";
+})(exports.AgentExecutionType || (exports.AgentExecutionType = {}));
 
 /**
  * Types for the Agent Memory metrics service.