@uipath/uipath-typescript 1.3.9 → 1.3.10

package/dist/maestro-processes/index.cjs

@@ -1050,14 +1050,25 @@ class ApiClient {
             if (!text) {
                 return undefined;
             }
-            return JSON.parse(text);
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError) {
+                    throw new ServerError({
+                        message: `Server returned non-JSON response (${response.status} ${response.url}): ${error.message}`,
+                        statusCode: response.status,
+                    });
+                }
+                throw error;
+            }
         }
         catch (error) {
             // If it's already one of our errors, re-throw it
             if (error.type && error.type.includes('Error')) {
                 throw error;
             }
-            // Otherwise, it's likely a network error
+            // Otherwise, it's a genuine network/fetch failure
             throw ErrorFactory.createNetworkError(error);
         }
     }
@@ -1424,9 +1435,9 @@ class PaginationHelpers {
      * @returns Promise resolving to a paginated result
      */
     static async getAllPaginated(params) {
-        const { serviceAccess, getEndpoint, folderId, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         const endpoint = getEndpoint(folderId);
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         const paginatedResponse = await serviceAccess.requestWithPagination(method, endpoint, paginationParams, {
             headers,
             params: additionalParams,
@@ -1454,13 +1465,13 @@ class PaginationHelpers {
      * @returns Promise resolving to an object with data and totalCount
      */
     static async getAllNonPaginated(params) {
-        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         // Set default field names
         const itemsField = options.itemsField || DEFAULT_ITEMS_FIELD;
         const totalCountField = options.totalCountField || DEFAULT_TOTAL_COUNT_FIELD;
         // Determine endpoint and headers based on folderId
         const endpoint = folderId ? getByFolderEndpoint : getAllEndpoint;
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         // Make the API call based on method
         let response;
         if (method === HTTP_METHODS.POST) {
@@ -1519,6 +1530,7 @@ class PaginationHelpers {
                 serviceAccess: config.serviceAccess,
                 getEndpoint: config.getEndpoint,
                 folderId,
+                headers: config.headers,
                 paginationParams: cursor ? { cursor, pageSize } : jumpToPage ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
                 transformFn: config.transformFn,
@@ -1536,6 +1548,7 @@ class PaginationHelpers {
             getAllEndpoint: config.getEndpoint(),
             getByFolderEndpoint: byFolderEndpoint,
             folderId,
+            headers: config.headers,
             additionalParams: prefixedOptions,
             transformFn: config.transformFn,
             method: config.method,

package/dist/maestro-processes/index.mjs

@@ -1048,14 +1048,25 @@ class ApiClient {
             if (!text) {
                 return undefined;
             }
-            return JSON.parse(text);
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError) {
+                    throw new ServerError({
+                        message: `Server returned non-JSON response (${response.status} ${response.url}): ${error.message}`,
+                        statusCode: response.status,
+                    });
+                }
+                throw error;
+            }
         }
         catch (error) {
             // If it's already one of our errors, re-throw it
             if (error.type && error.type.includes('Error')) {
                 throw error;
             }
-            // Otherwise, it's likely a network error
+            // Otherwise, it's a genuine network/fetch failure
             throw ErrorFactory.createNetworkError(error);
         }
     }
@@ -1422,9 +1433,9 @@ class PaginationHelpers {
      * @returns Promise resolving to a paginated result
      */
     static async getAllPaginated(params) {
-        const { serviceAccess, getEndpoint, folderId, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         const endpoint = getEndpoint(folderId);
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         const paginatedResponse = await serviceAccess.requestWithPagination(method, endpoint, paginationParams, {
             headers,
             params: additionalParams,
@@ -1452,13 +1463,13 @@ class PaginationHelpers {
      * @returns Promise resolving to an object with data and totalCount
      */
     static async getAllNonPaginated(params) {
-        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         // Set default field names
         const itemsField = options.itemsField || DEFAULT_ITEMS_FIELD;
         const totalCountField = options.totalCountField || DEFAULT_TOTAL_COUNT_FIELD;
         // Determine endpoint and headers based on folderId
         const endpoint = folderId ? getByFolderEndpoint : getAllEndpoint;
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         // Make the API call based on method
         let response;
         if (method === HTTP_METHODS.POST) {
@@ -1517,6 +1528,7 @@ class PaginationHelpers {
                 serviceAccess: config.serviceAccess,
                 getEndpoint: config.getEndpoint,
                 folderId,
+                headers: config.headers,
                 paginationParams: cursor ? { cursor, pageSize } : jumpToPage ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
                 transformFn: config.transformFn,
@@ -1534,6 +1546,7 @@ class PaginationHelpers {
             getAllEndpoint: config.getEndpoint(),
             getByFolderEndpoint: byFolderEndpoint,
             folderId,
+            headers: config.headers,
             additionalParams: prefixedOptions,
             transformFn: config.transformFn,
             method: config.method,

package/dist/processes/index.cjs

@@ -613,14 +613,25 @@ class ApiClient {
             if (!text) {
                 return undefined;
             }
-            return JSON.parse(text);
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError) {
+                    throw new ServerError({
+                        message: `Server returned non-JSON response (${response.status} ${response.url}): ${error.message}`,
+                        statusCode: response.status,
+                    });
+                }
+                throw error;
+            }
         }
         catch (error) {
             // If it's already one of our errors, re-throw it
             if (error.type && error.type.includes('Error')) {
                 throw error;
             }
-            // Otherwise, it's likely a network error
+            // Otherwise, it's a genuine network/fetch failure
             throw ErrorFactory.createNetworkError(error);
         }
     }
@@ -1284,9 +1295,9 @@ class PaginationHelpers {
      * @returns Promise resolving to a paginated result
      */
     static async getAllPaginated(params) {
-        const { serviceAccess, getEndpoint, folderId, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         const endpoint = getEndpoint(folderId);
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         const paginatedResponse = await serviceAccess.requestWithPagination(method, endpoint, paginationParams, {
             headers,
             params: additionalParams,
@@ -1314,13 +1325,13 @@ class PaginationHelpers {
      * @returns Promise resolving to an object with data and totalCount
      */
     static async getAllNonPaginated(params) {
-        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         // Set default field names
         const itemsField = options.itemsField || DEFAULT_ITEMS_FIELD;
         const totalCountField = options.totalCountField || DEFAULT_TOTAL_COUNT_FIELD;
         // Determine endpoint and headers based on folderId
         const endpoint = folderId ? getByFolderEndpoint : getAllEndpoint;
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         // Make the API call based on method
         let response;
         if (method === HTTP_METHODS.POST) {
@@ -1379,6 +1390,7 @@ class PaginationHelpers {
                 serviceAccess: config.serviceAccess,
                 getEndpoint: config.getEndpoint,
                 folderId,
+                headers: config.headers,
                 paginationParams: cursor ? { cursor, pageSize } : jumpToPage ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
                 transformFn: config.transformFn,
@@ -1396,6 +1408,7 @@ class PaginationHelpers {
             getAllEndpoint: config.getEndpoint(),
             getByFolderEndpoint: byFolderEndpoint,
             folderId,
+            headers: config.headers,
             additionalParams: prefixedOptions,
             transformFn: config.transformFn,
             method: config.method,
@@ -2053,33 +2066,32 @@ class ProcessService extends FolderScopedService {
             }
         }, options);
     }
-    /**
-     * Starts a process execution (job)
-     *
-     * @param request - Process start request body
-     * @param folderId - Required folder ID
-     * @param options - Optional query parameters
-     * @returns Promise resolving to the created jobs
-     *
-     * @example
-     * ```typescript
-     * import { Processes } from '@uipath/uipath-typescript/processes';
-     *
-     * const processes = new Processes(sdk);
-     *
-     * // Start a process by process key
-     * const jobs = await processes.start({
-     *   processKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-     * }, 123); // folderId is required
-     *
-     * // Start a process by name with specific robots
-     * const jobs = await processes.start({
-     *   processName: "MyProcess"
-     * }, 123); // folderId is required
-     * ```
-     */
-    async start(request, folderId, options = {}) {
-        const headers = createHeaders({ [FOLDER_ID]: folderId });
+    async start(request, optionsOrFolderId, legacyOptions) {
+        // Normalize the two overload forms into a single internal shape.
+        let folderId;
+        let folderKey;
+        let folderPath;
+        let queryOptions;
+        if (typeof optionsOrFolderId === 'number') {
+            // Deprecated positional form: start(request, folderId, options?)
+            folderId = optionsOrFolderId;
+            queryOptions = legacyOptions ?? {};
+        }
+        else {
+            // Preferred form: start(request, options?)
+            const { folderId: fid, folderKey: fkey, folderPath: fpath, ...rest } = optionsOrFolderId ?? {};
+            folderId = fid;
+            folderKey = fkey;
+            folderPath = fpath;
+            queryOptions = rest;
+        }
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: 'processes.start',
+            fallbackFolderKey: this.config.folderKey,
+        });
         // Transform SDK field names to API field names (e.g., processKey → releaseKey)
         const apiRequest = transformRequest(request, ProcessMap);
         // Create the request object according to API spec
@@ -2087,8 +2099,8 @@ class ProcessService extends FolderScopedService {
             startInfo: apiRequest
         };
         // Prefix all query parameter keys with '$' for OData
-        const keysToPrefix = Object.keys(options);
-        const apiOptions = addPrefixToKeys(options, ODATA_PREFIX, keysToPrefix);
+        const keysToPrefix = Object.keys(queryOptions);
+        const apiOptions = addPrefixToKeys(queryOptions, ODATA_PREFIX, keysToPrefix);
         const response = await this.post(PROCESS_ENDPOINTS.START_PROCESS, requestBody, {
             params: apiOptions,
             headers

package/dist/processes/index.d.ts

@@ -744,6 +744,17 @@ interface ProcessGetByIdOptions extends BaseOptions {
  */
 interface ProcessGetByNameOptions extends FolderScopedOptions {
 }
+/**
+ * Options for starting a process. Combines folder scoping
+ * (`folderId` / `folderKey` / `folderPath`) with the OData query options
+ * (`expand`, `select`, `filter`, `orderby`) accepted by the start endpoint.
+ *
+ * Folder scoping is optional in the type — the SDK falls back to the
+ * init-time folderKey (e.g. `<meta name="uipath:folder-key">` in coded-app
+ * deployments). A `ValidationError` is raised when neither is provided.
+ */
+interface ProcessStartOptions extends FolderScopedOptions, RequestOptions {
+}
 
 /**
  * Service for managing and executing UiPath Automation Processes.
@@ -840,26 +851,45 @@ interface ProcessServiceModel {
      */
     getByName(name: string, options?: ProcessGetByNameOptions): Promise<ProcessGetResponse>;
     /**
-     * Starts a process with the specified configuration
+     * Starts a process with the specified configuration.
+     *
+     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
+     * inside the options.
      *
      * @param request - Process start configuration
-     * @param folderId - Required folder ID
-     * @param options - Optional request options
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional query parameters (`expand`, `select`, `filter`, `orderby`)
      * @returns Promise resolving to array of started process instances
      * {@link ProcessStartResponse}
      * @example
      * ```typescript
-     * // Start a process by process key
-     * const result = await processes.start({
-     *   processKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-     * }, <folderId>); // folderId is required
-     *
-     * // Start a process by name with specific robots
-     * const result = await processes.start({
-     *   processName: "MyProcess"
-     * }, <folderId>); // folderId is required
+     * // By folder ID
+     * await processes.start({ processKey: '<processKey>' }, { folderId: <folderId> });
+     *
+     * // By folder key (GUID)
+     * await processes.start({ processKey: '<processKey>' }, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await processes.start({ processKey: '<processKey>' }, { folderPath: 'Shared/Finance' });
+     *
+     * // Start by process name (instead of processKey)
+     * await processes.start({ processName: 'MyProcess' }, { folderId: <folderId> });
+     *
+     * // With additional options
+     * await processes.start({ processKey: '<processKey>' }, { folderId: <folderId>, expand: 'Robot' });
      * ```
      */
+    start(request: ProcessStartRequest, options?: ProcessStartOptions): Promise<ProcessStartResponse[]>;
+    /**
+     * Starts a process — positional `folderId` form.
+     *
+     * @deprecated Use the options-object form: `start(request, { folderId })`. See {@link ProcessStartOptions} for the supported options.
+     *
+     * @param request - Process start configuration
+     * @param folderId - Required folder ID (numeric)
+     * @param options - Optional request options
+     * @returns Promise resolving to array of started process instances
+     * {@link ProcessStartResponse}
+     */
     start(request: ProcessStartRequest, folderId: number, options?: RequestOptions): Promise<ProcessStartResponse[]>;
 }
 
@@ -913,12 +943,15 @@ declare class ProcessService extends FolderScopedService implements ProcessServi
      */
     getAll<T extends ProcessGetAllOptions = ProcessGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<ProcessGetResponse> : NonPaginatedResponse<ProcessGetResponse>>;
     /**
-     * Starts a process execution (job)
+     * Starts a process with the specified configuration.
      *
-     * @param request - Process start request body
-     * @param folderId - Required folder ID
-     * @param options - Optional query parameters
-     * @returns Promise resolving to the created jobs
+     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
+     * inside the options.
+     *
+     * @param request - Process start configuration
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional query parameters (`expand`, `select`, `filter`, `orderby`)
+     * @returns Promise resolving to array of started process instances
+     * {@link ProcessStartResponse}
      *
      * @example
      * ```typescript
@@ -926,17 +959,34 @@ declare class ProcessService extends FolderScopedService implements ProcessServi
      *
      * const processes = new Processes(sdk);
      *
-     * // Start a process by process key
-     * const jobs = await processes.start({
-     *   processKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-     * }, 123); // folderId is required
+     * // By folder ID
+     * await processes.start({ processKey: '<processKey>' }, { folderId: <folderId> });
      *
-     * // Start a process by name with specific robots
-     * const jobs = await processes.start({
-     *   processName: "MyProcess"
-     * }, 123); // folderId is required
+     * // By folder key (GUID)
+     * await processes.start({ processKey: '<processKey>' }, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await processes.start({ processKey: '<processKey>' }, { folderPath: 'Shared/Finance' });
+     *
+     * // Start by process name (instead of processKey)
+     * await processes.start({ processName: 'MyProcess' }, { folderId: <folderId> });
+     *
+     * // With additional options
+     * await processes.start({ processKey: '<processKey>' }, { folderId: <folderId>, expand: 'Robot' });
      * ```
      */
+    start(request: ProcessStartRequest, options?: ProcessStartOptions): Promise<ProcessStartResponse[]>;
+    /**
+     * Starts a process — positional `folderId` form.
+     *
+     * @deprecated Use the options-object form: `start(request, { folderId })`. See {@link ProcessStartOptions} for the supported options.
+     *
+     * @param request - Process start configuration
+     * @param folderId - Required folder ID (numeric)
+     * @param options - Optional request options
+     * @returns Promise resolving to array of started process instances
+     * {@link ProcessStartResponse}
+     */
     start(request: ProcessStartRequest, folderId: number, options?: RequestOptions): Promise<ProcessStartResponse[]>;
     /**
      * Gets a single process by ID
@@ -987,4 +1037,4 @@ declare class ProcessService extends FolderScopedService implements ProcessServi
 }
 
 export { JobPriority, JobSourceType, JobType, PackageSourceType, PackageType, ProcessService, ProcessService as Processes, RemoteControlAccess, RobotSize, RuntimeType, StartStrategy, StopStrategy, TargetFramework };
-export type { ArgumentMetadata, BaseProcessStartRequest, FolderProperties, JobAttachment, JobError, Machine, ProcessGetAllOptions, ProcessGetByIdOptions, ProcessGetByNameOptions, ProcessGetResponse, ProcessProperties, ProcessServiceModel, ProcessStartRequest, ProcessStartRequestWithKey, ProcessStartRequestWithName, ProcessStartResponse, RobotMetadata };
+export type { ArgumentMetadata, BaseProcessStartRequest, FolderProperties, JobAttachment, JobError, Machine, ProcessGetAllOptions, ProcessGetByIdOptions, ProcessGetByNameOptions, ProcessGetResponse, ProcessProperties, ProcessServiceModel, ProcessStartOptions, ProcessStartRequest, ProcessStartRequestWithKey, ProcessStartRequestWithName, ProcessStartResponse, RobotMetadata };

package/dist/processes/index.mjs

@@ -611,14 +611,25 @@ class ApiClient {
             if (!text) {
                 return undefined;
             }
-            return JSON.parse(text);
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError) {
+                    throw new ServerError({
+                        message: `Server returned non-JSON response (${response.status} ${response.url}): ${error.message}`,
+                        statusCode: response.status,
+                    });
+                }
+                throw error;
+            }
         }
         catch (error) {
             // If it's already one of our errors, re-throw it
             if (error.type && error.type.includes('Error')) {
                 throw error;
             }
-            // Otherwise, it's likely a network error
+            // Otherwise, it's a genuine network/fetch failure
             throw ErrorFactory.createNetworkError(error);
         }
     }
@@ -1282,9 +1293,9 @@ class PaginationHelpers {
      * @returns Promise resolving to a paginated result
      */
     static async getAllPaginated(params) {
-        const { serviceAccess, getEndpoint, folderId, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         const endpoint = getEndpoint(folderId);
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         const paginatedResponse = await serviceAccess.requestWithPagination(method, endpoint, paginationParams, {
             headers,
             params: additionalParams,
@@ -1312,13 +1323,13 @@ class PaginationHelpers {
      * @returns Promise resolving to an object with data and totalCount
      */
     static async getAllNonPaginated(params) {
-        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         // Set default field names
         const itemsField = options.itemsField || DEFAULT_ITEMS_FIELD;
         const totalCountField = options.totalCountField || DEFAULT_TOTAL_COUNT_FIELD;
         // Determine endpoint and headers based on folderId
         const endpoint = folderId ? getByFolderEndpoint : getAllEndpoint;
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         // Make the API call based on method
         let response;
         if (method === HTTP_METHODS.POST) {
@@ -1377,6 +1388,7 @@ class PaginationHelpers {
                 serviceAccess: config.serviceAccess,
                 getEndpoint: config.getEndpoint,
                 folderId,
+                headers: config.headers,
                 paginationParams: cursor ? { cursor, pageSize } : jumpToPage ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
                 transformFn: config.transformFn,
@@ -1394,6 +1406,7 @@ class PaginationHelpers {
             getAllEndpoint: config.getEndpoint(),
             getByFolderEndpoint: byFolderEndpoint,
             folderId,
+            headers: config.headers,
             additionalParams: prefixedOptions,
             transformFn: config.transformFn,
             method: config.method,
@@ -2051,33 +2064,32 @@ class ProcessService extends FolderScopedService {
             }
         }, options);
     }
-    /**
-     * Starts a process execution (job)
-     *
-     * @param request - Process start request body
-     * @param folderId - Required folder ID
-     * @param options - Optional query parameters
-     * @returns Promise resolving to the created jobs
-     *
-     * @example
-     * ```typescript
-     * import { Processes } from '@uipath/uipath-typescript/processes';
-     *
-     * const processes = new Processes(sdk);
-     *
-     * // Start a process by process key
-     * const jobs = await processes.start({
-     *   processKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-     * }, 123); // folderId is required
-     *
-     * // Start a process by name with specific robots
-     * const jobs = await processes.start({
-     *   processName: "MyProcess"
-     * }, 123); // folderId is required
-     * ```
-     */
-    async start(request, folderId, options = {}) {
-        const headers = createHeaders({ [FOLDER_ID]: folderId });
+    async start(request, optionsOrFolderId, legacyOptions) {
+        // Normalize the two overload forms into a single internal shape.
+        let folderId;
+        let folderKey;
+        let folderPath;
+        let queryOptions;
+        if (typeof optionsOrFolderId === 'number') {
+            // Deprecated positional form: start(request, folderId, options?)
+            folderId = optionsOrFolderId;
+            queryOptions = legacyOptions ?? {};
+        }
+        else {
+            // Preferred form: start(request, options?)
+            const { folderId: fid, folderKey: fkey, folderPath: fpath, ...rest } = optionsOrFolderId ?? {};
+            folderId = fid;
+            folderKey = fkey;
+            folderPath = fpath;
+            queryOptions = rest;
+        }
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: 'processes.start',
+            fallbackFolderKey: this.config.folderKey,
+        });
         // Transform SDK field names to API field names (e.g., processKey → releaseKey)
         const apiRequest = transformRequest(request, ProcessMap);
         // Create the request object according to API spec
@@ -2085,8 +2097,8 @@ class ProcessService extends FolderScopedService {
             startInfo: apiRequest
         };
         // Prefix all query parameter keys with '$' for OData
-        const keysToPrefix = Object.keys(options);
-        const apiOptions = addPrefixToKeys(options, ODATA_PREFIX, keysToPrefix);
+        const keysToPrefix = Object.keys(queryOptions);
+        const apiOptions = addPrefixToKeys(queryOptions, ODATA_PREFIX, keysToPrefix);
         const response = await this.post(PROCESS_ENDPOINTS.START_PROCESS, requestBody, {
             params: apiOptions,
             headers

package/dist/queues/index.cjs

@@ -613,14 +613,25 @@ class ApiClient {
             if (!text) {
                 return undefined;
             }
-            return JSON.parse(text);
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError) {
+                    throw new ServerError({
+                        message: `Server returned non-JSON response (${response.status} ${response.url}): ${error.message}`,
+                        statusCode: response.status,
+                    });
+                }
+                throw error;
+            }
         }
         catch (error) {
             // If it's already one of our errors, re-throw it
             if (error.type && error.type.includes('Error')) {
                 throw error;
             }
-            // Otherwise, it's likely a network error
+            // Otherwise, it's a genuine network/fetch failure
             throw ErrorFactory.createNetworkError(error);
         }
     }
@@ -1221,9 +1232,9 @@ class PaginationHelpers {
      * @returns Promise resolving to a paginated result
      */
     static async getAllPaginated(params) {
-        const { serviceAccess, getEndpoint, folderId, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         const endpoint = getEndpoint(folderId);
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         const paginatedResponse = await serviceAccess.requestWithPagination(method, endpoint, paginationParams, {
             headers,
             params: additionalParams,
@@ -1251,13 +1262,13 @@ class PaginationHelpers {
      * @returns Promise resolving to an object with data and totalCount
      */
     static async getAllNonPaginated(params) {
-        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         // Set default field names
         const itemsField = options.itemsField || DEFAULT_ITEMS_FIELD;
         const totalCountField = options.totalCountField || DEFAULT_TOTAL_COUNT_FIELD;
         // Determine endpoint and headers based on folderId
         const endpoint = folderId ? getByFolderEndpoint : getAllEndpoint;
-        const headers = folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {};
+        const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
         // Make the API call based on method
         let response;
         if (method === HTTP_METHODS.POST) {
@@ -1316,6 +1327,7 @@ class PaginationHelpers {
                 serviceAccess: config.serviceAccess,
                 getEndpoint: config.getEndpoint,
                 folderId,
+                headers: config.headers,
                 paginationParams: cursor ? { cursor, pageSize } : jumpToPage ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
                 transformFn: config.transformFn,
@@ -1333,6 +1345,7 @@ class PaginationHelpers {
             getAllEndpoint: config.getEndpoint(),
             getByFolderEndpoint: byFolderEndpoint,
             folderId,
+            headers: config.headers,
             additionalParams: prefixedOptions,
             transformFn: config.transformFn,
             method: config.method,