@uipath/uipath-typescript 1.4.1 → 1.5.0

package/dist/cases/index.d.ts

@@ -110,21 +110,12 @@ interface GetTopDurationResponse extends GetTopBaseResponse {
     duration: number;
 }
 /**
- * Element count by status for a BPMN element within a process or case
+ * Duration percentile stats shared by Insights aggregate endpoints (per-element and per-process/case).
+ *
+ * For instance-level stats, durations are computed over terminal instances only
+ * (Completed, Cancelled, Deleted) and default to `0` when no terminal instances exist.
  */
-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;
+interface DurationStats {
     /** Minimum duration in milliseconds */
     minDurationMs: number;
     /** Maximum duration in milliseconds */
@@ -138,6 +129,65 @@ interface ElementStats {
     /** 99th percentile duration in milliseconds */
     p99DurationMs: number;
 }
+/**
+ * Instance count and duration stats aggregated by status for a process or case within a time range.
+ *
+ * Duration fields are computed over terminal instances only (Completed, Cancelled, Deleted)
+ * and default to `0` when no terminal instances exist in the time range.
+ */
+interface InstanceStats extends DurationStats {
+    /** Total number of instances across all statuses */
+    totalCount: number;
+    /** Number of currently running instances */
+    runningCount: number;
+    /** Number of instances in transitioning state */
+    transitioningCount: number;
+    /** Number of paused instances */
+    pausedCount: number;
+    /** Number of faulted instances */
+    faultedCount: number;
+    /** Number of completed instances */
+    completedCount: number;
+    /** Number of cancelled instances */
+    cancelledCount: number;
+    /** Number of deleted instances */
+    deletedCount: number;
+}
+/**
+ * Required request parameters for process-scoped insights stats endpoints
+ * (`getElementStats`, `getInstanceStats`).
+ *
+ * Identifies a single process+package+version and the time range to aggregate over.
+ */
+interface MaestroProcessStatsRequest {
+    /** Process key to filter by */
+    processKey: string;
+    /** Package identifier */
+    packageId: string;
+    /** Package version to filter by */
+    packageVersion: string;
+    /** Start of the time range to query */
+    startTime: Date;
+    /** End of the time range to query */
+    endTime: Date;
+}
+/**
+ * Per-element execution counts and duration percentiles for a BPMN element within a process or case.
+ */
+interface ElementStats extends DurationStats {
+    /** 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;
+}
 
 /**
  * Simplified universal pagination cursor
@@ -536,31 +586,73 @@ interface CasesServiceModel {
      * 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]
+     * );
+     * ```
+     */
+    getElementStats(request: MaestroProcessStatsRequest): Promise<ElementStats[]>;
+    /**
+     * 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]
+     * );
      * ```
      */
-    getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
+    getInstanceStats(request: MaestroProcessStatsRequest): Promise<InstanceStats>;
 }
 interface CaseMethods {
     /**
@@ -572,6 +664,15 @@ interface CaseMethods {
      * @returns Promise resolving to an array of {@link ElementStats}
      */
     getElementStats(startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
+    /**
+     * Get instance stats for this case
+     *
+     * @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 {@link InstanceStats}
+     */
+    getInstanceStats(startTime: Date, endTime: Date, packageVersion: string): Promise<InstanceStats>;
 }
 type CaseGetAllWithMethodsResponse = CaseGetAllResponse & CaseMethods;
 /**
@@ -2079,31 +2180,73 @@ declare class CasesService extends BaseService implements CasesServiceModel {
      * 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]
+     * );
+     * ```
+     */
+    getElementStats(request: MaestroProcessStatsRequest): Promise<ElementStats[]>;
+    /**
+     * 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]
+     * );
      * ```
      */
-    getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
+    getInstanceStats(request: MaestroProcessStatsRequest): Promise<InstanceStats>;
     /**
      * Extract a readable case name from the packageId
      * @param packageId - The full package identifier
@@ -2362,4 +2505,4 @@ declare class CaseInstancesService extends BaseService implements CaseInstancesS
 }
 
 export { CaseInstancesService as CaseInstances, CaseInstancesService, CasesService as Cases, CasesService, EscalationActionType, EscalationRecipientScope, EscalationTriggerType, InstanceFinalStatus, InstanceStatus, SLADurationUnit, SlaSummaryStatus, StageTaskType, TimeInterval, createCaseInstanceWithMethods, createCaseWithMethods };
-export type { CaseAppConfig, CaseAppOverview, CaseGetAllResponse, CaseGetAllWithMethodsResponse, CaseGetStageResponse, CaseGetTopDurationResponse, CaseGetTopFaultedCountResponse, CaseGetTopRunCountResponse, CaseInstanceExecutionHistoryResponse, CaseInstanceGetAllOptions, CaseInstanceGetAllWithPaginationOptions, CaseInstanceGetResponse, CaseInstanceMethods, CaseInstanceOperationOptions, CaseInstanceOperationResponse, CaseInstanceReopenOptions, CaseInstanceRun, CaseInstanceSlaSummaryOptions, CaseInstanceStageSLAOptions, CaseInstanceStageSLAResponse, CaseInstanceStageSLAStage, CaseInstancesServiceModel, CaseMethods, CasesServiceModel, ElementExecutionMetadata, ElementGetTopFailedCountResponse, ElementRunMetadata, ElementStats, EscalationAction, EscalationRecipient, EscalationRule, EscalationTriggerMetadata, GetTopBaseResponse, GetTopDurationResponse, GetTopFaultedCountResponse, GetTopRunCountResponse, InstanceStatusTimelineResponse, RawCaseInstanceGetResponse, SlaSummaryResponse, StageSLA, StageTask, TimelineOptions, TopQueryOptions };
+export type { CaseAppConfig, CaseAppOverview, CaseGetAllResponse, CaseGetAllWithMethodsResponse, CaseGetStageResponse, CaseGetTopDurationResponse, CaseGetTopFaultedCountResponse, CaseGetTopRunCountResponse, CaseInstanceExecutionHistoryResponse, CaseInstanceGetAllOptions, CaseInstanceGetAllWithPaginationOptions, CaseInstanceGetResponse, CaseInstanceMethods, CaseInstanceOperationOptions, CaseInstanceOperationResponse, CaseInstanceReopenOptions, CaseInstanceRun, CaseInstanceSlaSummaryOptions, CaseInstanceStageSLAOptions, CaseInstanceStageSLAResponse, CaseInstanceStageSLAStage, CaseInstancesServiceModel, CaseMethods, CasesServiceModel, DurationStats, ElementExecutionMetadata, ElementGetTopFailedCountResponse, ElementRunMetadata, ElementStats, EscalationAction, EscalationRecipient, EscalationRule, EscalationTriggerMetadata, GetTopBaseResponse, GetTopDurationResponse, GetTopFaultedCountResponse, GetTopRunCountResponse, InstanceStats, InstanceStatusTimelineResponse, MaestroProcessStatsRequest, RawCaseInstanceGetResponse, SlaSummaryResponse, StageSLA, StageTask, TimelineOptions, TopQueryOptions };