@uipath/uipath-typescript 1.3.11 → 1.4.1

package/dist/agents/index.d.ts

@@ -0,0 +1,961 @@
+import { IUiPath } from '../core/index';
+
+/**
+ * Simplified universal pagination cursor
+ * Used to fetch next/previous pages
+ */
+interface PaginationCursor {
+    /** Opaque string containing all information needed to fetch next page */
+    value: string;
+}
+/**
+ * Discriminated union for pagination methods - ensures cursor and jumpToPage are mutually exclusive
+ */
+type PaginationMethodUnion = {
+    cursor?: PaginationCursor;
+    jumpToPage?: never;
+} | {
+    cursor?: never;
+    jumpToPage?: number;
+} | {
+    cursor?: never;
+    jumpToPage?: never;
+};
+/**
+ * Pagination options. Users cannot specify both cursor and jumpToPage.
+ */
+type PaginationOptions = {
+    /** Size of the page to fetch (items per page) */
+    pageSize?: number;
+} & PaginationMethodUnion;
+/**
+ * Paginated response containing items and navigation information
+ */
+interface PaginatedResponse<T> {
+    /** The items in the current page */
+    items: T[];
+    /** Total count of items across all pages (if available) */
+    totalCount?: number;
+    /** Whether more pages are available */
+    hasNextPage: boolean;
+    /** Cursor to fetch the next page (if available) */
+    nextCursor?: PaginationCursor;
+    /** Cursor to fetch the previous page (if available) */
+    previousCursor?: PaginationCursor;
+    /** Current page number (1-based, if available) */
+    currentPage?: number;
+    /** Total number of pages (if available) */
+    totalPages?: number;
+    /** Whether this pagination type supports jumping to arbitrary pages */
+    supportsPageJump: boolean;
+}
+/**
+ * Response for non-paginated calls that includes both data and total count
+ */
+interface NonPaginatedResponse<T> {
+    items: T[];
+    totalCount?: number;
+}
+/**
+ * Helper type for defining paginated method overloads
+ * Creates a union type of all ways pagination can be triggered
+ */
+type HasPaginationOptions<T> = (T & {
+    pageSize: number;
+}) | (T & {
+    cursor: PaginationCursor;
+}) | (T & {
+    jumpToPage: number;
+});
+
+/**
+ * Pagination types supported by the SDK
+ */
+declare enum PaginationType {
+    OFFSET = "offset",
+    TOKEN = "token"
+}
+/**
+ * Interface for service access methods needed by pagination helpers
+ */
+interface PaginationServiceAccess {
+    get<T>(path: string, options?: any): Promise<{
+        data: T;
+    }>;
+    post<T>(path: string, body?: any, options?: any): Promise<{
+        data: T;
+    }>;
+    requestWithPagination<T>(method: string, path: string, paginationOptions: PaginationOptions, options: RequestWithPaginationOptions): Promise<PaginatedResponse<T>>;
+}
+/**
+ * Field names for extracting data from paginated responses.
+ */
+interface PaginationFieldNames {
+    itemsField?: string;
+    totalCountField?: string;
+    continuationTokenField?: string;
+}
+/**
+ * Options for the requestWithPagination method in BaseService.
+ */
+interface RequestWithPaginationOptions extends RequestSpec {
+    pagination: PaginationFieldNames & {
+        paginationType: PaginationType;
+        paginationParams?: {
+            pageSizeParam?: string;
+            offsetParam?: string;
+            tokenParam?: string;
+            countParam?: string;
+            convertToSkip?: boolean;
+            zeroBased?: boolean;
+        };
+    };
+}
+
+/**
+ * HTTP methods supported by the API client
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Supported response types for API requests
+ */
+type ResponseType = 'json' | 'text' | 'blob' | 'arraybuffer' | 'stream';
+/**
+ * Query parameters type with support for arrays and nested objects
+ */
+type QueryParams = Record<string, string | number | boolean | Array<string | number | boolean> | null | undefined>;
+/**
+ * Standard HTTP headers type
+ */
+type Headers = Record<string, string>;
+/**
+ * Options for request retries
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Base delay between retries in milliseconds */
+    retryDelay?: number;
+    /** Whether to use exponential backoff */
+    useExponentialBackoff?: boolean;
+    /** Status codes that should trigger a retry */
+    retryableStatusCodes?: number[];
+}
+/**
+ * Options for request timeouts
+ */
+interface TimeoutOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Whether to abort the request on timeout */
+    abortOnTimeout?: boolean;
+}
+/**
+ * Options for request body transformation
+ */
+interface BodyOptions {
+    /** Whether to stringify the body */
+    stringify?: boolean;
+    /** Content type override */
+    contentType?: string;
+}
+/**
+ * Pagination metadata for API requests
+ */
+interface PaginationMetadata {
+    /** Type of pagination used by the API endpoint */
+    paginationType: PaginationType;
+    /** Response field containing items array (defaults to 'value') */
+    itemsField?: string;
+    /** Response field containing total count (defaults to '@odata.count') */
+    totalCountField?: string;
+    /** Response field containing continuation token (defaults to 'continuationToken') */
+    continuationTokenField?: string;
+}
+/**
+ * Base interface for all API requests
+ */
+interface RequestSpec {
+    /** HTTP method for the request */
+    method?: HttpMethod;
+    /** URL endpoint for the request */
+    url?: string;
+    /** Query parameters to be appended to the URL */
+    params?: QueryParams;
+    /** HTTP headers to include with the request */
+    headers?: Headers;
+    /** Raw body content (takes precedence over data) */
+    body?: unknown;
+    /** Expected response type */
+    responseType?: ResponseType;
+    /** Request timeout options */
+    timeoutOptions?: TimeoutOptions;
+    /** Retry behavior options */
+    retryOptions?: RetryOptions;
+    /** Body transformation options */
+    bodyOptions?: BodyOptions;
+    /** AbortSignal for cancelling the request */
+    signal?: AbortSignal;
+    /** Pagination metadata for the request */
+    pagination?: PaginationMetadata;
+}
+
+interface ApiResponse<T> {
+    data: T;
+}
+/**
+ * Base class for all UiPath SDK services.
+ *
+ * Provides common functionality for authentication, configuration, and API communication.
+ * All service classes extend this base to inherit dependency injection and HTTP client access.
+ *
+ * This class implements the dependency injection pattern where services receive a configured
+ * UiPath instance. The ApiClient is created internally and handles all HTTP operations
+ * including authentication token management.
+ *
+ * @remarks
+ * Service classes should extend this base and call `super(uiPath)` in their constructor.
+ * Protected HTTP methods (get, post, put, patch, delete) are available to all subclasses.
+ *
+ */
+declare class BaseService {
+    #private;
+    /**
+     * SDK configuration (read-only). Available to subclasses so they can
+     * fall back to init-time defaults like `folderKey`.
+     */
+    protected readonly config: {
+        folderKey?: string;
+    };
+    /**
+     * Creates a base service instance with dependency injection.
+     *
+     * Extracts configuration, execution context, and token manager from the UiPath instance
+     * to initialize an authenticated API client. The ApiClient handles all HTTP operations
+     * and token management internally.
+     *
+     * @param instance - UiPath SDK instance providing authentication and configuration.
+     *                    Services receive this via dependency injection in the modular pattern.
+     * @param headers - Optional default headers to include in every request (e.g. `x-uipath-external-user-id` for
+     *                  CAS external-app auth)
+     *
+     * @example
+     * ```typescript
+     * // Services automatically call this via super()
+     * export class EntityService extends BaseService {
+     *   constructor(instance: IUiPath) {
+     *     super(instance); // Initializes the internal ApiClient
+     *   }
+     * }
+     *
+     * // Usage in modular pattern
+     * import { UiPath } from '@uipath/uipath-typescript/core';
+     * import { Entities } from '@uipath/uipath-typescript/entities';
+     *
+     * const sdk = new UiPath(config);
+     * await sdk.initialize();
+     * const entities = new Entities(sdk);
+     * ```
+     */
+    constructor(instance: IUiPath, headers?: Record<string, string>);
+    /**
+     * Gets a valid authentication token, refreshing if necessary.
+     * Use this when you need to manually add Authorization headers (e.g., direct uploads).
+     *
+     * @returns Promise resolving to a valid access token string
+     * @throws AuthenticationError if no token is available or refresh fails
+     */
+    protected getValidAuthToken(): Promise<string>;
+    /**
+     * Creates a service accessor for pagination helpers
+     * This allows pagination helpers to access protected methods without making them public
+     */
+    protected createPaginationServiceAccess(): PaginationServiceAccess;
+    protected request<T>(method: string, path: string, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected requestWithSpec<T>(spec: RequestSpec): Promise<ApiResponse<T>>;
+    protected get<T>(path: string, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected post<T>(path: string, data?: unknown, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected put<T>(path: string, data?: unknown, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected patch<T>(path: string, data?: unknown, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected delete<T>(path: string, options?: RequestSpec): Promise<ApiResponse<T>>;
+    /**
+     * Execute a request with cursor-based pagination
+     */
+    protected requestWithPagination<T>(method: string, path: string, paginationOptions: PaginationOptions, options: RequestWithPaginationOptions): Promise<PaginatedResponse<T>>;
+    /**
+     * Validates and prepares pagination parameters from options
+     */
+    private validateAndPreparePaginationParams;
+    /**
+     * Prepares request parameters for pagination based on pagination type
+     */
+    private preparePaginationRequestParams;
+    /**
+     * Creates a paginated response from API response
+     */
+    private createPaginatedResponseFromResponse;
+    /**
+     * Determines if there are more pages based on pagination type and metadata
+     */
+    private determineHasMorePages;
+}
+
+/**
+ * Filter fields shared by agent endpoints that accept a
+ * folder/agent/project scope (`/Agents/agents`, `/Agents/errors`, etc.).
+ */
+interface AgentFilterOptions {
+    /** Optional folder keys to scope the lookup. Intersected with the user's accessible folders. */
+    folderKeys?: string[];
+    /** Filter to specific agent names. */
+    agentNames?: string[];
+    /** Filter to specific project keys. */
+    projectKeys?: string[];
+    /** Filter to a single agent by ID. */
+    agentId?: string;
+    /** Filter to a specific process version. */
+    processVersion?: string;
+}
+/**
+ * Columns available for ordering results.
+ */
+declare enum AgentListSortColumn {
+    AgentName = "AgentName",
+    ParentProcess = "ParentProcess",
+    LastRun = "LastRun",
+    HealthScore = "HealthScore",
+    LastIncident = "LastIncident",
+    FolderName = "FolderName",
+    /** Quantity of AGU (Agent Units) consumed */
+    QuantityAGU = "QuantityAGU",
+    /** Quantity of PLTU (Platform Units) consumed */
+    QuantityPLTU = "QuantityPLTU",
+    FolderPath = "FolderPath"
+}
+/**
+ * Ordering directive for the agents list.
+ */
+interface AgentListOrderBy {
+    /** Column to sort by */
+    column: AgentListSortColumn;
+    /** Sort descending. Defaults to false. */
+    desc?: boolean;
+}
+/**
+ * One row in the agents list - agent identity plus consumption and health metadata aggregated over the
+ * requested time window.
+ */
+interface AgentListItem {
+    /** Agent ID */
+    agentId: string;
+    /** Agent display name */
+    agentName: string;
+    /** Parent process name. May be `null` or `""` for jobs not bound to a parent process. */
+    parentProcess: string | null;
+    /** Folder key of the folder the agent runs in. May be `null` or `""`. */
+    folderKey: string | null;
+    /** Folder display name. May be `null` or `""`. */
+    folderName: string | null;
+    /** Fully qualified folder path. May be `null` or `""`. */
+    folderPath: string | null;
+    /** Last run timestamp */
+    lastRun: string;
+    /** Process key. May be `null` or `""` for ad-hoc jobs. */
+    processKey: string | null;
+    /** Process version. May be `null` or `""`. */
+    processVersion: string | null;
+    /** Health score (0-100) */
+    healthScore: number;
+    /** Last incident type label. May be `null` or `""`. */
+    lastIncidentType: string | null;
+    /** Total units consumed by this agent in the window */
+    unitsQuantity: number;
+    /** Display name of the units (if any). May be `null` or `""`. */
+    unitsName: string | null;
+    /** Quantity of AGU (Agent Units) consumed by this agent */
+    quantityAGU: number;
+    /** Quantity of PLTU (Platform Units) consumed by this agent */
+    quantityPLTU: number;
+}
+/**
+ * Options for getting the list of agents.
+ *
+ * Composes filter, pagination, and sort options.
+ */
+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.
+ *
+ * See [About Agents](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/about-agents)
+ * for an overview of UiPath Agents.
+ */
+interface AgentServiceModel {
+    /**
+     * Retrieves the list of agents on the tenant with consumption and health
+     * metadata 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, and filters
+     * @returns Promise resolving to a paginated or non-paginated list of {@link AgentListItem}
+     * @example
+     * ```typescript
+     * import { Agents, AgentListSortColumn } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // Non-paginated — returns the server default page
+     * const result = await agents.getAll(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2026-05-14T00:00:00Z'),
+     * );
+     * result.items.forEach((agent) => {
+     *   console.log(`${agent.agentName} — ${agent.unitsQuantity} units, health=${agent.healthScore}`);
+     * });
+     *
+     * // Paginated — sorted by health score descending
+     * const page = await agents.getAll(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2026-05-14T00:00:00Z'),
+     *   {
+     *     pageSize: 25,
+     *     orderBy: { column: AgentListSortColumn.HealthScore, desc: true },
+     *     folderKeys: ['<folderKey1>'],
+     *   },
+     * );
+     *
+     * if (page.hasNextPage && page.nextCursor) {
+     *   const next = await agents.getAll(
+     *     new Date('2025-05-01T00:00:00Z'),
+     *     new Date('2026-05-14T00:00:00Z'),
+     *     { cursor: page.nextCursor },
+     *   );
+     * }
+     * ```
+     */
+    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[]>;
+}
+
+/**
+ * Service for interacting with the UiPath Agents API.
+ */
+declare class AgentService extends BaseService implements AgentServiceModel {
+    /**
+     * Retrieves the list of agents on the tenant with consumption and health
+     * metadata 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, and filters
+     * @returns Promise resolving to a paginated or non-paginated list of {@link AgentListItem}
+     * @example
+     * ```typescript
+     * import { Agents, AgentListSortColumn } from '@uipath/uipath-typescript/agents';
+     *
+     * const agents = new Agents(sdk);
+     *
+     * // Non-paginated — returns the server default page
+     * const result = await agents.getAll(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2026-05-14T00:00:00Z'),
+     * );
+     * result.items.forEach((agent) => {
+     *   console.log(`${agent.agentName} — ${agent.unitsQuantity} units, health=${agent.healthScore}`);
+     * });
+     *
+     * // Paginated — sorted by health score descending
+     * const page = await agents.getAll(
+     *   new Date('2025-05-01T00:00:00Z'),
+     *   new Date('2026-05-14T00:00:00Z'),
+     *   {
+     *     pageSize: 25,
+     *     orderBy: { column: AgentListSortColumn.HealthScore, desc: true },
+     *     folderKeys: ['<folderKey1>'],
+     *   },
+     * );
+     *
+     * if (page.hasNextPage && page.nextCursor) {
+     *   const next = await agents.getAll(
+     *     new Date('2025-05-01T00:00:00Z'),
+     *     new Date('2026-05-14T00:00:00Z'),
+     *     { cursor: page.nextCursor },
+     *   );
+     * }
+     * ```
+     */
+    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 { AgentErrorSortColumn, AgentListSortColumn, AgentService as Agents };
+export type { AgentError, AgentErrorOrderBy, AgentFilterOptions, AgentGetAllOptions, AgentGetConsumptionTimelineOptions, AgentGetConsumptionTimelineResponse, AgentGetErrorsOptions, AgentGetErrorsTimelineOptions, AgentGetErrorsTimelineResponse, AgentGetLatencyTimelineOptions, AgentGetLatencyTimelineResponse, AgentJobInfo, AgentListItem, AgentListOrderBy, AgentServiceModel };