fix: address comments

Author: ninja-shreyash

agent_docs/rules.md

@@ -28,6 +28,7 @@ Every new method must also have an integration test in `tests/integration/shared
 - Use `registerResource()` from `tests/integration/utils/cleanup.ts` for cleanup tracking
 - Use `generateRandomString()` from `tests/integration/utils/helpers.ts` for unique test data
 - Tests run in both `v0` and `v1` init modes via `describe.each(modes)` — **only if the service is registered in both modes in `unified-setup.ts`**. New services that only support `v1` init should use `['v1']` only.
+- **Always `throw new Error()` when test preconditions are not met** — whether it's missing config (e.g., no `folderId`) or missing test data (e.g., no running jobs). Never use `console.warn()` + `return` to silently skip — silent skips hide unrunnable tests and make CI green when tests aren't actually exercised.
 - **NEVER** write redundant integration tests — each test must cover a distinct code path, error scenario, or response shape aspect.
 - **Include a transform validation test** for new methods with a transform pipeline. This test should verify: (a) transformed camelCase fields exist and have values (`job.createdTime`, `job.processName`), AND (b) original PascalCase API fields are absent (`(job as any).CreationTime` is `undefined`, `(job as any).ReleaseName` is `undefined`). This is a separate test from the basic "should retrieve by ID" test — it validates the SDK transform layer against the live API. Note: existing integration tests don't yet follow this pattern, but unit tests do (Assets, Queues, ChoiceSets). Extending it to integration tests catches mismatches between the Swagger spec assumptions and the live API response.
 

docs/oauth-scopes.md

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

src/core/http/api-client.ts

@@ -103,7 +103,7 @@ export class ApiClient {
         throw ErrorFactory.createFromHttpStatus(response.status, errorInfo);
       }
 
-      if (response.status === 204) {
+      if (response.status === 204 || response.headers.get('content-length') === '0') {
         return undefined as T;
       }
 

src/models/orchestrator/jobs.constants.ts

@@ -1,3 +1,6 @@
+/** Maximum number of job keys to resolve in a single OData filter query (matches Python SDK) */
+export const JOB_KEY_RESOLUTION_CHUNK_SIZE = 50;
+
 /**
  * Maps fields for Job entities to ensure consistent naming
  * Semantic renames only — case conversion handled by pascalToCamelCaseKeys()

src/models/orchestrator/jobs.models.ts

@@ -134,8 +134,7 @@ export interface JobServiceModel {
   /**
    * 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.
+   * Sends a stop request for the specified jobs to the Orchestrator. 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)
@@ -192,6 +191,26 @@ export interface JobMethods {
    * ```
    */
   getOutput(): Promise<Record<string, unknown> | null>;
+
+  /**
+   * Stops this job.
+   *
+   * Sends a stop request for this job to the Orchestrator.
+   *
+   * @param options - Optional {@link JobStopOptions} including stop strategy (defaults to SoftStop)
+   * @returns Promise resolving to an {@link OperationResponse}<{@link JobStopData}> with the resolved job ID
+   *
+   * @example
+   * ```typescript
+   * const allJobs = await jobs.getAll({ folderId: <folderId> });
+   * const runningJob = allJobs.items.find(j => j.state === JobState.Running);
+   *
+   * if (runningJob) {
+   *   const result = await runningJob.stop();
+   * }
+   * ```
+   */
+  stop(options?: JobStopOptions): Promise<OperationResponse<JobStopData>>;
 }
 
 /**
@@ -208,6 +227,11 @@ function createJobMethods(jobData: RawJobGetResponse, service: JobServiceModel):
       if (!jobData.folderId) throw new Error('Job folderId is undefined');
       return service.getOutput(jobData.key, jobData.folderId);
     },
+    async stop(options?: JobStopOptions): Promise<OperationResponse<JobStopData>> {
+      if (!jobData.key) throw new Error('Job key is undefined');
+      if (!jobData.folderId) throw new Error('Job folderId is undefined');
+      return service.stop([jobData.key], jobData.folderId, options);
+    },
   };
 }
 

src/models/orchestrator/jobs.types.ts

@@ -177,8 +177,8 @@ export interface JobGetByIdOptions extends BaseOptions {}
 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
+   * - `SoftStop` — requests graceful cancellation; the job completes its current activity before stopping
+   * - `Kill` — requests immediate termination of the job
    * @default StopStrategy.SoftStop
    */
   strategy?: StopStrategy;

