@uipath/uipath-typescript 1.3.7 → 1.3.9

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

@@ -1,9 +1,106 @@
 import { IUiPath } from '../core/index';
 
+/**
+ * Insights Types
+ * Shared types for Maestro insights analytics endpoints
+ */
+/**
+ * Optional filters for Insights "top" endpoint queries.
+ * All fields are optional — pass any combination to narrow results.
+ */
+interface TopQueryOptions {
+    /** Filter by package identifier */
+    packageId?: string;
+    /** Filter by process key */
+    processKey?: string;
+    /** Filter by package version */
+    version?: string;
+}
+/**
+ * Common fields returned by all Insights "top" endpoints
+ */
+interface GetTopBaseResponse {
+    /** The package identifier */
+    packageId: string;
+    /** The unique process key */
+    processKey: string;
+}
+/**
+ * Response for the top run count Insights endpoint
+ */
+interface GetTopRunCountResponse extends GetTopBaseResponse {
+    /** Number of times the process was run in the given time range */
+    runCount: number;
+}
+/**
+ * Response for the top failure count Insights endpoint
+ */
+interface GetTopFaultedCountResponse extends GetTopBaseResponse {
+    /** Number of faulted instances in the given time range */
+    faultedCount: number;
+}
+/**
+ * Time bucketing granularity for insights time-series queries.
+ *
+ * Controls how data points are grouped on the time axis.
+ */
+declare enum TimeInterval {
+    /** Group data points by hour */
+    Hour = "HOUR",
+    /** Group data points by day */
+    Day = "DAY",
+    /** Group data points by week */
+    Week = "WEEK"
+}
+/**
+ * Options for insights time-series queries.
+ */
+interface TimelineOptions {
+    /**
+     * How to group data points on the time axis.
+     * @default TimeInterval.Day
+     */
+    groupBy?: TimeInterval;
+}
+/**
+ * Final instance statuses returned by the instance status timeline endpoint.
+ *
+ * Only includes statuses where the instance has finished execution — Completed, Faulted, or Cancelled.
+ * Active statuses like Running or Paused are not included.
+ */
+declare enum InstanceFinalStatus {
+    /** Instance completed successfully */
+    Completed = "Completed",
+    /** Instance encountered an error */
+    Faulted = "Faulted",
+    /** Instance was cancelled */
+    Cancelled = "Cancelled"
+}
+/**
+ * Instance count for a process with a given status
+ * within a specific time bucket.
+ */
+interface InstanceStatusTimelineResponse {
+    /** Start of the time bucket in local timezone (e.g. `"5/8/2026 12:00:00 AM"`) */
+    startTime: string;
+    /** Instance status */
+    status: InstanceFinalStatus;
+    /** Number of instances with this status in the time bucket */
+    count: number;
+}
+/**
+ * Response for the top duration Insights endpoint
+ */
+interface GetTopDurationResponse extends GetTopBaseResponse {
+    /** Total execution duration in milliseconds */
+    duration: number;
+}
+
 /**
  * Maestro Process Types
  * Types and interfaces for Maestro process management
  */
+
 /**
  * Process information with instance statistics
  */
@@ -43,6 +140,27 @@ interface RawMaestroProcessGetAllResponse {
     /** Process instance count - canceling */
     cancelingCount: number;
 }
+/**
+ * Response for a single entry in top processes by run count
+ */
+interface ProcessGetTopRunCountResponse extends GetTopRunCountResponse {
+    /** Human-readable process name */
+    name: string;
+}
+/**
+ * Response for a single entry in top processes by failure count
+ */
+interface ProcessGetTopFaultedCountResponse extends GetTopFaultedCountResponse {
+    /** Human-readable process name */
+    name: string;
+}
+/**
+ * Response for a single entry in top processes by duration
+ */
+interface ProcessGetTopDurationResponse extends GetTopDurationResponse {
+    /** Human-readable process name */
+    name: string;
+}
 
 /**
  * Process Incident Status
@@ -170,6 +288,161 @@ interface MaestroProcessesServiceModel {
      * ```
      */
     getIncidents(processKey: string, folderKey: string): Promise<ProcessIncidentGetResponse[]>;
