feat(jobs): add Jobs.getByKey method [PLT-100298]

Exposes the existing GET_BY_KEY endpoint as a public getByKey() method
on the Jobs service. Refactors getOutput() to use getByKey() internally
instead of the private fetchJobByKey() helper.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ninja-shreyash

docs/oauth-scopes.md

@@ -14,6 +14,7 @@ This page lists the specific OAuth scopes required in external app for each SDK
 | Method | OAuth Scope |
 |--------|-------------|
 | `getAll()` | `OR.Jobs` or `OR.Jobs.Read` |
+| `getByKey()` | `OR.Jobs` or `OR.Jobs.Read` |
 | `getOutput()` | `OR.Jobs` or `OR.Jobs.Read` |
 
 ## Attachments

src/models/orchestrator/jobs.internal-types.ts

@@ -1,4 +1,4 @@
-import { JobGetAllOptions, RawJobGetResponse } from './jobs.types';
+import { JobGetAllOptions, JobGetByKeyOptions, RawJobGetResponse } from './jobs.types';
 import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '../../utils/pagination';
 
 // Combined type for job data with methods
@@ -67,6 +67,35 @@ export interface JobServiceModel {
     : 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, Machine, or Release.
+   *
+   * @param jobKey - 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.getByKey(<jobKey>, <folderId>);
+   * console.log(job.state, job.processName);
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // With expanded related entities
+   * const job = await jobs.getByKey(<jobKey>, <folderId>, {
+   *   expand: 'Robot,Machine,Release'
+   * });
+   * console.log(job.robot?.name, job.machine?.name);
+   * ```
+   */
+  getByKey(jobKey: string, folderId: number, options?: JobGetByKeyOptions): Promise<JobGetResponse>;
+
   /**
    * Gets the output of a completed job.
    *

src/models/orchestrator/jobs.models.ts

@@ -1,4 +1,4 @@
-import { JobState, RequestOptions } from '../common/types';
+import { JobState, BaseOptions, RequestOptions } from '../common/types';
 import { PaginationOptions } from '../../utils/pagination';
 import {
   JobPriority,
@@ -166,3 +166,8 @@ export type JobGetAllOptions = RequestOptions & PaginationOptions & {
   folderId?: number;
 }
 
+/**
+ * Options for getting a job by key
+ */
+export interface JobGetByKeyOptions extends BaseOptions {}
+

src/models/orchestrator/jobs.types.ts

@@ -1,10 +1,9 @@
 import { FolderScopedService } from '../../folder-scoped';
-import { RawJobGetResponse, JobGetAllOptions } from '../../../models/orchestrator/jobs.types';
-import { RawJobOutputFields } from '../../../models/orchestrator/jobs.internal-types';
+import { RawJobGetResponse, JobGetAllOptions, JobGetByKeyOptions } from '../../../models/orchestrator/jobs.types';
 import { JobServiceModel, JobGetResponse, createJobWithMethods } from '../../../models/orchestrator/jobs.models';
-import { pascalToCamelCaseKeys, transformData } from '../../../utils/transform';
+import { addPrefixToKeys, pascalToCamelCaseKeys, transformData } from '../../../utils/transform';
 import { JOB_ENDPOINTS } from '../../../utils/constants/endpoints';
-import { ODATA_PAGINATION, ODATA_OFFSET_PARAMS } from '../../../utils/constants/common';
+import { ODATA_PAGINATION, ODATA_OFFSET_PARAMS, ODATA_PREFIX } from '../../../utils/constants/common';
 import { JobMap } from '../../../models/orchestrator/jobs.constants';
 import { AttachmentService } from '../attachments/attachments';
 import { ValidationError, ServerError } from '../../../core/errors';
@@ -105,6 +104,55 @@ export class JobService extends FolderScopedService implements JobServiceModel {
     }, options) as any;
   }
 
+  /**
+   * 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, Machine, or Release.
+   *
+   * @param jobKey - 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.getByKey(<jobKey>, <folderId>);
+   * console.log(job.state, job.processName);
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // With expanded related entities
+   * const job = await jobs.getByKey(<jobKey>, <folderId>, {
+   *   expand: 'Robot,Machine,Release'
+   * });
+   * console.log(job.robot?.name, job.machine?.name);
+   * ```
+   */
+  @track('Jobs.GetByKey')
+  async getByKey(jobKey: string, folderId: number, options: JobGetByKeyOptions = {}): Promise<JobGetResponse> {
+    if (!jobKey) {
+      throw new ValidationError({ message: 'jobKey is required for getByKey' });
+    }
+
+    const headers = createHeaders({ [FOLDER_ID]: folderId });
+    const keysToPrefix = Object.keys(options);
+    const apiOptions = addPrefixToKeys(options, ODATA_PREFIX, keysToPrefix);
+
+    const response = await this.get<Record<string, unknown>>(
+      JOB_ENDPOINTS.GET_BY_KEY(jobKey),
+      {
+        params: apiOptions,
+        headers,
+      }
+    );
+
+    const rawJob = transformData(pascalToCamelCaseKeys(response.data) as RawJobGetResponse, JobMap);
+    return createJobWithMethods(rawJob, this);
+  }
+
   /**
    * Gets the output of a completed job.
    *
@@ -143,44 +191,23 @@ export class JobService extends FolderScopedService implements JobServiceModel {
       throw new ValidationError({ message: 'jobKey is required for getOutput' });
     }
 
-    const job = await this.fetchJobByKey(jobKey, folderId);
+    const job = await this.getByKey(jobKey, folderId, { select: 'OutputArguments,OutputFile' });
 
-    if (job.OutputArguments) {
+    if (job.outputArguments) {
       try {
-        return JSON.parse(job.OutputArguments) as Record<string, unknown>;
+        return JSON.parse(job.outputArguments) as Record<string, unknown>;
       } catch {
         throw new ServerError({ message: 'Failed to parse job output arguments as JSON' });
       }
     }
 
-    if (job.OutputFile) {
-      return this.downloadOutputFile(job.OutputFile);
+    if (job.outputFile) {
+      return this.downloadOutputFile(job.outputFile);
     }
 
     return null;
   }
 
-  /**
-   * Fetches a job by its Key (GUID) using the GetByKey endpoint.
-   * Only selects fields needed for output extraction.
-   */
-  private async fetchJobByKey(
-    jobKey: string,
-    folderId: number
-  ): Promise<RawJobOutputFields> {
-    const headers = createHeaders({ [FOLDER_ID]: folderId });
-    const response = await this.get<RawJobOutputFields>(
-      JOB_ENDPOINTS.GET_BY_KEY(jobKey),
-      {
-        params: {
-          $select: 'OutputArguments,OutputFile',
-        },
-        headers,
-      }
-    );
-    return response.data;
-  }
-
   /**
    * Downloads the output file content via the Attachments API.
    * 1. Fetches blob access info from the attachment using AttachmentService

src/services/orchestrator/jobs/jobs.ts

@@ -62,6 +62,113 @@ describe.each(modes)('Orchestrator Jobs - Integration Tests [%s]', (mode) => {
     });
   });
 
+  describe('getByKey', () => {
+    it('should retrieve a job by key', async () => {
+      const { jobs, folderId } = getJobsService();
+
+      if (!folderId) {
+        throw new Error('INTEGRATION_TEST_FOLDER_ID is required for getByKey tests.');
+      }
+
+      // First get a job key from getAll
+      const allJobs = await jobs.getAll({
+        folderId,
+        pageSize: 1,
+      });
+
+      if (allJobs.items.length === 0) {
+        throw new Error('No jobs available to test getByKey.');
+      }
+
+      const jobKey = allJobs.items[0].key;
+      const job = await jobs.getByKey(jobKey, folderId);
+
+      expect(job).toBeDefined();
+      expect(job.id).toBeDefined();
+      expect(job.key).toBe(jobKey);
+      expect(job.state).toBeDefined();
+      expect(typeof job.id).toBe('number');
+    });
+
+    it('should retrieve a job with expand options', async () => {
+      const { jobs, folderId } = getJobsService();
+
+      if (!folderId) {
+        throw new Error('INTEGRATION_TEST_FOLDER_ID is required for getByKey tests.');
+      }
+
+      const allJobs = await jobs.getAll({
+        folderId,
+        pageSize: 1,
+      });
+
+      if (allJobs.items.length === 0) {
+        throw new Error('No jobs available to test getByKey with expand.');
+      }
+
+      const jobKey = allJobs.items[0].key;
+      const job = await jobs.getByKey(jobKey, folderId, {
+        expand: 'Robot,Machine,Release',
+      });
+
+      expect(job).toBeDefined();
+      expect(job.key).toBe(jobKey);
+    });
+
+    it('should have bound getOutput method on result', async () => {
+      const { jobs, folderId } = getJobsService();
+
+      if (!folderId) {
+        throw new Error('INTEGRATION_TEST_FOLDER_ID is required for getByKey tests.');
+      }
+
+      const allJobs = await jobs.getAll({
+        folderId,
+        pageSize: 1,
+      });
+
+      if (allJobs.items.length === 0) {
+        throw new Error('No jobs available to test getByKey bound methods.');
+      }
+
+      const jobKey = allJobs.items[0].key;
+      const job = await jobs.getByKey(jobKey, folderId);
+
+      expect(job.getOutput).toBeDefined();
+      expect(typeof job.getOutput).toBe('function');
+    });
+
+    it('should have transformed camelCase fields and no PascalCase fields', async () => {
+      const { jobs, folderId } = getJobsService();
+
+      if (!folderId) {
+        throw new Error('INTEGRATION_TEST_FOLDER_ID is required for getByKey transform tests.');
+      }
+
+      const allJobs = await jobs.getAll({
+        folderId,
+        pageSize: 1,
+      });
+
+      if (allJobs.items.length === 0) {
+        throw new Error('No jobs available to validate transform.');
+      }
+
+      const jobKey = allJobs.items[0].key;
+      const job = await jobs.getByKey(jobKey, folderId);
+
+      // Verify transformed camelCase fields exist
+      expect(job.createdTime).toBeDefined();
+      expect(job.processName).toBeDefined();
+      expect(job.folderId).toBeDefined();
+
+      // Verify original PascalCase API fields are absent
+      expect((job as any).CreationTime).toBeUndefined();
+      expect((job as any).ReleaseName).toBeUndefined();
+      expect((job as any).OrganizationUnitId).toBeUndefined();
+    });
+  });
+
   describe('getOutput', () => {
     it('should return parsed output or null for a completed job', async () => {
       const { jobs, folderId } = getJobsService();