@uipath/uipath-typescript 1.2.1 → 1.3.0

package/dist/tasks/index.d.ts

@@ -1,5 +1,45 @@
 import { IUiPath } from '../core/index';
 
+/**
+ * Standardized result interface for all operation methods (pause, cancel, complete, update, upload, etc.)
+ * Success responses include data from the request context or API response
+ */
+interface OperationResponse<TData> {
+    /**
+     * Whether the operation was successful
+     */
+    success: boolean;
+    /**
+     * Response data (can contain error details in case of failure)
+     */
+    data: TData;
+}
+/**
+ * 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;
+}
+
 /**
  * Simplified universal pagination cursor
  * Used to fetch next/previous pages
@@ -64,270 +104,9 @@ 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;
-}
-
-/**
- * Standardized result interface for all operation methods (pause, cancel, complete, update, upload, etc.)
- * Success responses include data from the request context or API response
- */
-interface OperationResponse<TData> {
-    /**
-     * Whether the operation was successful
-     */
-    success: boolean;
-    /**
-     * Response data (can contain error details in case of failure)
-     */
-    data: TData;
-}
-/**
- * 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;
-}
+}) | (T & {
+    jumpToPage: number;
+});
 
 interface UserLoginInfo {
     name: string;
@@ -337,10 +116,23 @@ interface UserLoginInfo {
     displayName: string;
     id: number;
 }
+/**
+ * Types of tasks available in Action Center.
+ * Each type determines the task's behavior, UI rendering, and completion requirements.
+ */
 declare enum TaskType {
+    /** A form-based task that renders a UiPath form layout for user input */
     Form = "FormTask",
+    /** An externally managed task handled outside of Action Center */
     External = "ExternalTask",
-    App = "AppTask"
+    /** A task powered by a UiPath App */
+    App = "AppTask",
+    /** A document validation task for reviewing and correcting extracted document data */
+    DocumentValidation = "DocumentValidationTask",
+    /** A document classification task for categorizing documents */
+    DocumentClassification = "DocumentClassificationTask",
+    /** A data labeling task for annotating training data */
+    DataLabeling = "DataLabelingTask"
 }
 declare enum TaskPriority {
     Low = "Low",
@@ -520,7 +312,23 @@ type TaskCompleteOptions = {
     data?: any;
     action?: string;
 } | {
-    type: Exclude<TaskType, TaskType.External>;
+    type: TaskType.DocumentValidation;
+    data?: any;
+    action?: string;
+} | {
+    type: TaskType.DocumentClassification;
+    data?: any;
+    action?: string;
+} | {
+    type: TaskType.DataLabeling;
+    data?: any;
+    action?: string;
+} | {
+    type: TaskType.Form;
+    data: any;
+    action: string;
+} | {
+    type: TaskType.App;
     data: any;
     action: string;
 };
@@ -551,7 +359,14 @@ type TaskGetAllOptions = RequestOptions & PaginationOptions & {
 /**
  * Query options for getting a task by ID
  */
-type TaskGetByIdOptions = BaseOptions;
+interface TaskGetByIdOptions extends BaseOptions {
+    /**
+     * Optional task type. When not provided, method will automatically identify the
+     * task type and resolve accordingly, but it will be slower.
+     * When provided, it will skip the step to identify the task type, so it will be faster.
+     */
+    taskType?: TaskType;
+}
 /**
  * Options for getting users with task permissions
  */
@@ -620,10 +435,9 @@ interface TaskServiceModel {
     getAll<T extends TaskGetAllOptions = TaskGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<TaskGetResponse> : NonPaginatedResponse<TaskGetResponse>>;
     /**
      * Gets a task by ID
-     * IMPORTANT: For form tasks, folderId must be provided.
      * @param id - The ID of the task to retrieve
-     * @param options - Optional query parameters
-     * @param folderId - Optional folder ID (REQUIRED for form tasks)
+     * @param options - Optional query parameters including taskType for faster retrieval {@link TaskGetByIdOptions}
+     * @param folderId - Optional folder ID (REQUIRED when options.taskType is provided)
      * @returns Promise resolving to the task
      * {@link TaskGetResponse}
      * @example
@@ -632,10 +446,13 @@ interface TaskServiceModel {
      * const task = await tasks.getById(<taskId>);
      *
      * // Get a form task by ID
-     * const formTask = await tasks.getById(<taskId>, <folderId>);
+     * const formTask = await tasks.getById(<taskId>, {}, <folderId>);
      *
      * // Access form task properties
      * console.log(formTask.formLayout);
+     *
+     * // Get a document validation task by ID (faster with taskType provided in the options)
+     * const dvTask = await tasks.getById(<taskId>, { taskType: TaskType.DocumentValidation }, <folderId>);
      * ```
      */
     getById(id: number, options?: TaskGetByIdOptions, folderId?: number): Promise<TaskGetResponse>;
@@ -834,6 +651,227 @@ type TaskCreateResponse = RawTaskCreateResponse & TaskMethods;
  */
 declare function createTaskWithMethods(taskData: RawTaskGetResponse | RawTaskCreateResponse, service: TaskServiceModel): TaskGetResponse | TaskCreateResponse;
 
+/**
+ * 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;
+}
+
 /**
  * Service for interacting with UiPath Tasks API
  */
@@ -945,23 +983,24 @@ declare class TaskService extends BaseService implements TaskServiceModel {
     getAll<T extends TaskGetAllOptions = TaskGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<TaskGetResponse> : NonPaginatedResponse<TaskGetResponse>>;
     /**
      * Gets a task by ID
-     * IMPORTANT: For form tasks, folderId must be provided.
-     *
      * @param id - The ID of the task to retrieve
-     * @param options - Optional query parameters
-     * @param folderId - Optional folder ID (REQUIRED for form tasks)
-     * @returns Promise resolving to the task (form tasks will return form-specific data)
-     *
+     * @param options - Optional query parameters including taskType for faster retrieval {@link TaskGetByIdOptions}
+     * @param folderId - Optional folder ID (REQUIRED when options.taskType is provided)
+     * @returns Promise resolving to the task
+     * {@link TaskGetResponse}
      * @example
      * ```typescript
-     * import { Tasks } from '@uipath/uipath-typescript/tasks';
+     * // Get a task by ID
+     * const task = await tasks.getById(<taskId>);
      *
-     * const tasks = new Tasks(sdk);
+     * // Get a form task by ID
+     * const formTask = await tasks.getById(<taskId>, {}, <folderId>);
      *
-     * // Get task by ID
-     * const task = await tasks.getById(123);
+     * // Access form task properties
+     * console.log(formTask.formLayout);
      *
-     * // If the task is a form task, it will automatically return form-specific data
+     * // Get a document validation task by ID (faster with taskType provided in the options)
+     * const dvTask = await tasks.getById(<taskId>, { taskType: TaskType.DocumentValidation }, <folderId>);
      * ```
      */
     getById(id: number, options?: TaskGetByIdOptions, folderId?: number): Promise<TaskGetResponse>;
@@ -1093,14 +1132,19 @@ declare class TaskService extends BaseService implements TaskServiceModel {
      */
     complete(options: TaskCompletionOptions, folderId: number): Promise<OperationResponse<TaskCompletionOptions>>;
     /**
-     * Gets a form task by ID (private method)
+     * Routes to the type-specific endpoint based on task type.
+     */
+    private getByTaskType;
+    /**
+     * Fetches a task from a type-specific endpoint.
      *
-     * @param id - The ID of the form task to retrieve
+     * @param id - The task ID
      * @param folderId - Required folder ID
-     * @param options - Optional query parameters
-     * @returns Promise resolving to the form task
+     * @param endpoint - The type-specific endpoint to call
+     * @param extraParams - Additional query parameters (e.g. form options)
+     * @returns Promise resolving to the task
      */
-    private getFormTaskById;
+    private getTaskByTypeEndpoint;
     /**
      * Process parameters for task queries with folder filtering
      * @param options - The REST API options to process