@uipath/uipath-typescript 1.3.10 → 1.4.0

package/dist/maestro-processes/index.d.ts

@@ -39,6 +39,20 @@ interface GetTopFaultedCountResponse extends GetTopBaseResponse {
     /** Number of faulted instances in the given time range */
     faultedCount: number;
 }
+/**
+ * SDK response for top elements with failure.
+ * Shared by both MaestroProcesses and Cases — no service-specific enrichment.
+ */
+interface ElementGetTopFailedCountResponse {
+    /** BPMN element name (falls back to element ID if name is empty) */
+    elementName: string;
+    /** BPMN element type (e.g. ServiceTask, ReceiveTask, IntermediateCatchEvent) */
+    elementType: string;
+    /** The unique process key this element belongs to */
+    processKey: string;
+    /** Number of failed executions of this element in the given time range */
+    failedCount: number;
+}
 /**
  * Time bucketing granularity for insights time-series queries.
  *
@@ -95,6 +109,35 @@ interface GetTopDurationResponse extends GetTopBaseResponse {
     /** Total execution duration in milliseconds */
     duration: number;
 }
+/**
+ * Element count by status for a BPMN element within a process or case
+ */
+interface ElementStats {
+    /** BPMN element identifier */
+    elementId: string;
+    /** Number of successful executions */
+    successCount: number;
+    /** Number of failed executions */
+    failCount: number;
+    /** Number of terminated executions */
+    terminatedCount: number;
+    /** Number of paused executions */
+    pausedCount: number;
+    /** Number of in-progress executions */
+    inProgressCount: number;
+    /** Minimum duration in milliseconds */
+    minDurationMs: number;
+    /** Maximum duration in milliseconds */
+    maxDurationMs: number;
+    /** Average duration in milliseconds */
+    avgDurationMs: number;
+    /** 50th percentile (median) duration in milliseconds */
+    p50DurationMs: number;
+    /** 95th percentile duration in milliseconds */
+    p95DurationMs: number;
+    /** 99th percentile duration in milliseconds */
+    p99DurationMs: number;
+}
 
 /**
  * Maestro Process Types
@@ -364,6 +407,44 @@ interface MaestroProcessesServiceModel {
      * ```
      */
     getTopFaultedCount(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopFaultedCountResponse[]>;
+    /**
+     * Get the top 10 BPMN elements ranked by failure count within a time range.
+     *
+     * Returns an array of up to 10 elements sorted by how many times they failed,
+     * useful for identifying the most error-prone activities in processes.
+     *
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param options - Optional filters (packageId, processKey, version)
+     * @returns Promise resolving to an array of {@link ElementGetTopFailedCountResponse}
+     * @example
+     * ```typescript
+     * import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * const maestroProcesses = new MaestroProcesses(sdk);
+     *
+     * // Get top failing elements for the last 7 days
+     * const topFailing = await maestroProcesses.getTopElementFailedCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date()
+     * );
+     *
+     * for (const element of topFailing) {
+     *   console.log(`${element.elementName} (${element.elementType}): ${element.failedCount} failures`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top failing elements for a specific process
+     * const filtered = await maestroProcesses.getTopElementFailedCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date(),
+     *   { processKey: '<processKey>' }
+     * );
+     * ```
+     */
+    getTopElementFailedCount(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ElementGetTopFailedCountResponse[]>;
     /**
      * Get all instances status counts aggregated by date for maestro processes.
      *
@@ -443,6 +524,38 @@ interface MaestroProcessesServiceModel {
      * ```
      */
     getTopExecutionDuration(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopDurationResponse[]>;
+    /**
+     * Get element stats for process instances
+     *
+     * 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
+     * @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'
+     * );
+     *
+     * // Analyze element performance
+     * for (const element of elements) {
+     *   console.log(`Element: ${element.elementId}`);
+     *   console.log(`  Success: ${element.successCount}, Failed: ${element.failCount}`);
+     *   console.log(`  Avg duration: ${element.avgDurationMs}ms, P95: ${element.p95DurationMs}ms`);
+     * }
+     * ```
+     */
+    getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
 }
 interface ProcessMethods {
     /**
@@ -451,6 +564,15 @@ interface ProcessMethods {
      * @returns Promise resolving to array of process incidents
      */
     getIncidents(): Promise<ProcessIncidentGetResponse[]>;
+    /**
+     * Get element stats for this process
+     *
+     * @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 Promise resolving to an array of {@link ElementStats}
+     */
+    getElementStats(startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
 }
 type MaestroProcessGetAllResponse = RawMaestroProcessGetAllResponse & ProcessMethods;
 /**
@@ -593,8 +715,7 @@ interface ProcessInstanceExecutionHistoryResponse {
     startedTime: string;
     endTime: string | null;
     attributes: string | null;
-    createdTime: string;
-    updatedTime?: string;
+    updatedTime: string;
     expiredTime: string | null;
 }
 /**
@@ -741,24 +862,26 @@ interface ProcessInstancesServiceModel {
     /**
      * Get execution history (spans) for a process instance
      * @param instanceId The ID of the instance to get history for
+     * @param folderKey The folder key for authorization
      * @returns Promise resolving to execution history
      * {@link ProcessInstanceExecutionHistoryResponse}
      * @example
      * ```typescript
      * // Get execution history for a process instance
      * const history = await processInstances.getExecutionHistory(
-     *   <instanceId>
+     *   <instanceId>,
+     *   <folderKey>
      * );
      *
      * // Analyze execution timeline
      * history.forEach(span => {
      *   console.log(`Activity: ${span.name}`);
-     *   console.log(`Start: ${span.startTime}`);
-     *   console.log(`Duration: ${span.duration}ms`);
+     *   console.log(`Start: ${span.startedTime}`);
+     *   console.log(`End: ${span.endTime}`);
      * });
      * ```
      */
-    getExecutionHistory(instanceId: string): Promise<ProcessInstanceExecutionHistoryResponse[]>;
+    getExecutionHistory(instanceId: string, folderKey: string): Promise<ProcessInstanceExecutionHistoryResponse[]>;
     /**
      * Get BPMN XML file for a process instance
      * @param instanceId The ID of the instance to get BPMN for
@@ -1024,6 +1147,7 @@ interface RequestWithPaginationOptions extends RequestSpec {
             tokenParam?: string;
             countParam?: string;
             convertToSkip?: boolean;
+            zeroBased?: boolean;
         };
     };
 }
@@ -1289,6 +1413,44 @@ declare class MaestroProcessesService extends BaseService implements MaestroProc
      * ```
      */
     getTopRunCount(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopRunCountResponse[]>;
+    /**
+     * Get the top 10 BPMN elements ranked by failure count within a time range.
+     *
+     * Returns an array of up to 10 elements sorted by how many times they failed,
+     * useful for identifying the most error-prone activities in processes.
+     *
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param options - Optional filters (packageId, processKey, version)
+     * @returns Promise resolving to an array of {@link ElementGetTopFailedCountResponse}
+     * @example
+     * ```typescript
+     * import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * const maestroProcesses = new MaestroProcesses(sdk);
+     *
+     * // Get top failing elements for the last 7 days
+     * const topFailing = await maestroProcesses.getTopElementFailedCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date()
+     * );
+     *
+     * for (const element of topFailing) {
+     *   console.log(`${element.elementName} (${element.elementType}): ${element.failedCount} failures`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top failing elements for a specific process
+     * const filtered = await maestroProcesses.getTopElementFailedCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date(),
+     *   { processKey: '<processKey>' }
+     * );
+     * ```
+     */
+    getTopElementFailedCount(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ElementGetTopFailedCountResponse[]>;
     /**
      * Get all instances status counts aggregated by date for maestro processes.
      *
@@ -1406,6 +1568,38 @@ declare class MaestroProcessesService extends BaseService implements MaestroProc
      * ```
      */
     getTopExecutionDuration(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopDurationResponse[]>;
+    /**
+     * Get element stats for process instances
+     *
+     * 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
+     * @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'
+     * );
+     *
+     * // Analyze element performance
+     * for (const element of elements) {
+     *   console.log(`Element: ${element.elementId}`);
+     *   console.log(`  Success: ${element.successCount}, Failed: ${element.failCount}`);
+     *   console.log(`  Avg duration: ${element.avgDurationMs}ms, P95: ${element.p95DurationMs}ms`);
+     * }
+     * ```
+     */
+    getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
 }
 
 declare class ProcessInstancesService extends BaseService implements ProcessInstancesServiceModel {
@@ -1460,9 +1654,27 @@ declare class ProcessInstancesService extends BaseService implements ProcessInst
     /**
      * Get execution history (spans) for a process instance
      * @param instanceId The ID of the instance to get history for
-     * @returns Promise<ProcessInstanceExecutionHistoryResponse[]>
+     * @param folderKey The folder key for authorization
+     * @returns Promise resolving to execution history
+     * {@link ProcessInstanceExecutionHistoryResponse}
+     * @example
+     * ```typescript
+     * // Get execution history for a process instance
+     * const history = await processInstances.getExecutionHistory(
+     *   <instanceId>,
+     *   <folderKey>
+     * );
+     *
+     * // Analyze execution timeline
+     * history.forEach(span => {
+     *   console.log(`Activity: ${span.name}`);
+     *   console.log(`Start: ${span.startedTime}`);
+     *   console.log(`End: ${span.endTime}`);
+     * });
+     * ```
      */
-    getExecutionHistory(instanceId: string): Promise<ProcessInstanceExecutionHistoryResponse[]>;
+    getExecutionHistory(instanceId: string, folderKey: string): Promise<ProcessInstanceExecutionHistoryResponse[]>;
+    private mapSpanToHistory;
     /**
      * Get BPMN XML file for a process instance
      * @param instanceId The ID of the instance to get BPMN for
@@ -1562,4 +1774,4 @@ declare class ProcessIncidentsService extends BaseService implements ProcessInci
 }
 
 export { DebugMode, InstanceFinalStatus, MaestroProcessesService as MaestroProcesses, MaestroProcessesService, ProcessIncidentSeverity, ProcessIncidentStatus, ProcessIncidentType, ProcessIncidentsService as ProcessIncidents, ProcessIncidentsService, ProcessInstancesService as ProcessInstances, ProcessInstancesService, TimeInterval, createProcessInstanceWithMethods, createProcessWithMethods };
-export type { BpmnXmlString, ElementMetaData, GetTopBaseResponse, GetTopDurationResponse, GetTopFaultedCountResponse, GetTopRunCountResponse, GlobalVariableMetaData, InstanceStatusTimelineResponse, MaestroProcessGetAllResponse, MaestroProcessesServiceModel, ProcessGetTopDurationResponse, ProcessGetTopFaultedCountResponse, ProcessGetTopRunCountResponse, ProcessIncidentGetAllResponse, ProcessIncidentGetResponse, ProcessIncidentsServiceModel, ProcessInstanceExecutionHistoryResponse, ProcessInstanceGetAllOptions, ProcessInstanceGetAllWithPaginationOptions, ProcessInstanceGetResponse, ProcessInstanceGetVariablesOptions, ProcessInstanceGetVariablesResponse, ProcessInstanceMethods, ProcessInstanceOperationOptions, ProcessInstanceOperationResponse, ProcessInstanceRun, ProcessInstancesServiceModel, ProcessMethods, RawMaestroProcessGetAllResponse, RawProcessInstanceGetResponse, TimelineOptions, TopQueryOptions };
+export type { BpmnXmlString, ElementGetTopFailedCountResponse, ElementMetaData, ElementStats, GetTopBaseResponse, GetTopDurationResponse, GetTopFaultedCountResponse, GetTopRunCountResponse, GlobalVariableMetaData, InstanceStatusTimelineResponse, MaestroProcessGetAllResponse, MaestroProcessesServiceModel, ProcessGetTopDurationResponse, ProcessGetTopFaultedCountResponse, ProcessGetTopRunCountResponse, ProcessIncidentGetAllResponse, ProcessIncidentGetResponse, ProcessIncidentsServiceModel, ProcessInstanceExecutionHistoryResponse, ProcessInstanceGetAllOptions, ProcessInstanceGetAllWithPaginationOptions, ProcessInstanceGetResponse, ProcessInstanceGetVariablesOptions, ProcessInstanceGetVariablesResponse, ProcessInstanceMethods, ProcessInstanceOperationOptions, ProcessInstanceOperationResponse, ProcessInstanceRun, ProcessInstancesServiceModel, ProcessMethods, RawMaestroProcessGetAllResponse, RawProcessInstanceGetResponse, TimelineOptions, TopQueryOptions };