@uipath/uipath-typescript 1.2.2 → 1.3.1

package/dist/jobs/index.d.ts

@@ -227,6 +227,8 @@ declare class BaseService {
      *
      * @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
@@ -246,7 +248,7 @@ declare class BaseService {
      * const entities = new Entities(sdk);
      * ```
      */
-    constructor(instance: IUiPath);
+    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).
@@ -506,7 +508,7 @@ declare enum ServerlessJobType {
 /**
  * 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.
+ * Available when using 'expand: "release"' in the query.
  */
 interface ProcessMetadata {
     /** The unique key of the release */
@@ -523,9 +525,9 @@ interface ProcessMetadata {
     id?: number;
 }
 /**
- * Interface for job response
+ * Raw job response from the API before method attachment
  */
-interface JobGetResponse extends FolderProperties {
+interface RawJobGetResponse extends FolderProperties {
     /** The unique numeric identifier of the job */
     id: number;
     /** The unique job identifier (GUID) */
@@ -552,6 +554,8 @@ interface JobGetResponse extends FolderProperties {
     inputArguments: string | null;
     /** Output parameters as a JSON string resulted from job execution */
     outputArguments: string | null;
+    /** Attachment key for file-based output when output is too large for inline arguments */
+    outputFile: string | null;
     /** Environment variables as a JSON string passed to the job execution */
     environmentVariables: string | null;
     /** Additional information about the current job */
@@ -608,11 +612,11 @@ interface JobGetResponse extends FolderProperties {
     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) */
+    /** The machine associated with the job (available when using expand=machine) */
     machine?: Machine;
-    /** The robot associated with the job (available when using expand=Robot) */
+    /** 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) */
+    /** The process metadata associated with the job */
     process?: ProcessMetadata | null;
     /** Error details for the job, or null if the job has no errors */
     jobError: JobError | null;
@@ -626,7 +630,14 @@ type JobGetAllOptions = RequestOptions & PaginationOptions & {
      */
     folderId?: number;
 };
+/**
+ * Options for getting a job by ID
+ */
+interface JobGetByIdOptions extends BaseOptions {
+}
 
+/** Combined response type for job data with bound methods. */
+type JobGetResponse = RawJobGetResponse & JobMethods;
 /**
  * Service for managing UiPath Orchestrator Jobs.
  *
@@ -645,9 +656,15 @@ type JobGetAllOptions = RequestOptions & PaginationOptions & {
  */
 interface JobServiceModel {
     /**
-     * Gets all jobs across folders with optional filtering
+     * Gets all jobs across folders with optional filtering and pagination.
      *
-     * @param options - Query options including optional folderId and pagination options
+     * Returns jobs with full details including state, timing, and input/output arguments.
+     * Pass `folderId` to scope the query to a specific folder.
+     *
+     * !!! info "Input and output fields are not included in `getAll` responses"
+     *     The `inputArguments`, `inputFile`, `outputArguments`, and `outputFile` fields will always be `null` in the `getAll` response. To retrieve a job's output, use the {@link getOutput} method with the job's `key` and `folderId`.
+     *
+     * @param options - Query options including optional folderId, filtering, 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
@@ -679,29 +696,133 @@ interface JobServiceModel {
      * ```
      */
     getAll<T extends JobGetAllOptions = JobGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<JobGetResponse> : NonPaginatedResponse<JobGetResponse>>;
+    /**
+     * Gets a job by its unique key (GUID).
+     *
+     * Returns the full job details including state, timing, input/output arguments, and error information.
+     * Use `expand` to include related entities like `robot`, or `machine`.
+     *
+     * @param id - The unique key (GUID) of the job to retrieve
+     * @param folderId - The folder ID where the job resides
+     * @param options - Optional query options for expanding or selecting fields
+     * @returns Promise resolving to a {@link JobGetResponse} with full job details and bound methods
+     *
+     * @example
+     * ```typescript
+     * // Get a job by key
+     * const job = await jobs.getById(<id>, <folderId>);
+     * console.log(job.state, job.processName);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With expanded related entities
+     * const job = await jobs.getById(<id>, <folderId>, {
+     *   expand: 'robot,machine'
+     * });
+     * console.log(job.robot?.name, job.machine?.name);
+     * ```
+     */
+    getById(id: string, folderId: number, options?: JobGetByIdOptions): Promise<JobGetResponse>;
+    /**
+     * Gets the output of a completed job.
+     *
+     * Retrieves the job's output arguments, handling both inline output (stored directly on the job
+     * as a JSON string in `outputArguments`) and file-based output (stored as a blob attachment for
+     * large outputs). Returns the parsed JSON output or `null` if the job has no output.
+     *
+     * @param jobKey - The unique key (GUID) of the job to retrieve output from
+     * @param folderId - The folder ID where the job resides
+     * @returns Promise resolving to the parsed output as `Record<string, unknown>`, or `null` if no output exists
+     *
+     * @example
+     * ```typescript
+     * // Get output from a completed job
+     * const output = await jobs.getOutput(<jobKey>, <folderId>);
+     *
+     * if (output) {
+     *   console.log('Job output:', output);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get output using bound method (jobKey and folderId are taken from the job object)
+     * const allJobs = await jobs.getAll();
+     * const completedJob = allJobs.items.find(j => j.state === JobState.Successful);
+     *
+     * if (completedJob) {
+     *   const output = await completedJob.getOutput();
+     * }
+     * ```
+     */
+    getOutput(jobKey: string, folderId: number): Promise<Record<string, unknown> | null>;
 }
+/**
+ * Methods available on job response objects.
+ * These are bound to the job data and delegate to the service.
+ */
+interface JobMethods {
+    /**
+     * Gets the output of this job.
+     *
+     * Retrieves the job's output arguments, handling both inline output (stored directly on the job
+     * as a JSON string in `outputArguments`) and file-based output (stored as a blob attachment for
+     * large outputs). Returns the parsed JSON output or `null` if the job has no output.
+     *
+     * @returns Promise resolving to the parsed output as `Record<string, unknown>`, or `null` if no output exists
+     *
+     * @example
+     * ```typescript
+     * const allJobs = await jobs.getAll();
+     * const completedJob = allJobs.items.find(j => j.state === JobState.Successful);
+     *
+     * if (completedJob) {
+     *   const output = await completedJob.getOutput();
+     * }
+     * ```
+     */
+    getOutput(): Promise<Record<string, unknown> | null>;
+}
+/**
+ * Creates a job response with bound methods.
+ *
+ * @param jobData - The raw job data from API
+ * @param service - The job service instance
+ * @returns A job object with added methods
+ */
+declare function createJobWithMethods(jobData: RawJobGetResponse, service: JobServiceModel): JobGetResponse;
 
 /**
  * Service for interacting with UiPath Orchestrator Jobs API
  */
 declare class JobService extends FolderScopedService implements JobServiceModel {
+    private attachmentService;
     /**
-     * Gets all jobs across folders with optional filtering
+     * Creates an instance of the Jobs service.
      *
-     * @param options - Query options including optional folderId and pagination options
-     * @returns Promise resolving to array of jobs or paginated response
+     * @param instance - UiPath SDK instance providing authentication and configuration
+     */
+    constructor(instance: IUiPath);
+    /**
+     * Gets all jobs across folders with optional filtering and pagination.
      *
-     * @example
-     * ```typescript
-     * import { Jobs } from '@uipath/uipath-typescript/jobs';
+     * Returns jobs with full details including state, timing, and input/output arguments.
+     * Pass `folderId` to scope the query to a specific folder.
      *
-     * const jobs = new Jobs(sdk);
+     * !!! info "Input and output fields are not included in `getAll` responses"
+     *     The `inputArguments`, `inputFile`, `outputArguments`, and `outputFile` fields will always be `null` in the `getAll` response. To retrieve a job's output, use the {@link getOutput} method with the job's `key` and `folderId`.
      *
+     * @param options - Query options including optional folderId, filtering, 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: 123 });
+     * const folderJobs = await jobs.getAll({ folderId: <folderId> });
      *
      * // With filtering
      * const runningJobs = await jobs.getAll({
@@ -715,10 +836,84 @@ declare class JobService extends FolderScopedService implements JobServiceModel
      * 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>>;
+    /**
+     * Gets a job by its unique key (GUID).
+     *
+     * Returns the full job details including state, timing, input/output arguments, and error information.
+     * Use `expand` to include related entities like `robot`, or `machine`.
+     *
+     * @param id - The unique key (GUID) of the job to retrieve
+     * @param folderId - The folder ID where the job resides
+     * @param options - Optional query options for expanding or selecting fields
+     * @returns Promise resolving to a {@link JobGetResponse} with full job details and bound methods
+     *
+     * @example
+     * ```typescript
+     * // Get a job by key
+     * const job = await jobs.getById(<id>, <folderId>);
+     * console.log(job.state, job.processName);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With expanded related entities
+     * const job = await jobs.getById(<id>, <folderId>, {
+     *   expand: 'robot,machine'
+     * });
+     * console.log(job.robot?.name, job.machine?.name);
+     * ```
+     */
+    getById(id: string, folderId: number, options?: JobGetByIdOptions): Promise<JobGetResponse>;
+    /**
+     * Gets the output of a completed job.
+     *
+     * Retrieves the job's output arguments, handling both inline output (stored directly on the job
+     * as a JSON string in `outputArguments`) and file-based output (stored as a blob attachment for
+     * large outputs). Returns the parsed JSON output or `null` if the job has no output.
+     *
+     * @param jobKey - The unique key (GUID) of the job to retrieve output from
+     * @param folderId - The folder ID where the job resides
+     * @returns Promise resolving to the parsed output as `Record<string, unknown>`, or `null` if no output exists
+     *
+     * @example
+     * ```typescript
+     * // Get output from a completed job
+     * const output = await jobs.getOutput(<jobKey>, <folderId>);
+     *
+     * if (output) {
+     *   console.log('Job output:', output);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get output using bound method (jobKey and folderId are taken from the job object)
+     * const allJobs = await jobs.getAll();
+     * const completedJob = allJobs.items.find(j => j.state === JobState.Successful);
+     *
+     * if (completedJob) {
+     *   const output = await completedJob.getOutput();
+     * }
+     * ```
+     */
+    getOutput(jobKey: string, folderId: number): Promise<Record<string, unknown> | null>;
+    /**
+     * Downloads the output file content via the Attachments API.
+     * 1. Fetches blob access info from the attachment using AttachmentService
+     * 2. Downloads content from the presigned blob URI
+     * 3. Parses and returns the JSON content
+     */
+    private downloadOutputFile;
 }
 
-export { JobService, JobSubState, JobService as Jobs, ServerlessJobType };
-export type { JobGetAllOptions, JobGetResponse, JobServiceModel, ProcessMetadata };
+export { JobService, JobState, JobSubState, JobService as Jobs, ServerlessJobType, createJobWithMethods };
+export type { JobGetAllOptions, JobGetByIdOptions, JobGetResponse, JobMethods, JobServiceModel, ProcessMetadata, RawJobGetResponse };