@uipath/uipath-typescript 1.4.0 → 1.4.2

package/dist/agents/index.d.ts

@@ -378,14 +378,153 @@ interface AgentListItem {
     quantityPLTU: number;
 }
 /**
- * Options for {@link AgentServiceModel.getAll}.
+ * Options for getting the list of agents.
  *
  * Composes filter, pagination, and sort options.
  */
-type AgentListOptions = AgentFilterOptions & PaginationOptions & {
+type AgentGetAllOptions = AgentFilterOptions & PaginationOptions & {
     /** Sort order for the result set. */
     orderBy?: AgentListOrderBy;
 };
+/**
+ * Summary information about a single job execution — included on every
+ * error entry to anchor the window.
+ */
+interface AgentJobInfo {
+    /** Job key */
+    jobKey: string;
+    /** Folder key the job ran in */
+    folderKey: string;
+    /** Display name of the folder */
+    folderName: string;
+    /** Fully qualified folder path */
+    folderPath: string;
+    /** Job start time */
+    startTime: string;
+    /** Job end time. `null` while the job is still running. */
+    endTime: string | null;
+    /** Process key the job was launched from. `null` for ad-hoc jobs. */
+    processKey: string | null;
+}
+/**
+ * Columns available for ordering / grouping the agent errors list.
+ */
+declare enum AgentErrorSortColumn {
+    AgentId = "AgentId",
+    AgentName = "AgentName",
+    ParentProcessName = "ParentProcessName",
+    ErrorTitle = "ErrorTitle",
+    FirstSeenStartTime = "FirstSeenStartTime",
+    ExecutionCount = "ExecutionCount",
+    Type = "Type",
+    FirstSeenFolderName = "FirstSeenFolderName",
+    FirstSeenFolderPath = "FirstSeenFolderPath",
+    LastSeenStartTime = "LastSeenStartTime",
+    LastSeenFolderName = "LastSeenFolderName",
+    LastSeenFolderPath = "LastSeenFolderPath"
+}
+/**
+ * Ordering directive for the agent errors list.
+ */
+interface AgentErrorOrderBy {
+    /** Column to sort by */
+    column: AgentErrorSortColumn;
+    /** Sort descending. Defaults to false (ascending) server-side. */
+    desc?: boolean;
+}
+/**
+ * One error in the agent errors list — an error/error-class observed
+ * for an agent over the requested window.
+ */
+interface AgentError {
+    /** Error type */
+    type: string;
+    /** Error description */
+    description: string;
+    /** Agent ID */
+    agentId: string;
+    /** Agent display name. `null` if the agent has no display name set. */
+    agentName: string | null;
+    /** Job key where the error was first seen */
+    jobKey: string;
+    /** Parent process name. `null` for jobs not bound to a parent process. */
+    parentProcess: string | null;
+    /** First-seen timestamp */
+    firstSeen: string;
+    /** Folder key where the error was first observed */
+    folderKey: string;
+    /** Folder display name */
+    folderName: string;
+    /** Fully qualified folder path */
+    folderPath: string;
+    /** Number of error executions counted for this error */
+    count: number;
+    /** First job in the window where this error was observed */
+    firstSeenJob: AgentJobInfo;
+    /** Last job in the window where this error was observed */
+    lastSeenJob: AgentJobInfo;
+}
+/**
+ * Options for the agent errors list.
+ *
+ * Composes filter, pagination, and sort/group options.
+ */
+type AgentGetErrorsOptions = AgentFilterOptions & PaginationOptions & {
+    /** Sort order for the result set. */
+    orderBy?: AgentErrorOrderBy;
+    /** Group results by one or more columns. */
+    groupBy?: AgentErrorSortColumn[];
+};
+/**
+ * A single point on the agent errors timeline
+ */
+interface AgentGetErrorsTimelineResponse {
+    /** Agent name */
+    name: string;
+    /** Error count in this time bucket */
+    value: number;
+    /** Bucket timestamp (ISO 8601, UTC) */
+    date: string;
+}
+/**
+ * Options for getting the agent errors timeline.
+ */
+interface AgentGetErrorsTimelineOptions extends AgentFilterOptions {
+    /** Max number of agents to return. Defaults to 10 server-side. */
+    limit?: number;
+}
+/**
+ * A single point on the agent consumption timeline
+ */
+interface AgentGetConsumptionTimelineResponse {
+    /** Bucket timestamp (ISO 8601, UTC) */
+    timeSlice: string;
+    /** AGU quantity consumed in this time bucket */
+    aguConsumption: number;
+}
+/**
+ * Options for getting the agent consumption timeline.
+ */
+interface AgentGetConsumptionTimelineOptions extends AgentFilterOptions {
+}
+/**
+ * A single point on the agent latency timeline
+ */
+interface AgentGetLatencyTimelineResponse {
+    /**
+     * Percentile label for this point — observed values: `"P50"`, `"P95"`.
+     */
+    name: string;
+    /** Latency value in milliseconds. */
+    value: number;
+    /** Bucket timestamp (ISO 8601, UTC) */
+    date: string;
+}
+/**
+ * Options for getting the agent latency timeline.
+ */
+interface AgentGetLatencyTimelineOptions extends AgentFilterOptions {
+}
 
 /**
  * Service for retrieving runtime data for UiPath Agents.
@@ -441,7 +580,164 @@ interface AgentServiceModel {
      * }
      * ```
      */
-    getAll<T extends AgentListOptions = AgentListOptions>(startTime: Date, endTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentListItem> : NonPaginatedResponse<AgentListItem>>;
+    getAll<T extends AgentGetAllOptions = AgentGetAllOptions>(startTime: Date, endTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentListItem> : NonPaginatedResponse<AgentListItem>>;
+    /**
+     * Retrieves agent errors (error-classes observed for agents) over the
+     * requested window.
+     *
+     * Returns a {@link PaginatedResponse} when pagination options (`pageSize`,
+     * `cursor`, or `jumpToPage`) are provided, otherwise a
+     * {@link NonPaginatedResponse}.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param endTime - Exclusive upper bound for the query window
+     * @param options - Optional pagination, sort/group, and filters
+     * @returns Promise resolving to a paginated or non-paginated list of {@link AgentError}
+     * @example
+     * ```typescript
+     * import { Agents, AgentErrorSortColumn } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // Non-paginated — errors in the window
+     * const result = await agents.getErrors(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2026-05-14T00:00:00Z'),
+     * );
+     * result.items.forEach((error) => {
+     *   console.log(`${error.type}: ${error.description} (count=${error.count})`);
+     * });
+     *
+     * // Paginated — sorted by execution count descending
+     * const page = await agents.getErrors(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2026-05-14T00:00:00Z'),
+     *   {
+     *     pageSize: 25,
+     *     orderBy: { column: AgentErrorSortColumn.ExecutionCount, desc: true },
+     *   },
+     * );
+     *
+     * if (page.hasNextPage && page.nextCursor) {
+     *   const next = await agents.getErrors(
+     *     new Date('2025-05-01T00:00:00Z'),
+     *     new Date('2026-05-14T00:00:00Z'),
+     *     { cursor: page.nextCursor },
+     *   );
+     * }
+     * ```
+     */
+    getErrors<T extends AgentGetErrorsOptions = AgentGetErrorsOptions>(startTime: Date, endTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentError> : NonPaginatedResponse<AgentError>>;
+    /**
+     * Retrieves a time-series of error counts grouped by agent over the requested window.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param endTime - Exclusive upper bound for the query window
+     * @param options - Optional filters
+     * @returns Promise resolving to an array of {@link AgentGetErrorsTimelineResponse}
+     * @example
+     * ```typescript
+     * import { Agents } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // All errors in May 2025
+     * const result = await agents.getErrorsTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     * );
+     * result.forEach((point) => {
+     *   console.log(`${point.date} ${point.name}: ${point.value} errors`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Scope to specific folders and top 5 agents
+     * const result = await agents.getErrorsTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     *   {
+     *     folderKeys: ['<folderKey1>'],
+     *     agentNames: ['JokeAgent', 'StoryAgent'],
+     *     limit: 5,
+     *   },
+     * );
+     * ```
+     */
+    getErrorsTimeline(startTime: Date, endTime: Date, options?: AgentGetErrorsTimelineOptions): Promise<AgentGetErrorsTimelineResponse[]>;
+    /**
+     * Retrieves a time-series of AGU (Agent Units) consumption over the requested window.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param endTime - Exclusive upper bound for the query window
+     * @param options - Optional filters
+     * @returns Promise resolving to an array of {@link AgentGetConsumptionTimelineResponse}
+     * @example
+     * ```typescript
+     * import { Agents } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // AGU consumption timeline in May 2025
+     * const result = await agents.getConsumptionTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     * );
+     * result.forEach((point) => {
+     *   console.log(`${point.timeSlice}: ${point.aguConsumption} AGU`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Scope to specific folders and agents
+     * const result = await agents.getConsumptionTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     *   {
+     *     folderKeys: ['<folderKey1>'],
+     *     agentNames: ['JokeAgent'],
+     *   },
+     * );
+     * ```
+     */
+    getConsumptionTimeline(startTime: Date, endTime: Date, options?: AgentGetConsumptionTimelineOptions): Promise<AgentGetConsumptionTimelineResponse[]>;
+    /**
+     * Retrieves a time-series of agent latency (milliseconds) over the requested
+     * window.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param endTime - Exclusive upper bound for the query window
+     * @param options - Optional filters
+     * @returns Promise resolving to an array of {@link AgentGetLatencyTimelineResponse}
+     * @example
+     * ```typescript
+     * import { Agents } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // Latency timeline in May 2025
+     * const result = await agents.getLatencyTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     * );
+     * result.forEach((point) => {
+     *   console.log(`${point.date} ${point.name}: ${point.value} ms`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Scope to specific folders and a single agent
+     * const result = await agents.getLatencyTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     *   {
+     *     folderKeys: ['<folderKey1>'],
+     *     agentId: '<agentId>',
+     *   },
+     * );
+     * ```
+     */
+    getLatencyTimeline(startTime: Date, endTime: Date, options?: AgentGetLatencyTimelineOptions): Promise<AgentGetLatencyTimelineResponse[]>;
 }
 
 /**
@@ -495,8 +791,171 @@ declare class AgentService extends BaseService implements AgentServiceModel {
      * }
      * ```
      */
-    getAll<T extends AgentListOptions = AgentListOptions>(startTime: Date, endTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentListItem> : NonPaginatedResponse<AgentListItem>>;
+    getAll<T extends AgentGetAllOptions = AgentGetAllOptions>(startTime: Date, endTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentListItem> : NonPaginatedResponse<AgentListItem>>;
+    /**
+     * Retrieves agent errors (error-classes observed for agents) over the
+     * requested window.
+     *
+     * Returns a {@link PaginatedResponse} when pagination options (`pageSize`,
+     * `cursor`, or `jumpToPage`) are provided, otherwise a
+     * {@link NonPaginatedResponse}.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param endTime - Exclusive upper bound for the query window
+     * @param options - Optional pagination, sort/group, and filters
+     * @returns Promise resolving to a paginated or non-paginated list of {@link AgentError}
+     * @example
+     * ```typescript
+     * import { Agents, AgentErrorSortColumn } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // Non-paginated — errors in the window
+     * const result = await agents.getErrors(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2026-05-14T00:00:00Z'),
+     * );
+     * result.items.forEach((error) => {
+     *   console.log(`${error.type}: ${error.description} (count=${error.count})`);
+     * });
+     *
+     * // Paginated — sorted by execution count descending
+     * const page = await agents.getErrors(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2026-05-14T00:00:00Z'),
+     *   {
+     *     pageSize: 25,
+     *     orderBy: { column: AgentErrorSortColumn.ExecutionCount, desc: true },
+     *   },
+     * );
+     *
+     * if (page.hasNextPage && page.nextCursor) {
+     *   const next = await agents.getErrors(
+     *     new Date('2025-05-01T00:00:00Z'),
+     *     new Date('2026-05-14T00:00:00Z'),
+     *     { cursor: page.nextCursor },
+     *   );
+     * }
+     * ```
+     */
+    getErrors<T extends AgentGetErrorsOptions = AgentGetErrorsOptions>(startTime: Date, endTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentError> : NonPaginatedResponse<AgentError>>;
+    /**
+     * Retrieves a time-series of error counts grouped by agent over the requested window.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param endTime - Exclusive upper bound for the query window
+     * @param options - Optional filters
+     * @returns Promise resolving to an array of {@link AgentGetErrorsTimelineResponse}
+     * @example
+     * ```typescript
+     * import { Agents } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // All errors in May 2025
+     * const result = await agents.getErrorsTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     * );
+     * result.forEach((point) => {
+     *   console.log(`${point.date} ${point.name}: ${point.value} errors`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Scope to specific folders and top 5 agents
+     * const result = await agents.getErrorsTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     *   {
+     *     folderKeys: ['<folderKey1>'],
+     *     agentNames: ['JokeAgent', 'StoryAgent'],
+     *     limit: 5,
+     *   },
+     * );
+     * ```
+     */
+    getErrorsTimeline(startTime: Date, endTime: Date, options?: AgentGetErrorsTimelineOptions): Promise<AgentGetErrorsTimelineResponse[]>;
+    /**
+     * Retrieves a time-series of AGU (Agent Units) consumption over the requested window.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param endTime - Exclusive upper bound for the query window
+     * @param options - Optional filters
+     * @returns Promise resolving to an array of {@link AgentGetConsumptionTimelineResponse}
+     * @example
+     * ```typescript
+     * import { Agents } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // AGU consumption timeline in May 2025
+     * const result = await agents.getConsumptionTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     * );
+     * result.forEach((point) => {
+     *   console.log(`${point.timeSlice}: ${point.aguConsumption} AGU`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Scope to specific folders and agents
+     * const result = await agents.getConsumptionTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     *   {
+     *     folderKeys: ['<folderKey1>'],
+     *     agentNames: ['JokeAgent'],
+     *   },
+     * );
+     * ```
+     */
+    getConsumptionTimeline(startTime: Date, endTime: Date, options?: AgentGetConsumptionTimelineOptions): Promise<AgentGetConsumptionTimelineResponse[]>;
+    /**
+     * Retrieves a time-series of agent latency (milliseconds) over the requested
+     * window.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param endTime - Exclusive upper bound for the query window
+     * @param options - Optional filters
+     * @returns Promise resolving to an array of {@link AgentGetLatencyTimelineResponse}
+     * @example
+     * ```typescript
+     * import { Agents } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // Latency timeline in May 2025
+     * const result = await agents.getLatencyTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     * );
+     * result.forEach((point) => {
+     *   console.log(`${point.date} ${point.name}: ${point.value} ms`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Scope to specific folders and a single agent
+     * const result = await agents.getLatencyTimeline(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2025-06-01T00:00:00Z'),
+     *   {
+     *     folderKeys: ['<folderKey1>'],
+     *     agentId: '<agentId>',
+     *   },
+     * );
+     * ```
+     */
+    getLatencyTimeline(startTime: Date, endTime: Date, options?: AgentGetLatencyTimelineOptions): Promise<AgentGetLatencyTimelineResponse[]>;
+    /**
+     * Builds the common POST request body shared by the agent filter endpoints —
+     * the required time window plus any optional folder/agent/project/process
+     * filters. Undefined options are omitted so the server applies its defaults.
+     */
+    private buildAgentFilterBody;
 }
 
-export { AgentListSortColumn, AgentService as Agents };
-export type { AgentFilterOptions, AgentListItem, AgentListOptions, AgentListOrderBy, AgentServiceModel };
+export { AgentErrorSortColumn, AgentListSortColumn, AgentService as Agents };
+export type { AgentError, AgentErrorOrderBy, AgentFilterOptions, AgentGetAllOptions, AgentGetConsumptionTimelineOptions, AgentGetConsumptionTimelineResponse, AgentGetErrorsOptions, AgentGetErrorsTimelineOptions, AgentGetErrorsTimelineResponse, AgentGetLatencyTimelineOptions, AgentGetLatencyTimelineResponse, AgentJobInfo, AgentListItem, AgentListOrderBy, AgentServiceModel };