@uipath/uipath-typescript 1.4.2 → 1.5.1

package/dist/cases/index.d.ts

@@ -75,6 +75,12 @@ interface TimelineOptions {
      * @default TimeInterval.Day
      */
     groupBy?: TimeInterval;
+    /** Filter by package identifier */
+    packageId?: string;
+    /** Filter by package version */
+    version?: string;
+    /** Filter by one or more process keys. Pass `['<processKey>']` for a single process. */
+    processKeys?: string[];
 }
 /**
  * Final instance statuses returned by the instance status timeline endpoint.
@@ -102,6 +108,17 @@ interface InstanceStatusTimelineResponse {
     /** Number of instances with this status in the time bucket */
     count: number;
 }
+/**
+ * Incident count within a specific time bucket.
+ */
+interface IncidentTimelineResponse {
+    /** Start of the time bucket in local timezone (ISO 8601, e.g. `"2026-05-04T00:00:00"`) */
+    startTime: string;
+    /** End of the time bucket in local timezone (ISO 8601, e.g. `"2026-05-11T00:00:00"`) */
+    endTime: string;
+    /** Number of incidents that occurred within this time bucket */
+    count: number;
+}
 /**
  * Response for the top duration Insights endpoint
  */
@@ -110,21 +127,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 +146,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
@@ -460,7 +527,7 @@ interface CasesServiceModel {
      *
      * @param startTime - Start of the time range to query
      * @param endTime - End of the time range to query
-     * @param options - Optional settings for time bucketing granularity
+     * @param options - Optional settings for filtering and time bucket granularity
      * @returns Promise resolving to an array of {@link InstanceStatusTimelineResponse}
      *
      * @example
@@ -487,11 +554,62 @@ interface CasesServiceModel {
      *
      * @example
      * ```typescript
+     * // Filter to a specific case process
+     * const filtered = await cases.getInstanceStatusTimeline(startTime, endTime, {
+     *   processKeys: ['<processKey>'],
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
      * // Get all-time data (from Unix epoch to now)
      * const allTime = await cases.getInstanceStatusTimeline(new Date(0), new Date());
      * ```
      */
     getInstanceStatusTimeline(startTime: Date, endTime: Date, options?: TimelineOptions): Promise<InstanceStatusTimelineResponse[]>;
+    /**
+     * Get incident counts aggregated by time bucket for case management processes.
+     *
+     * Returns time-grouped counts of incidents that occurred within each bucket,
+     * useful for rendering incident time-series charts. Use `groupBy` to control
+     * the time bucket size (hour, day, or week) — defaults to day if not provided.
+     *
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param options - Optional settings for filtering and time bucket granularity
+     * @returns Promise resolving to an array of {@link IncidentTimelineResponse}
+     *
+     * @example
+     * ```typescript
+     * // Get daily incident counts for the last 7 days
+     * const now = new Date();
+     * const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+     * const incidents = await cases.getIncidentsTimeline(sevenDaysAgo, now);
+     *
+     * for (const incident of incidents) {
+     *   console.log(`${incident.startTime} → ${incident.endTime}: ${incident.count} incidents`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * import { TimeInterval } from '@uipath/uipath-typescript/cases';
+     *
+     * // Get weekly breakdown
+     * const incidents = await cases.getIncidentsTimeline(startTime, endTime, {
+     *   groupBy: TimeInterval.Week,
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter to a specific case process
+     * const filtered = await cases.getIncidentsTimeline(startTime, endTime, {
+     *   processKeys: ['<processKey>'],
+     * });
+     * ```
+     */
+    getIncidentsTimeline(startTime: Date, endTime: Date, options?: TimelineOptions): Promise<IncidentTimelineResponse[]>;
     /**
      * Get the top 5 case processes ranked by total duration within a time range.
      *
@@ -536,31 +654,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 +732,33 @@ 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>;
+    /**
+     * Get instance status counts aggregated by date for this case process.
+     *
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param options - Optional settings for filtering and time bucket granularity (processKey is auto-captured from this case)
+     * @returns Promise resolving to an array of {@link InstanceStatusTimelineResponse}
+     */
+    getInstanceStatusTimeline(startTime: Date, endTime: Date, options?: Omit<TimelineOptions, 'processKeys'>): Promise<InstanceStatusTimelineResponse[]>;
+    /**
+     * Get incident counts aggregated by time bucket for this case process.
+     *
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param options - Optional settings for filtering and time bucket granularity (processKey is auto-captured from this case)
+     * @returns Promise resolving to an array of {@link IncidentTimelineResponse}
+     */
+    getIncidentsTimeline(startTime: Date, endTime: Date, options?: Omit<TimelineOptions, 'processKeys'>): Promise<IncidentTimelineResponse[]>;
 }
 type CaseGetAllWithMethodsResponse = CaseGetAllResponse & CaseMethods;
 /**
@@ -1965,7 +2152,7 @@ declare class CasesService extends BaseService implements CasesServiceModel {
      *
      * @param startTime - Start of the time range to query
      * @param endTime - End of the time range to query
-     * @param options - Optional settings for time bucketing granularity
+     * @param options - Optional settings for filtering and time bucket granularity
      * @returns Promise resolving to an array of {@link InstanceStatusTimelineResponse}
      *
      * @example
@@ -1992,11 +2179,62 @@ declare class CasesService extends BaseService implements CasesServiceModel {
      *
      * @example
      * ```typescript
+     * // Filter to a specific case process
+     * const filtered = await cases.getInstanceStatusTimeline(startTime, endTime, {
+     *   processKeys: ['<processKey>'],
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
      * // Get all-time data (from Unix epoch to now)
      * const allTime = await cases.getInstanceStatusTimeline(new Date(0), new Date());
      * ```
      */
     getInstanceStatusTimeline(startTime: Date, endTime: Date, options?: TimelineOptions): Promise<InstanceStatusTimelineResponse[]>;
+    /**
+     * Get incident counts aggregated by time bucket for case management processes.
+     *
+     * Returns time-grouped counts of incidents that occurred within each bucket,
+     * useful for rendering incident time-series charts. Use `groupBy` to control
+     * the time bucket size (hour, day, or week) — defaults to day if not provided.
+     *
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param options - Optional settings for filtering and time bucket granularity
+     * @returns Promise resolving to an array of {@link IncidentTimelineResponse}
+     *
+     * @example
+     * ```typescript
+     * // Get daily incident counts for the last 7 days
+     * const now = new Date();
+     * const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+     * const incidents = await cases.getIncidentsTimeline(sevenDaysAgo, now);
+     *
+     * for (const incident of incidents) {
+     *   console.log(`${incident.startTime} → ${incident.endTime}: ${incident.count} incidents`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * import { TimeInterval } from '@uipath/uipath-typescript/cases';
+     *
+     * // Get weekly breakdown
+     * const incidents = await cases.getIncidentsTimeline(startTime, endTime, {
+     *   groupBy: TimeInterval.Week,
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter to a specific case process
+     * const filtered = await cases.getIncidentsTimeline(startTime, endTime, {
+     *   processKeys: ['<processKey>'],
+     * });
+     * ```
+     */
+    getIncidentsTimeline(startTime: Date, endTime: Date, options?: TimelineOptions): Promise<IncidentTimelineResponse[]>;
     /**
      * Get the top 10 case processes ranked by failure count within a time range.
      *
@@ -2079,31 +2317,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 +2642,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, IncidentTimelineResponse, InstanceStats, InstanceStatusTimelineResponse, MaestroProcessStatsRequest, RawCaseInstanceGetResponse, SlaSummaryResponse, StageSLA, StageTask, TimelineOptions, TopQueryOptions };