feat(jobs): add Jobs.stop() method [PLT-100574]

Add stop method to the Jobs service that stops one or more jobs by their
UUID keys. Resolves keys to integer IDs in batches of 50, then calls the
StopJobs OData action. Supports SoftStop and Kill strategies.

Also adds text responseType handling to api-client for endpoints returning
empty 200 responses.

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

Author: ninja-shreyash

docs/oauth-scopes.md

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

src/core/http/api-client.ts

@@ -113,6 +113,12 @@ export class ApiClient {
         return blob as T;
       }
 
+      // Handle text response type for endpoints that return empty or plain text bodies
+      if (options.responseType === RESPONSE_TYPES.TEXT) {
+        const text = await response.text();
+        return (text || undefined) as T;
+      }
+
       // Check if we're expecting XML
       const acceptHeader = headers['Accept'] || headers['accept'];
       if (acceptHeader === CONTENT_TYPES.XML) {

src/models/orchestrator/jobs.models.ts

@@ -1,5 +1,6 @@
-import { JobGetAllOptions, RawJobGetResponse } from './jobs.types';
+import { JobGetAllOptions, RawJobGetResponse, JobStopOptions, JobStopData } from './jobs.types';
 import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '../../utils/pagination';
+import { OperationResponse } from '../common/types';
 
 // Combined type for job data with methods
 export type JobGetResponse = RawJobGetResponse & JobMethods;
@@ -100,6 +101,43 @@ export interface JobServiceModel {
    * ```
    */
   getOutput(jobKey: string, folderId: number): Promise<Record<string, unknown> | null>;
+
+  /**
+   * Stops one or more jobs by their UUID keys.
+   *
+   * Resolves the provided job UUID keys to integer IDs, then sends a stop request to the Orchestrator.
+   * Keys are processed in chunks of 50 to avoid URL length limits. Throws if any keys cannot be resolved.
+   *
+   * @param jobKeys - Array of job UUID keys to stop (e.g., from {@link JobGetResponse}.key)
+   * @param folderId - The folder ID where the jobs reside (required)
+   * @param options - Optional {@link JobStopOptions} including stop strategy
+   * @returns Promise resolving to an {@link OperationResponse}<{@link JobStopData}> with the resolved job IDs
+   *
+   * @example
+   * ```typescript
+   * import { Jobs } from '@uipath/uipath-typescript/jobs';
+   *
+   * const jobs = new Jobs(sdk);
+   *
+   * // Stop a single job with default soft stop
+   * const result = await jobs.stop(
+   *   ['c80c3b30-f010-4eb8-82d4-b67bc615e137'],
+   *   123
+   * );
+   *
+   * // Force-kill multiple jobs
+   * const killResult = await jobs.stop(
+   *   ['c80c3b30-f010-4eb8-82d4-b67bc615e137', '24ef1040-454d-4184-b994-c641ee32318d'],
+   *   123,
+   *   { strategy: StopStrategy.Kill }
+   * );
+   * ```
+   */
+  stop(
+    jobKeys: string[],
+    folderId: number,
+    options?: JobStopOptions
+  ): Promise<OperationResponse<JobStopData>>;
 }
 
 /**

src/models/orchestrator/jobs.types.ts

@@ -166,3 +166,23 @@ export type JobGetAllOptions = RequestOptions & PaginationOptions & {
   folderId?: number;
 }
 
+/**
+ * Options for stopping jobs
+ */
+export interface JobStopOptions {
+  /**
+   * The stop strategy to use.
+   * - `SoftStop` — sends a cancellation request and waits for the job to finish gracefully
+   * - `Kill` — forcefully terminates the job immediately
+   * @default StopStrategy.SoftStop
+   */
+  strategy?: StopStrategy;
+}
+
+/**
+ * Data returned from a stop operation
+ */
+export interface JobStopData {
+  /** The resolved integer IDs of the jobs that were stopped */
+  jobIds: number[];
+}

src/services/orchestrator/jobs/jobs.ts

@@ -1,5 +1,5 @@
 import { FolderScopedService } from '../../folder-scoped';
-import { RawJobGetResponse, JobGetAllOptions } from '../../../models/orchestrator/jobs.types';
+import { RawJobGetResponse, JobGetAllOptions, JobStopOptions, JobStopData } from '../../../models/orchestrator/jobs.types';
 import { RawJobOutputFields } from '../../../models/orchestrator/jobs.internal-types';
 import { JobServiceModel, JobGetResponse, createJobWithMethods } from '../../../models/orchestrator/jobs.models';
 import { pascalToCamelCaseKeys, transformData } from '../../../utils/transform';
@@ -11,12 +11,17 @@ import { ValidationError, ServerError } from '../../../core/errors';
 import { ErrorFactory } from '../../../core/errors/error-factory';
 import { errorResponseParser } from '../../../core/errors/parser';
 import { createHeaders } from '../../../utils/http/headers';
-import { FOLDER_ID } from '../../../utils/constants/headers';
+import { FOLDER_ID, RESPONSE_TYPES } from '../../../utils/constants/headers';
 import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '../../../utils/pagination';
 import { PaginationHelpers } from '../../../utils/pagination/helpers';
 import { PaginationType } from '../../../utils/pagination/internal-types';
 import { track } from '../../../core/telemetry';
 import type { IUiPath } from '../../../core/types';
+import { OperationResponse, CollectionResponse } from '../../../models/common/types';
+import { StopStrategy } from '../../../models/orchestrator/processes.types';
+
+/** Maximum number of job keys to resolve in a single OData filter query */
+const JOB_KEY_RESOLUTION_CHUNK_SIZE = 50;
 
 /**
  * Service for interacting with UiPath Orchestrator Jobs API
@@ -160,6 +165,37 @@ export class JobService extends FolderScopedService implements JobServiceModel {
     return null;
   }
 
+  /**
+   * Stops one or more jobs by their UUID keys.
+   *
+   * Resolves job UUID keys to integer IDs, then calls the StopJobs OData action.
+   * Keys are resolved in chunks of 50 to avoid URL length limits.
+   *
+   * @param jobKeys - Array of job UUID keys to stop
+   * @param folderId - The folder ID where the jobs reside (required by the API)
+   * @param options - Optional stop options including strategy
+   * @returns Promise resolving to an OperationResponse with the resolved job IDs
+   */
+  @track('Jobs.Stop')
+  async stop(
+    jobKeys: string[],
+    folderId: number,
+    options?: JobStopOptions
+  ): Promise<OperationResponse<JobStopData>> {
+    if (jobKeys.length === 0) {
+      return { success: true, data: { jobIds: [] } };
+    }
+
+    const headers = createHeaders({ [FOLDER_ID]: folderId });
+    const strategy = options?.strategy ?? StopStrategy.SoftStop;
+
+    const jobIds = await this.resolveJobKeys(jobKeys, headers);
+
+    await this.stopJobsByIds(jobIds, strategy, headers);
+
+    return { success: true, data: { jobIds } };
+  }
+
   /**
    * Fetches a job by its Key (GUID) using the GetByKey endpoint.
    * Only selects fields needed for output extraction.
@@ -222,4 +258,56 @@ export class JobService extends FolderScopedService implements JobServiceModel {
       throw new ServerError({ message: 'Failed to parse job output file as JSON' });
     }
   }
+
+  /**
+   * Resolves job UUID keys to integer IDs via OData filter queries.
+   * Chunks keys into batches to avoid URL length limits.
+   */
+  private async resolveJobKeys(
+    jobKeys: string[],
+    headers: Record<string, string>
+  ): Promise<number[]> {
+    const uniqueKeys = [...new Set(jobKeys)];
+    const keyToIdMap = new Map<string, number>();
+
+    for (let i = 0; i < uniqueKeys.length; i += JOB_KEY_RESOLUTION_CHUNK_SIZE) {
+      const chunk = uniqueKeys.slice(i, i + JOB_KEY_RESOLUTION_CHUNK_SIZE);
+      const filterValues = chunk.map((key) => `'${key}'`).join(',');
+      const filter = `Key in (${filterValues})`;
+
+      const response = await this.get<CollectionResponse<{ Key: string; Id: number }>>(
+        JOB_ENDPOINTS.GET_ALL,
+        {
+          params: { $filter: filter, $select: 'Id,Key' },
+          headers,
+        }
+      );
+
+      for (const job of response.data.value) {
+        keyToIdMap.set(job.Key, job.Id);
+      }
+    }
+
+    const missingKeys = uniqueKeys.filter((key) => !keyToIdMap.has(key));
+    if (missingKeys.length > 0) {
+      throw new Error(`Jobs not found for keys: ${missingKeys.join(', ')}`);
+    }
+
+    return jobKeys.map((key) => keyToIdMap.get(key)!);
+  }
+
+  /**
+   * Calls the StopJobs OData action with resolved integer IDs.
+   */
+  private async stopJobsByIds(
+    jobIds: number[],
+    strategy: StopStrategy,
+    headers: Record<string, string>
+  ): Promise<void> {
+    await this.post(
+      JOB_ENDPOINTS.STOP,
+      { jobIds, strategy },
+      { headers, responseType: RESPONSE_TYPES.TEXT }
+    );
+  }
 }

src/utils/constants/endpoints/orchestrator.ts

@@ -60,6 +60,7 @@ export const QUEUE_ENDPOINTS = {
 export const JOB_ENDPOINTS = {
   GET_ALL: `${ORCHESTRATOR_BASE}/odata/Jobs`,
   GET_BY_KEY: (identifier: string) => `${ORCHESTRATOR_BASE}/odata/Jobs/UiPath.Server.Configuration.OData.GetByKey(identifier=${identifier})`,
+  STOP: `${ORCHESTRATOR_BASE}/odata/Jobs/UiPath.Server.Configuration.OData.StopJobs`,
 } as const;
 
 /**

tests/integration/shared/orchestrator/jobs.integration.test.ts

@@ -91,6 +91,56 @@ describe.each(modes)('Orchestrator Jobs - Integration Tests [%s]', (mode) => {
     });
   });
 
+  describe('stop', () => {
+    it('should stop a running job with soft stop strategy', async () => {
+      const { jobs, folderId } = getJobsService();
+
+      if (!folderId) {
+        console.warn('INTEGRATION_TEST_FOLDER_ID not configured, skipping stop test.');
+        return;
+      }
+
+      // Find a running job to stop
+      const runningJobs = await jobs.getAll({
+        folderId,
+        filter: "State eq 'Running'",
+        pageSize: 1,
+      });
+
+      if (runningJobs.items.length === 0) {
+        console.warn('No running jobs available to test stop. Skipping.');
+        return;
+      }
+
+      const jobKey = runningJobs.items[0].key;
+
+      const result = await jobs.stop([jobKey], folderId);
+
+      expect(result).toBeDefined();
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+      expect(result.data.jobIds).toBeDefined();
+      expect(Array.isArray(result.data.jobIds)).toBe(true);
+      expect(result.data.jobIds.length).toBe(1);
+      expect(typeof result.data.jobIds[0]).toBe('number');
+    });
+
+    it('should return empty result when called with empty array', async () => {
+      const { jobs, folderId } = getJobsService();
+
+      if (!folderId) {
+        console.warn('INTEGRATION_TEST_FOLDER_ID not configured, skipping stop test.');
+        return;
+      }
+
+      const result = await jobs.stop([], folderId);
+
+      expect(result).toBeDefined();
+      expect(result.success).toBe(true);
+      expect(result.data.jobIds).toEqual([]);
+    });
+  });
+
   describe('Job structure validation', () => {
     it('should have expected fields in job objects', async () => {
       const { jobs, folderId } = getJobsService();