@uipath/uipath-typescript 1.2.0 → 1.2.2

package/dist/jobs/index.d.ts

@@ -0,0 +1,724 @@
+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;
+        };
+    };
+}
+
+/**
+ * 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;
+    /**
+     * 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.
+     *
+     * @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);
+    /**
+     * 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;
+}
+
+/**
+ * Base service for services that need folder-specific functionality.
+ *
+ * Extends BaseService with additional methods for working with folder-scoped resources
+ * in UiPath Orchestrator. Services that work with folders (Assets, Queues) extend this class.
+ *
+ * @remarks
+ * This class provides helper methods for making folder-scoped API calls, handling folder IDs
+ * in request headers, and managing cross-folder queries.
+ */
+declare class FolderScopedService extends BaseService {
+    /**
+     * Gets resources in a folder with optional query parameters
+     *
+     * @param endpoint - API endpoint to call
+     * @param folderId - required folder ID
+     * @param options - Query options
+     * @param transformFn - Optional function to transform the response data
+     * @returns Promise resolving to an array of resources
+     */
+    protected _getByFolder<T, R = T>(endpoint: string, folderId: number, options?: Record<string, any>, transformFn?: (item: T) => R): Promise<R[]>;
+}
+
+/**
+ * Common enum for job state used across services
+ */
+declare enum JobState {
+    Pending = "Pending",
+    Running = "Running",
+    Stopping = "Stopping",
+    Terminating = "Terminating",
+    Faulted = "Faulted",
+    Successful = "Successful",
+    Stopped = "Stopped",
+    Suspended = "Suspended",
+    Resumed = "Resumed"
+}
+interface BaseOptions {
+    expand?: string;
+    select?: string;
+}
+/**
+ * Common request options interface used across services for querying data
+ */
+interface RequestOptions extends BaseOptions {
+    filter?: string;
+    orderby?: string;
+}
+
+/**
+ * Enum for package types
+ */
+declare enum PackageType {
+    Undefined = "Undefined",
+    Process = "Process",
+    ProcessOrchestration = "ProcessOrchestration",
+    WebApp = "WebApp",
+    Agent = "Agent",
+    TestAutomationProcess = "TestAutomationProcess",
+    Api = "Api",
+    MCPServer = "MCPServer",
+    BusinessRules = "BusinessRules",
+    CaseManagement = "CaseManagement",
+    Flow = "Flow",
+    Function = "Function"
+}
+/**
+ * Enum for job priority
+ */
+declare enum JobPriority {
+    Low = "Low",
+    Normal = "Normal",
+    High = "High"
+}
+/**
+ * Enum for remote control access
+ */
+declare enum RemoteControlAccess {
+    None = "None",
+    ReadOnly = "ReadOnly",
+    Full = "Full"
+}
+/**
+ * Enum for job source type
+ */
+declare enum JobSourceType {
+    Manual = "Manual",
+    Schedule = "Schedule",
+    Agent = "Agent",
+    Queue = "Queue",
+    StudioWeb = "StudioWeb",
+    IntegrationTrigger = "IntegrationTrigger",
+    StudioDesktop = "StudioDesktop",
+    AutomationOpsPipelines = "AutomationOpsPipelines",
+    Apps = "Apps",
+    SAP = "SAP",
+    HttpTrigger = "HttpTrigger",
+    HttpTriggerCallback = "HttpTriggerCallback",
+    RobotAPI = "RobotAPI",
+    CommandLine = "CommandLine",
+    RobotNetAPI = "RobotNetAPI",
+    Autopilot = "Autopilot",
+    TestManager = "TestManager",
+    AgentService = "AgentService",
+    ProcessOrchestration = "ProcessOrchestration",
+    PluginEcosystem = "PluginEcosystem",
+    PerformanceTesting = "PerformanceTesting",
+    AgentHub = "AgentHub",
+    ApiWorkflow = "ApiWorkflow",
+    CaseManagement = "CaseManagement"
+}
+/**
+ * Enum for stop strategy
+ */
+declare enum StopStrategy {
+    SoftStop = "SoftStop",
+    Kill = "Kill"
+}
+/**
+ * Enum for runtime type
+ */
+declare enum RuntimeType {
+    NonProduction = "NonProduction",
+    Attended = "Attended",
+    Unattended = "Unattended",
+    Development = "Development",
+    Studio = "Studio",
+    RpaDeveloper = "RpaDeveloper",
+    StudioX = "StudioX",
+    CitizenDeveloper = "CitizenDeveloper",
+    Headless = "Headless",
+    StudioPro = "StudioPro",
+    RpaDeveloperPro = "RpaDeveloperPro",
+    TestAutomation = "TestAutomation",
+    AutomationCloud = "AutomationCloud",
+    Serverless = "Serverless",
+    AutomationKit = "AutomationKit",
+    ServerlessTestAutomation = "ServerlessTestAutomation",
+    AutomationCloudTestAutomation = "AutomationCloudTestAutomation",
+    AttendedStudioWeb = "AttendedStudioWeb",
+    Hosting = "Hosting",
+    AssistantWeb = "AssistantWeb",
+    ProcessOrchestration = "ProcessOrchestration",
+    AgentService = "AgentService",
+    AppTest = "AppTest",
+    PerformanceTest = "PerformanceTest",
+    BusinessRule = "BusinessRule",
+    CaseManagement = "CaseManagement",
+    Flow = "Flow"
+}
+/**
+ * Interface for common folder properties
+ */
+interface FolderProperties {
+    folderId: number;
+    folderName: string | null;
+}
+/**
+ * Interface for robot metadata
+ */
+interface RobotMetadata {
+    id: number;
+    name?: string;
+    username?: string;
+}
+/**
+ * Interface for machine
+ */
+interface Machine {
+    id: number;
+    name?: string;
+}
+/**
+ * Interface for job error
+ */
+interface JobError {
+    code?: string;
+    title?: string;
+    detail?: string;
+    category?: string;
+    status?: number;
+    timestamp?: string;
+}
+/**
+ * Enum for job type
+ */
+declare enum JobType {
+    Unattended = "Unattended",
+    Attended = "Attended",
+    ServerlessGeneric = "ServerlessGeneric"
+}
+
+/**
+ * Enum for job sub-state
+ */
+declare enum JobSubState {
+    WithFaults = "WITH_FAULTS",
+    Manually = "MANUALLY"
+}
+/**
+ * Enum for serverless job type
+ */
+declare enum ServerlessJobType {
+    RobotJob = "RobotJob",
+    WebApp = "WebApp",
+    LoadTest = "LoadTest",
+    StudioWebDesigner = "StudioWebDesigner",
+    PublishStudioProject = "PublishStudioProject",
+    JsApi = "JsApi",
+    PythonCodedAgent = "PythonCodedAgent",
+    MCPServer = "MCPServer",
+    PythonCodedSystemAgent = "PythonCodedSystemAgent",
+    PythonAgent = "PythonAgent"
+}
+/**
+ * Interface for process metadata associated with a job.
+ * Represents a lightweight summary of the process (release) linked to a job.
+ * Available when using 'expand: "Release"' in the query.
+ */
+interface ProcessMetadata {
+    /** The unique key of the release */
+    key?: string;
+    /** The process key identifying the package */
+    processKey?: string;
+    /** The version of the process package */
+    processVersion?: string;
+    /** Whether this is the latest version of the process */
+    isLatestVersion?: boolean;
+    /** The display name of the process */
+    name?: string;
+    /** The numeric ID of the release */
+    id?: number;
+}
+/**
+ * Interface for job response
+ */
+interface JobGetResponse extends FolderProperties {
+    /** The unique numeric identifier of the job */
+    id: number;
+    /** The unique job identifier (GUID) */
+    key: string;
+    /** The current execution state of the job */
+    state: JobState;
+    /** The date and time when the job was created */
+    createdTime: string;
+    /** The date and time when the job execution started, or null if the job hasn't started yet */
+    startTime: string | null;
+    /** The date and time when the job execution ended, or null if the job hasn't ended yet */
+    endTime: string | null;
+    /** The date and time when the job was last modified */
+    lastModifiedTime: string | null;
+    /** The date and time when the job was resumed after suspension */
+    resumeTime: string | null;
+    /** The name of the process (release) associated with the job */
+    processName: string | null;
+    /** Path to the entry point workflow (XAML) that will be executed by the robot */
+    entryPointPath: string | null;
+    /** The name of the machine where the robot ran the job */
+    hostMachineName: string | null;
+    /** Input parameters as a JSON string passed to job execution */
+    inputArguments: string | null;
+    /** Output parameters as a JSON string resulted from job execution */
+    outputArguments: string | null;
+    /** Environment variables as a JSON string passed to the job execution */
+    environmentVariables: string | null;
+    /** Additional information about the current job */
+    info: string | null;
+    /** The source name of the job, describing how the job was triggered */
+    source: string | null;
+    /** Reference identifier for the job, used for external correlation */
+    reference: string | null;
+    /** The execution priority of the job */
+    jobPriority: JobPriority | null;
+    /** Value for more granular control over execution priority (1-100) */
+    specificPriorityValue: number | null;
+    /** The type of the job - Attended if started via the robot, Unattended otherwise */
+    type: JobType;
+    /** The package type of the process associated with the job */
+    packageType: PackageType;
+    /** The runtime type of the robot which can pick up the job */
+    runtimeType: RuntimeType | null;
+    /** The source type indicating how the job was triggered */
+    sourceType: JobSourceType;
+    /** The type of the serverless job, or null for non-serverless jobs */
+    serverlessJobType: ServerlessJobType | null;
+    /** The stop strategy for the job */
+    stopStrategy: StopStrategy | null;
+    /** The remote control access level for the job */
+    remoteControlAccess: RemoteControlAccess;
+    /** The folder key (GUID) of the folder this job is part of */
+    folderKey: string | null;
+    /** The unique identifier grouping multiple jobs, usually generated when started by a schedule */
+    batchExecutionKey: string;
+    /** The parent job key (GUID), set when the job was started by another job */
+    parentJobKey: string | null;
+    /** The ID of the schedule that started the job, or null if started by the user */
+    startingScheduleId: number | null;
+    /** The starting trigger ID, can be ApiTriggerId or HttpTriggerId */
+    startingTriggerId: string | null;
+    /** The process version ID */
+    processVersionId: number | null;
+    /** Expected maximum running time in seconds before the job is flagged */
+    maxExpectedRunningTimeSeconds: number | null;
+    /** Whether the job requires user interaction */
+    requiresUserInteraction: boolean;
+    /** If set, the job will resume on the same robot-machine pair on which it initially ran */
+    resumeOnSameContext: boolean;
+    /** Distinguishes between multiple job suspend/resume cycles */
+    resumeVersion: number | null;
+    /** The sub-state in which the job is, providing more granular status information */
+    subState: JobSubState | null;
+    /** The target runtime for the job */
+    targetRuntime: string | null;
+    /** The trace ID for distributed tracing */
+    traceId: string | null;
+    /** The parent span ID for distributed tracing */
+    parentSpanId: string | null;
+    /** The error code associated with a failed job */
+    errorCode: string | null;
+    /** The machine associated with the job (available when using expand=Machine) */
+    machine?: Machine;
+    /** The robot associated with the job (available when using expand=Robot) */
+    robot?: RobotMetadata;
+    /** The process metadata associated with the job (available when using expand=Release) */
+    process?: ProcessMetadata | null;
+    /** Error details for the job, or null if the job has no errors */
+    jobError: JobError | null;
+}
+/**
+ * Options for getting all jobs
+ */
+type JobGetAllOptions = RequestOptions & PaginationOptions & {
+    /**
+     * Optional folder ID to filter jobs by folder
+     */
+    folderId?: number;
+};
+
+/**
+ * Service for managing UiPath Orchestrator Jobs.
+ *
+ * Jobs represent the execution of a process (automation) on a UiPath Robot. Each job tracks the lifecycle of a single process run, including its state, timing, input/output arguments, and associated resources. [UiPath Jobs Guide](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/about-jobs)
+ *
+ * ### Usage
+ *
+ * Prerequisites: Initialize the SDK first - see [Getting Started](/uipath-typescript/getting-started/#import-initialize)
+ *
+ * ```typescript
+ * import { Jobs } from '@uipath/uipath-typescript/jobs';
+ *
+ * const jobs = new Jobs(sdk);
+ * const allJobs = await jobs.getAll();
+ * ```
+ */
+interface JobServiceModel {
+    /**
+     * Gets all jobs across folders with optional filtering
+     *
+     * @param options - Query options including optional folderId and pagination options
+     * @returns Promise resolving to either an array of jobs {@link NonPaginatedResponse}<{@link JobGetResponse}> or a {@link PaginatedResponse}<{@link JobGetResponse}> when pagination options are used.
+     * {@link JobGetResponse}
+     * @example
+     * ```typescript
+     * // Get all jobs
+     * const allJobs = await jobs.getAll();
+     *
+     * // Get all jobs in a specific folder
+     * const folderJobs = await jobs.getAll({ folderId: <folderId> });
+     *
+     * // With filtering
+     * const runningJobs = await jobs.getAll({
+     *   filter: "state eq 'Running'"
+     * });
+     *
+     * // First page with pagination
+     * const page1 = await jobs.getAll({ pageSize: 10 });
+     *
+     * // Navigate using cursor
+     * if (page1.hasNextPage) {
+     *   const page2 = await jobs.getAll({ cursor: page1.nextCursor });
+     * }
+     *
+     * // Jump to specific page
+     * const page5 = await jobs.getAll({
+     *   jumpToPage: 5,
+     *   pageSize: 10
+     * });
+     * ```
+     */
+    getAll<T extends JobGetAllOptions = JobGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<JobGetResponse> : NonPaginatedResponse<JobGetResponse>>;
+}
+
+/**
+ * Service for interacting with UiPath Orchestrator Jobs API
+ */
+declare class JobService extends FolderScopedService implements JobServiceModel {
+    /**
+     * Gets all jobs across folders with optional filtering
+     *
+     * @param options - Query options including optional folderId and pagination options
+     * @returns Promise resolving to array of jobs or paginated response
+     *
+     * @example
+     * ```typescript
+     * import { Jobs } from '@uipath/uipath-typescript/jobs';
+     *
+     * const jobs = new Jobs(sdk);
+     *
+     * // Get all jobs
+     * const allJobs = await jobs.getAll();
+     *
+     * // Get all jobs in a specific folder
+     * const folderJobs = await jobs.getAll({ folderId: 123 });
+     *
+     * // With filtering
+     * const runningJobs = await jobs.getAll({
+     *   filter: "state eq 'Running'"
+     * });
+     *
+     * // First page with pagination
+     * const page1 = await jobs.getAll({ pageSize: 10 });
+     *
+     * // Navigate using cursor
+     * if (page1.hasNextPage) {
+     *   const page2 = await jobs.getAll({ cursor: page1.nextCursor });
+     * }
+     * ```
+     */
+    getAll<T extends JobGetAllOptions = JobGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<JobGetResponse> : NonPaginatedResponse<JobGetResponse>>;
+}
+
+export { JobService, JobSubState, JobService as Jobs, ServerlessJobType };
+export type { JobGetAllOptions, JobGetResponse, JobServiceModel, ProcessMetadata };