src/services/orchestrator/jobs/jobs.ts

@@ -4,13 +4,13 @@ import { JobServiceModel, JobGetResponse, createJobWithMethods } from '../../../
 import { addPrefixToKeys, pascalToCamelCaseKeys, transformData } from '../../../utils/transform';
 import { JOB_ENDPOINTS } from '../../../utils/constants/endpoints';
 import { ODATA_PAGINATION, ODATA_OFFSET_PARAMS, ODATA_PREFIX } from '../../../utils/constants/common';
-import { JobMap } from '../../../models/orchestrator/jobs.constants';
+import { JobMap, JOB_KEY_RESOLUTION_CHUNK_SIZE } from '../../../models/orchestrator/jobs.constants';
 import { AttachmentService } from '../attachments/attachments';
 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, RESPONSE_TYPES } from '../../../utils/constants/headers';
+import { FOLDER_ID } from '../../../utils/constants/headers';
 import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '../../../utils/pagination';
 import { PaginationHelpers } from '../../../utils/pagination/helpers';
 import { PaginationType } from '../../../utils/pagination/internal-types';
@@ -19,9 +19,6 @@ 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
  */
@@ -219,8 +216,7 @@ export class JobService extends FolderScopedService implements JobServiceModel {
   /**
    * 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.
+   * Sends a stop request for the specified jobs to the Orchestrator. 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)
@@ -255,6 +251,10 @@ export class JobService extends FolderScopedService implements JobServiceModel {
       return { success: true, data: { jobIds: [] } };
     }
 
+    if (!folderId) {
+      throw new ValidationError({ message: 'folderId is required for stop' });
+    }
+
     const headers = createHeaders({ [FOLDER_ID]: folderId });
     const strategy = options?.strategy ?? StopStrategy.SoftStop;
 
@@ -341,7 +341,7 @@ export class JobService extends FolderScopedService implements JobServiceModel {
       throw new ValidationError({ message: `Jobs not found for keys: ${missingKeys.join(', ')}` });
     }
 
-    return jobKeys.map((key) => keyToIdMap.get(key)!);
+    return uniqueKeys.map((key) => keyToIdMap.get(key)!);
   }
 
   /**
@@ -355,7 +355,7 @@ export class JobService extends FolderScopedService implements JobServiceModel {
     await this.post(
       JOB_ENDPOINTS.STOP,
       { jobIds, strategy },
-      { headers, responseType: RESPONSE_TYPES.TEXT }
+      { headers }
     );
   }
 }

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

@@ -204,8 +204,7 @@ describe.each(modes)('Orchestrator Jobs - Integration Tests [%s]', (mode) => {
       });
 
       if (runningJobs.items.length === 0) {
-        console.warn('No running jobs available to test stop. Skipping.');
-        return;
+        throw new Error('No running jobs available in the test environment to test stop.');
       }
 
       const jobKey = runningJobs.items[0].key;

tests/unit/models/orchestrator/jobs.test.ts

@@ -6,6 +6,7 @@ import {
 import { createBasicJob } from '../../../utils/mocks/jobs';
 import { JOB_TEST_CONSTANTS } from '../../../utils/constants/jobs';
 import { TEST_CONSTANTS } from '../../../utils/constants/common';
+import { StopStrategy } from '../../../../src/models/orchestrator/processes.types';
 
 // ===== TEST SUITE =====
 describe('Job Models', () => {
@@ -16,6 +17,7 @@ describe('Job Models', () => {
       getAll: vi.fn(),
       getById: vi.fn(),
       getOutput: vi.fn(),
+      stop: vi.fn(),
     } as any;
   });
 
@@ -64,5 +66,54 @@ describe('Job Models', () => {
         await expect(job.getOutput()).rejects.toThrow('Job folderId is undefined');
       });
     });
+
+    describe('job.stop()', () => {
+      it('should call service.stop with the job key and folderId', async () => {
+        const mockJobData = createBasicJob();
+        const job = createJobWithMethods(mockJobData, mockService);
+
+        const mockResult = { success: true, data: { jobIds: [JOB_TEST_CONSTANTS.JOB_ID] } };
+        vi.mocked(mockService.stop).mockResolvedValue(mockResult);
+
+        const result = await job.stop();
+
+        expect(mockService.stop).toHaveBeenCalledWith(
+          [JOB_TEST_CONSTANTS.JOB_KEY],
+          TEST_CONSTANTS.FOLDER_ID,
+          undefined
+        );
+        expect(result).toEqual(mockResult);
+      });
+
+      it('should pass options to service.stop', async () => {
+        const mockJobData = createBasicJob();
+        const job = createJobWithMethods(mockJobData, mockService);
+
+        const mockResult = { success: true, data: { jobIds: [JOB_TEST_CONSTANTS.JOB_ID] } };
+        vi.mocked(mockService.stop).mockResolvedValue(mockResult);
+
+        await job.stop({ strategy: StopStrategy.Kill });
+
+        expect(mockService.stop).toHaveBeenCalledWith(
+          [JOB_TEST_CONSTANTS.JOB_KEY],
+          TEST_CONSTANTS.FOLDER_ID,
+          { strategy: StopStrategy.Kill }
+        );
+      });
+
+      it('should throw when job key is undefined', async () => {
+        const mockJobData = createBasicJob({ key: '' as any });
+        const job = createJobWithMethods(mockJobData, mockService);
+
+        await expect(job.stop()).rejects.toThrow('Job key is undefined');
+      });
+
+      it('should throw when job folderId is undefined', async () => {
+        const mockJobData = createBasicJob({ folderId: undefined as any });
+        const job = createJobWithMethods(mockJobData, mockService);
+
+        await expect(job.stop()).rejects.toThrow('Job folderId is undefined');
+      });
+    });
   });
 });

tests/unit/services/orchestrator/jobs.test.ts

@@ -174,6 +174,8 @@ describe('JobService Unit Tests', () => {
 
       expect(transformed.getOutput).toBeDefined();
       expect(typeof transformed.getOutput).toBe('function');
+      expect(transformed.stop).toBeDefined();
+      expect(typeof transformed.stop).toBe('function');
     });
   });
 
@@ -216,14 +218,16 @@ describe('JobService Unit Tests', () => {
       expect((result as any).LastModificationTime).toBeUndefined();
     });
 
-    it('should attach getOutput method to result', async () => {
+    it('should attach bound methods to result', async () => {
       const mockRawJob = createMockRawJob();
       mockApiClient.get.mockResolvedValueOnce(mockRawJob);
 
       const result = await jobService.getById(JOB_TEST_CONSTANTS.JOB_KEY, TEST_CONSTANTS.FOLDER_ID);
 
       expect(result.getOutput).toBeDefined();
       expect(typeof result.getOutput).toBe('function');
+      expect(result.stop).toBeDefined();
+      expect(typeof result.stop).toBe('function');
     });
 
     it('should pass expand and select options with OData prefix', async () => {
@@ -583,7 +587,7 @@ describe('JobService Unit Tests', () => {
       ).rejects.toThrow(JOB_TEST_CONSTANTS.ERROR_JOBS_NOT_FOUND_FOR_KEYS);
     });
 
-    it('should deduplicate job keys for resolution but preserve original order in result', async () => {
+    it('should deduplicate job keys for resolution and return unique IDs', async () => {
       mockApiClient.get.mockResolvedValueOnce({
         value: [{ Key: JOB_TEST_CONSTANTS.JOB_KEY, Id: JOB_TEST_CONSTANTS.JOB_ID }],
       });
@@ -594,10 +598,8 @@ describe('JobService Unit Tests', () => {
         TEST_CONSTANTS.FOLDER_ID
       );
 
-      expect(result.data.jobIds).toEqual([
-        JOB_TEST_CONSTANTS.JOB_ID,
-        JOB_TEST_CONSTANTS.JOB_ID,
-      ]);
+      // Duplicate keys are deduplicated — only one ID returned
+      expect(result.data.jobIds).toEqual([JOB_TEST_CONSTANTS.JOB_ID]);
 
       // Only one resolution call with deduplicated keys
       const filterArg = mockApiClient.get.mock.calls[0][1].params.$filter;
@@ -632,6 +634,12 @@ describe('JobService Unit Tests', () => {
       expect(result.data.jobIds).toEqual(ids);
     });
 
+    it('should throw validation error when folderId is missing', async () => {
+      await expect(
+        jobService.stop([JOB_TEST_CONSTANTS.JOB_KEY], 0)
+      ).rejects.toThrow('folderId is required for stop');
+    });
+
     it('should propagate resolution API errors', async () => {
       const error = createMockError(JOB_TEST_CONSTANTS.ERROR_JOB_NOT_FOUND);
       mockApiClient.get.mockRejectedValueOnce(error);