+    /**
+     * Get the top 5 processes ranked by run count within a time range.
+     *
+     * Returns an array of up to 5 processes sorted by how many times they were executed,
+     * useful for identifying the most active processes in a given period.
+     *
+     * @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 ProcessGetTopRunCountResponse}
+     * @example
+     * ```typescript
+     * import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * const maestroProcesses = new MaestroProcesses(sdk);
+     *
+     * // Get top processes by run count for the last 7 days
+     * const topProcesses = await maestroProcesses.getTopRunCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date()
+     * );
+     *
+     * for (const process of topProcesses) {
+     *   console.log(`${process.packageId}: ${process.runCount} runs`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top processes by run count for a specific package
+     * const filtered = await maestroProcesses.getTopRunCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date(),
+     *   { packageId: '<packageId>' }
+     * );
+     * ```
+     */
+    getTopRunCount(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopRunCountResponse[]>;
+    /**
+     * Get the top 10 processes ranked by failure count within a time range.
+     *
+     * Returns an array of up to 10 processes sorted by how many instances faulted,
+     * useful for identifying the most error-prone processes in a given period.
+     *
+     * @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 ProcessGetTopFaultedCountResponse}
+     * @example
+     * ```typescript
+     * import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * const maestroProcesses = new MaestroProcesses(sdk);
+     *
+     * // Get top processes by faulted count for the last 7 days
+     * const topFailing = await maestroProcesses.getTopFaultedCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date()
+     * );
+     *
+     * for (const process of topFailing) {
+     *   console.log(`${process.packageId}: ${process.faultedCount} failures`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top processes by faulted count for a specific package
+     * const filtered = await maestroProcesses.getTopFaultedCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date(),
+     *   { packageId: '<packageId>' }
+     * );
+     * ```
+     */
+    getTopFaultedCount(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopFaultedCountResponse[]>;
+    /**
+     * Get all instances status counts aggregated by date for maestro processes.
+     *
+     * Returns time-grouped counts of instances grouped by status (Completed, Faulted, Cancelled),
+     * useful for rendering 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 time bucketing granularity
+     * @returns Promise resolving to an array of {@link InstanceStatusTimelineResponse}
+     *
+     * @example
+     * ```typescript
+     * // Get daily instance status for the last 7 days
+     * const now = new Date();
+     * const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+     * const statuses = await maestroProcesses.getInstanceStatusTimeline(sevenDaysAgo, now);
+     *
+     * for (const entry of statuses) {
+     *   console.log(`${entry.startTime} — ${entry.status}: ${entry.count}`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * import { TimeInterval } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * // Get hourly breakdown
+     * const statuses = await maestroProcesses.getInstanceStatusTimeline(startTime, endTime, {
+     *   groupBy: TimeInterval.Hour,
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get all-time data (from Unix epoch to now)
+     * const allTime = await maestroProcesses.getInstanceStatusTimeline(new Date(0), new Date());
+     * ```
+     */
+    getInstanceStatusTimeline(startTime: Date, endTime: Date, options?: TimelineOptions): Promise<InstanceStatusTimelineResponse[]>;
+    /**
+     * Get the top 5 processes ranked by total duration within a time range.
+     *
+     * Returns an array of up to 5 processes sorted by their total execution time,
+     * useful for identifying the longest-running processes in a given period.
+     *
+     * @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 ProcessGetTopDurationResponse}
+     * @example
+     * ```typescript
+     * import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * const maestroProcesses = new MaestroProcesses(sdk);
+     *
+     * // Get top processes by duration for the last 7 days
+     * const topProcesses = await maestroProcesses.getTopExecutionDuration(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date()
+     * );
+     *
+     * for (const process of topProcesses) {
+     *   console.log(`${process.packageId}: ${process.duration}ms total`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top processes by duration for a specific package
+     * const filtered = await maestroProcesses.getTopExecutionDuration(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date(),
+     *   { packageId: '<packageId>' }
+     * );
+     * ```
+     */
+    getTopExecutionDuration(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopDurationResponse[]>;
 }
 interface ProcessMethods {
     /**
@@ -750,6 +1023,7 @@ interface RequestWithPaginationOptions extends RequestSpec {
             offsetParam?: string;
             tokenParam?: string;
             countParam?: string;
+            convertToSkip?: boolean;
         };
     };
 }
@@ -977,6 +1251,161 @@ declare class MaestroProcessesService extends BaseService implements MaestroProc
      * Get incidents for a specific process
      */
     getIncidents(processKey: string, folderKey: string): Promise<ProcessIncidentGetResponse[]>;
+    /**
+     * Get the top 5 processes ranked by run count within a time range.
+     *
+     * Returns an array of up to 5 processes sorted by how many times they were executed,
+     * useful for identifying the most active processes in a given period.
+     *
+     * @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 ProcessGetTopRunCountResponse}
+     * @example
+     * ```typescript
+     * import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * const maestroProcesses = new MaestroProcesses(sdk);
+     *
+     * // Get top processes by run count for the last 7 days
+     * const topProcesses = await maestroProcesses.getTopRunCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date()
+     * );
+     *
+     * for (const process of topProcesses) {
+     *   console.log(`${process.packageId}: ${process.runCount} runs`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top processes by run count for a specific package
+     * const filtered = await maestroProcesses.getTopRunCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date(),
+     *   { packageId: '<packageId>' }
+     * );
+     * ```
+     */
+    getTopRunCount(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopRunCountResponse[]>;
+    /**
+     * Get all instances status counts aggregated by date for maestro processes.
+     *
+     * Returns time-grouped counts of instances grouped by status (Completed, Faulted, Cancelled),
+     * useful for rendering 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 time bucketing granularity
+     * @returns Promise resolving to an array of {@link InstanceStatusTimelineResponse}
+     *
+     * @example
+     * ```typescript
+     * // Get daily instance status for the last 7 days
+     * const now = new Date();
+     * const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+     * const statuses = await maestroProcesses.getInstanceStatusTimeline(sevenDaysAgo, now);
+     *
+     * for (const entry of statuses) {
+     *   console.log(`${entry.startTime} — ${entry.status}: ${entry.count}`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * import { TimeInterval } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * // Get hourly breakdown
+     * const statuses = await maestroProcesses.getInstanceStatusTimeline(startTime, endTime, {
+     *   groupBy: TimeInterval.Hour,
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get all-time data (from Unix epoch to now)
+     * const allTime = await maestroProcesses.getInstanceStatusTimeline(new Date(0), new Date());
+     * ```
+     */
+    getInstanceStatusTimeline(startTime: Date, endTime: Date, options?: TimelineOptions): Promise<InstanceStatusTimelineResponse[]>;
+    /**
+     * Get the top 10 processes ranked by failure count within a time range.
+     *
+     * Returns an array of up to 10 processes sorted by how many instances faulted,
+     * useful for identifying the most error-prone processes in a given period.
+     *
+     * @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 ProcessGetTopFaultedCountResponse}
+     * @example
+     * ```typescript
+     * import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * const maestroProcesses = new MaestroProcesses(sdk);
+     *
+     * // Get top processes by faulted count for the last 7 days
+     * const topFailing = await maestroProcesses.getTopFaultedCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date()
+     * );
+     *
+     * for (const process of topFailing) {
+     *   console.log(`${process.packageId}: ${process.faultedCount} failures`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top processes by faulted count for a specific package
+     * const filtered = await maestroProcesses.getTopFaultedCount(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date(),
+     *   { packageId: '<packageId>' }
+     * );
+     * ```
+     */
+    getTopFaultedCount(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopFaultedCountResponse[]>;
+    /**
+     * Get the top 5 processes ranked by total duration within a time range.
+     *
+     * Returns an array of up to 5 processes sorted by their total execution time,
+     * useful for identifying the longest-running processes in a given period.
+     *
+     * @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 ProcessGetTopDurationResponse}
+     * @example
+     * ```typescript
+     * import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+     *
+     * const maestroProcesses = new MaestroProcesses(sdk);
+     *
+     * // Get top processes by duration for the last 7 days
+     * const topProcesses = await maestroProcesses.getTopExecutionDuration(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date()
+     * );
+     *
+     * for (const process of topProcesses) {
+     *   console.log(`${process.packageId}: ${process.duration}ms total`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get top processes by duration for a specific package
+     * const filtered = await maestroProcesses.getTopExecutionDuration(
+     *   new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+     *   new Date(),
+     *   { packageId: '<packageId>' }
+     * );
+     * ```
+     */
+    getTopExecutionDuration(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopDurationResponse[]>;
 }
 
 declare class ProcessInstancesService extends BaseService implements ProcessInstancesServiceModel {
@@ -1132,5 +1561,5 @@ declare class ProcessIncidentsService extends BaseService implements ProcessInci
     getAll(): Promise<ProcessIncidentGetAllResponse[]>;
 }
 
-export { DebugMode, MaestroProcessesService as MaestroProcesses, MaestroProcessesService, ProcessIncidentSeverity, ProcessIncidentStatus, ProcessIncidentType, ProcessIncidentsService as ProcessIncidents, ProcessIncidentsService, ProcessInstancesService as ProcessInstances, ProcessInstancesService, createProcessInstanceWithMethods, createProcessWithMethods };
-export type { BpmnXmlString, ElementMetaData, GlobalVariableMetaData, MaestroProcessGetAllResponse, MaestroProcessesServiceModel, ProcessIncidentGetAllResponse, ProcessIncidentGetResponse, ProcessIncidentsServiceModel, ProcessInstanceExecutionHistoryResponse, ProcessInstanceGetAllOptions, ProcessInstanceGetAllWithPaginationOptions, ProcessInstanceGetResponse, ProcessInstanceGetVariablesOptions, ProcessInstanceGetVariablesResponse, ProcessInstanceMethods, ProcessInstanceOperationOptions, ProcessInstanceOperationResponse, ProcessInstanceRun, ProcessInstancesServiceModel, ProcessMethods, RawMaestroProcessGetAllResponse, RawProcessInstanceGetResponse };
+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 };