@uipath/uipath-typescript 1.3.6 → 1.3.8

package/dist/processes/index.cjs

@@ -505,6 +505,8 @@ class ErrorFactory {
     }
 }
 
+const FOLDER_KEY = 'X-UIPATH-FolderKey';
+const FOLDER_PATH_ENCODED = 'X-UIPATH-FolderPath-Encoded';
 const FOLDER_ID = 'X-UIPATH-OrganizationUnitId';
 const TRACEPARENT = 'traceparent';
 const UIPATH_TRACEPARENT_ID = 'x-uipath-traceparent-id';
@@ -651,6 +653,27 @@ var PaginationType;
 /**
  * Collection of utility functions for working with objects
  */
+/**
+ * Resolves a field value from an object, supporting both direct keys (e.g., '@odata.count')
+ * and dot-separated nested paths (e.g., 'pagination.totalCount').
+ * Direct key match takes priority over nested traversal.
+ */
+function resolveNestedField(data, fieldPath) {
+    if (!data) {
+        return undefined;
+    }
+    if (fieldPath in data) {
+        return data[fieldPath];
+    }
+    if (!fieldPath.includes('.')) {
+        return undefined;
+    }
+    let value = data;
+    for (const part of fieldPath.split('.')) {
+        value = value?.[part];
+    }
+    return value;
+}
 /**
  * Filters out undefined values from an object
  * @param obj The source object
@@ -891,6 +914,10 @@ const BUCKET_TOKEN_PARAMS = {
     TOKEN_PARAM: 'continuationToken'
 };
 
+/**
+ * Converts a UTC timestamp string (e.g., "5/8/2026 11:20:17 AM") to ISO 8601 UTC format.
+ * Returns the original value if parsing fails.
+ */
 /**
  * Transforms data by mapping fields according to the provided field mapping
  * @param data The source data to transform
@@ -1308,7 +1335,8 @@ class PaginationHelpers {
         // Extract and transform items from response
         // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N })
         const rawItems = Array.isArray(response.data) ? response.data : response.data?.[itemsField];
-        const totalCount = Array.isArray(response.data) ? undefined : response.data?.[totalCountField];
+        const rawTotalCount = Array.isArray(response.data) ? undefined : resolveNestedField(response.data, totalCountField);
+        const totalCount = typeof rawTotalCount === 'number' ? rawTotalCount : undefined;
         // Parse items - automatically handle JSON string responses
         const parsedItems = typeof rawItems === 'string' ? JSON.parse(rawItems) : (rawItems || []);
         const items = transformFn ? parsedItems.map(transformFn) : parsedItems;
@@ -1484,8 +1512,9 @@ class BaseService {
     constructor(instance, headers) {
         // Private field - not visible via Object.keys() or any reflection
         _BaseService_apiClient.set(this, void 0);
-        const { config, context, tokenManager } = SDKInternalsRegistry.get(instance);
+        const { config, context, tokenManager, folderKey } = SDKInternalsRegistry.get(instance);
         __classPrivateFieldSet(this, _BaseService_apiClient, new ApiClient(config, context, tokenManager, headers ? { headers } : {}), "f");
+        this.config = { folderKey };
     }
     /**
      * Gets a valid authentication token, refreshing if necessary.
@@ -1604,9 +1633,17 @@ class BaseService {
                 const pageSizeParam = paginationParams?.pageSizeParam || ODATA_OFFSET_PARAMS.PAGE_SIZE_PARAM;
                 const offsetParam = paginationParams?.offsetParam || ODATA_OFFSET_PARAMS.OFFSET_PARAM;
                 const countParam = paginationParams?.countParam || ODATA_OFFSET_PARAMS.COUNT_PARAM;
+                // When true (default), converts pageNumber to a skip/offset value (e.g., page 3 with pageSize 10 → skip 20).
+                // When false, passes pageNumber directly as the offset param — used by APIs that accept a page number instead of a record offset.
+                const convertToSkip = paginationParams?.convertToSkip ?? true;
                 requestParams[pageSizeParam] = limitedPageSize;
-                if (params.pageNumber && params.pageNumber > 1) {
-                    requestParams[offsetParam] = (params.pageNumber - 1) * limitedPageSize;
+                if (convertToSkip) {
+                    if (params.pageNumber && params.pageNumber > 1) {
+                        requestParams[offsetParam] = (params.pageNumber - 1) * limitedPageSize;
+                    }
+                }
+                else {
+                    requestParams[offsetParam] = params.pageNumber || 1;
                 }
                 {
                     requestParams[countParam] = true;
@@ -1637,7 +1674,8 @@ class BaseService {
         // Extract items and metadata
         // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N })
         const items = Array.isArray(response.data) ? response.data : (response.data[itemsField] || []);
-        const totalCount = Array.isArray(response.data) ? undefined : response.data[totalCountField];
+        const rawTotalCount = Array.isArray(response.data) ? undefined : resolveNestedField(response.data, totalCountField);
+        const totalCount = typeof rawTotalCount === 'number' ? rawTotalCount : undefined;
         const continuationToken = response.data[continuationTokenField];
         // Determine if there are more pages
         const hasMore = this.determineHasMorePages(paginationType, {
@@ -1682,6 +1720,208 @@ class BaseService {
 }
 _BaseService_apiClient = new WeakMap();
 
+/**
+ * Validates the `name` argument passed to a `getByName(name, ...)` method.
+ * Trims whitespace and rejects empty/whitespace-only names.
+ *
+ * @param resourceType - Resource label used in error messages (e.g. 'Asset', 'Process')
+ * @param name - Resource name to validate
+ * @returns The trimmed name
+ * @throws ValidationError when `name` is missing or empty after trimming
+ */
+function validateName(resourceType, name) {
+    if (!name) {
+        throw new ValidationError({
+            message: `${resourceType} name is required and cannot be empty.`,
+        });
+    }
+    const trimmed = name.trim();
+    if (!trimmed) {
+        throw new ValidationError({
+            message: `${resourceType} name is required and cannot be empty.`,
+        });
+    }
+    return trimmed;
+}
+
+/**
+ * Encodes a folder path for the `X-UIPATH-FolderPath-Encoded` header.
+ *
+ * Orchestrator decodes this header as **base64-encoded UTF-16 LE bytes**
+ * (see `HttpHeadersProviderExtensions.GetDecoded` + `OrganizationUnitProvider`
+ * in the Orchestrator repo, which call `Encoding.Unicode.GetString(...)`).
+ * URL-encoding is NOT what the server expects — it must be base64-of-UTF-16-LE
+ * bytes.
+ *
+ * @param folderPath - The folder path (e.g. 'Shared/Finance')
+ * @returns Base64 string suitable for the `X-UIPATH-FolderPath-Encoded` header
+ */
+function encodeFolderPathHeader(folderPath) {
+    // Force little-endian regardless of host byte order. `Uint16Array` viewed
+    // as `Uint8Array` would use the host's native order — correct on LE hosts
+    // (x86/ARM-LE) but wrong on BE hosts. `DataView.setUint16(..., true)`
+    // pins LE.
+    const buf = new ArrayBuffer(folderPath.length * 2);
+    const view = new DataView(buf);
+    for (let i = 0; i < folderPath.length; i++) {
+        view.setUint16(i * 2, folderPath.charCodeAt(i), true);
+    }
+    const bytes = new Uint8Array(buf);
+    let binary = '';
+    for (let i = 0; i < bytes.byteLength; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    // btoa is browser-native; Node 16+ also has it as a global
+    return btoa(binary);
+}
+
+/**
+ * Resolves folder context into the appropriate Orchestrator folder headers.
+ *
+ * Centralized so all folder-scoped methods (e.g. `assets.getByName`,
+ * `processes.getByName`, future Queues/Buckets/Jobs) share one implementation.
+ *
+ * Each input field maps directly to its header — no auto-detection or type
+ * coercion. When multiple fields are supplied, all corresponding headers
+ * are forwarded and the server resolves precedence.
+ *
+ * Routing:
+ * - `folderId` → `X-UIPATH-OrganizationUnitId`
+ * - `folderKey` → `X-UIPATH-FolderKey`
+ * - `folderPath` → `X-UIPATH-FolderPath-Encoded`
+ * - none set + `fallbackFolderKey` → fallback used as `X-UIPATH-FolderKey`
+ * - none set + no fallback → `ValidationError`
+ *
+ * @throws ValidationError when no folder context can be resolved.
+ */
+function resolveFolderHeaders(input) {
+    const { folderId, folderKey, folderPath, resourceType, fallbackFolderKey } = input;
+    const trimmedKey = folderKey?.trim();
+    const trimmedPath = folderPath?.trim();
+    const headers = {};
+    if (folderId !== undefined) {
+        headers[FOLDER_ID] = folderId;
+    }
+    if (trimmedKey) {
+        headers[FOLDER_KEY] = trimmedKey;
+    }
+    if (trimmedPath) {
+        headers[FOLDER_PATH_ENCODED] = encodeFolderPathHeader(trimmedPath);
+    }
+    // No explicit folder context → meta-tag fallback or error.
+    if (Object.keys(headers).length === 0) {
+        if (!fallbackFolderKey) {
+            throw new ValidationError({
+                message: `${resourceType} requires folder context: pass \`folderId\`, \`folderKey\`, or \`folderPath\`, or initialize the SDK with a folder context.`,
+            });
+        }
+        headers[FOLDER_KEY] = fallbackFolderKey;
+    }
+    return createHeaders(headers);
+}
+
+/**
+ * Matches single-quote characters in OData string literals — escaped to `''`
+ * inside the `$filter=Name eq '…'` clause built by `getByNameLookup`.
+ */
+const SINGLE_QUOTE_RE = /'/g;
+/**
+ * Base service for services that need folder-specific functionality.
+ *
+ * Extends BaseService with additional methods for working with folder-scoped resources
+ * in UiPath Orchestrator. Services that work with folders (Assets, Queues) extend this class.
+ *
+ * @remarks
+ * This class provides helper methods for making folder-scoped API calls, handling folder IDs
+ * in request headers, and managing cross-folder queries.
+ */
+class FolderScopedService extends BaseService {
+    /**
+     * Gets resources in a folder with optional query parameters
+     *
+     * @param endpoint - API endpoint to call
+     * @param folderId - required folder ID
+     * @param options - Query options
+     * @param transformFn - Optional function to transform the response data
+     * @returns Promise resolving to an array of resources
+     */
+    async _getByFolder(endpoint, folderId, options = {}, transformFn) {
+        const headers = createHeaders({ [FOLDER_ID]: folderId });
+        const keysToPrefix = Object.keys(options);
+        const apiOptions = addPrefixToKeys(options, ODATA_PREFIX, keysToPrefix);
+        const response = await this.get(endpoint, {
+            params: apiOptions,
+            headers
+        });
+        if (transformFn) {
+            return response.data?.value.map(transformFn);
+        }
+        return response.data?.value;
+    }
+    /**
+     * Look up a single resource by name on a folder-scoped OData collection.
+     *
+     * Shared by `getByName` implementations across services (Assets, Processes, etc).
+     * Handles:
+     * - Name validation via `validateName`
+     * - Folder header resolution via `resolveFolderHeaders` (folderId → ID/key
+     *   header by type, folderPath → encoded path header, falls back to
+     *   init-time `config.folderKey` from the `uipath:folder-key` meta tag)
+     * - OData `$filter=Name eq '…'` with single-quote escaping + `$top=1`
+     * - Empty-result → `NotFoundError` with folder context in the message
+     *
+     * The transform step is caller-provided because each resource has its own
+     * PascalCase → camelCase field mapping.
+     *
+     * @param resourceType - Resource label used in validation + error messages (e.g. 'Asset', 'Process')
+     * @param endpoint - Folder-scoped OData collection endpoint
+     * @param name - Resource name to search for
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) + OData query options (`expand`, `select`)
+     * @param transform - Maps a raw OData item to the typed response (e.g. PascalCase → camelCase via field map)
+     * @throws ValidationError when inputs are malformed; NotFoundError when no match
+     */
+    async getByNameLookup(resourceType, endpoint, name, options, transform) {
+        const validatedName = validateName(resourceType, name);
+        const { folderId, folderKey, folderPath, ...queryOptions } = options;
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: `${resourceType}.getByName`,
+            fallbackFolderKey: this.config.folderKey,
+        });
+        const apiOptions = {
+            ...addPrefixToKeys(queryOptions, ODATA_PREFIX, Object.keys(queryOptions)),
+            '$filter': `Name eq '${validatedName.replace(SINGLE_QUOTE_RE, "''")}'`,
+            '$top': '1',
+        };
+        const response = await this.get(endpoint, {
+            headers,
+            params: apiOptions,
+        });
+        const items = response.data?.value;
+        if (!items?.length) {
+            const folderHint = describeFolderForError(folderId, folderKey, folderPath);
+            throw new NotFoundError({
+                message: `${resourceType} '${validatedName}' not found${folderHint}.`,
+            });
+        }
+        return transform(items[0]);
+    }
+}
+/** Renders the supplied folder for a NotFoundError message. */
+function describeFolderForError(folderId, folderKey, folderPath) {
+    const path = folderPath?.trim();
+    if (path)
+        return ` in folder '${path}'`;
+    const key = folderKey?.trim();
+    if (key)
+        return ` in folder (key: ${key})`;
+    if (typeof folderId === 'number')
+        return ` in folder (id: ${folderId})`;
+    return '';
+}
+
 /**
  * Maps fields for Process entities to ensure consistent naming
  */
@@ -1722,7 +1962,7 @@ const PROCESS_ENDPOINTS = {
 // Connection string placeholder that will be replaced during build
 const CONNECTION_STRING = "InstrumentationKey=a6efa11d-1feb-4508-9738-e13e12dcae5e;IngestionEndpoint=https://westeurope-5.in.applicationinsights.azure.com/;LiveEndpoint=https://westeurope.livediagnostics.monitor.azure.com/;ApplicationId=7c58eb1c-9581-4ba6-839e-11725848a037";
 // SDK Version placeholder 
-const SDK_VERSION = "1.3.6";
+const SDK_VERSION = "1.3.8";
 const VERSION = "Version";
 const SERVICE = "Service";
 const CLOUD_ORGANIZATION_NAME = "CloudOrganizationName";
@@ -1993,7 +2233,7 @@ function track(nameOrOptions, options) {
 /**
  * Service for interacting with UiPath Orchestrator Processes API
  */
-class ProcessService extends BaseService {
+class ProcessService extends FolderScopedService {
     /**
      * Gets all processes across folders with optional filtering and folder scoping
      *
@@ -2130,6 +2370,35 @@ class ProcessService extends BaseService {
         const transformedProcess = transformData(pascalToCamelCaseKeys(response.data), ProcessMap);
         return transformedProcess;
     }
+    /**
+     * Retrieves a single process by name.
+     *
+     * @param name - Process name to search for
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional query parameters (`expand`, `select`)
+     * @returns Promise resolving to a single process
+     * {@link ProcessGetResponse}
+     * @example
+     * ```typescript
+     * import { Processes } from '@uipath/uipath-typescript/processes';
+     *
+     * const processes = new Processes(sdk);
+     *
+     * // By folder ID
+     * await processes.getByName('MyProcess', { folderId: 123 });
+     *
+     * // By folder key (GUID)
+     * await processes.getByName('MyProcess', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await processes.getByName('MyProcess', { folderPath: 'Shared/Finance' });
+     *
+     * // With expand
+     * await processes.getByName('MyProcess', { folderPath: 'Shared/Finance', expand: 'entryPoints' });
+     * ```
+     */
+    async getByName(name, options = {}) {
+        return this.getByNameLookup('Process', PROCESS_ENDPOINTS.GET_ALL, name, options, (raw) => transformData(pascalToCamelCaseKeys(raw), ProcessMap));
+    }
 }
 __decorate([
     track('Processes.GetAll')
@@ -2140,6 +2409,9 @@ __decorate([
 __decorate([
     track('Processes.GetById')
 ], ProcessService.prototype, "getById", null);
+__decorate([
+    track('Processes.GetByName')
+], ProcessService.prototype, "getByName", null);
 
 /**
  * Enum for package types

package/dist/processes/index.d.ts

@@ -106,6 +106,7 @@ interface RequestWithPaginationOptions extends RequestSpec {
             offsetParam?: string;
             tokenParam?: string;
             countParam?: string;
+            convertToSkip?: boolean;
         };
     };
 }
@@ -218,6 +219,13 @@ interface ApiResponse<T> {
  */
 declare class BaseService {
     #private;
+    /**
+     * SDK configuration (read-only). Available to subclasses so they can
+     * fall back to init-time defaults like `folderKey`.
+     */
+    protected readonly config: {
+        folderKey?: string;
+    };
     /**
      * Creates a base service instance with dependency injection.
      *
@@ -316,6 +324,66 @@ interface RequestOptions extends BaseOptions {
     filter?: string;
     orderby?: string;
 }
+/**
+ * Options that scope a name-based lookup (e.g. `getByName`) to a folder.
+ * Provide one of `folderId`, `folderKey`, or `folderPath`. When more than
+ * one is supplied, all are forwarded; the server applies precedence
+ * `folderPath` > `folderKey` > `folderId`.
+ */
+interface FolderScopedOptions extends BaseOptions {
+    /** Numeric folder ID. */
+    folderId?: number;
+    /** Folder key (GUID-formatted string). */
+    folderKey?: string;
+    /** Slash-delimited folder path, e.g. `'Shared/Finance'`. */
+    folderPath?: string;
+}
+
+/**
+ * Base service for services that need folder-specific functionality.
+ *
+ * Extends BaseService with additional methods for working with folder-scoped resources
+ * in UiPath Orchestrator. Services that work with folders (Assets, Queues) extend this class.
+ *
+ * @remarks
+ * This class provides helper methods for making folder-scoped API calls, handling folder IDs
+ * in request headers, and managing cross-folder queries.
+ */
+declare class FolderScopedService extends BaseService {
+    /**
+     * Gets resources in a folder with optional query parameters
+     *
+     * @param endpoint - API endpoint to call
+     * @param folderId - required folder ID
+     * @param options - Query options
+     * @param transformFn - Optional function to transform the response data
+     * @returns Promise resolving to an array of resources
+     */
+    protected _getByFolder<T, R = T>(endpoint: string, folderId: number, options?: Record<string, any>, transformFn?: (item: T) => R): Promise<R[]>;
+    /**
+     * Look up a single resource by name on a folder-scoped OData collection.
+     *
+     * Shared by `getByName` implementations across services (Assets, Processes, etc).
+     * Handles:
+     * - Name validation via `validateName`
+     * - Folder header resolution via `resolveFolderHeaders` (folderId → ID/key
+     *   header by type, folderPath → encoded path header, falls back to
+     *   init-time `config.folderKey` from the `uipath:folder-key` meta tag)
+     * - OData `$filter=Name eq '…'` with single-quote escaping + `$top=1`
+     * - Empty-result → `NotFoundError` with folder context in the message
+     *
+     * The transform step is caller-provided because each resource has its own
+     * PascalCase → camelCase field mapping.
+     *
+     * @param resourceType - Resource label used in validation + error messages (e.g. 'Asset', 'Process')
+     * @param endpoint - Folder-scoped OData collection endpoint
+     * @param name - Resource name to search for
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) + OData query options (`expand`, `select`)
+     * @param transform - Maps a raw OData item to the typed response (e.g. PascalCase → camelCase via field map)
+     * @throws ValidationError when inputs are malformed; NotFoundError when no match
+     */
+    protected getByNameLookup<TRaw extends object, T>(resourceType: string, endpoint: string, name: string, options: FolderScopedOptions, transform: (raw: TRaw) => T): Promise<T>;
+}
 
 /**
  * Enum for package types
@@ -671,6 +739,11 @@ type ProcessGetAllOptions = RequestOptions & PaginationOptions & {
  */
 interface ProcessGetByIdOptions extends BaseOptions {
 }
+/**
+ * Options for getting a single process by name
+ */
+interface ProcessGetByNameOptions extends FolderScopedOptions {
+}
 
 /**
  * Service for managing and executing UiPath Automation Processes.
@@ -743,6 +816,29 @@ interface ProcessServiceModel {
      * ```
      */
     getById(id: number, folderId: number, options?: ProcessGetByIdOptions): Promise<ProcessGetResponse>;
+    /**
+     * Retrieves a single process by name.
+     *
+     * @param name - Process name to search for
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional query parameters (`expand`, `select`)
+     * @returns Promise resolving to a single process
+     * {@link ProcessGetResponse}
+     * @example
+     * ```typescript
+     * // By folder ID
+     * await processes.getByName('MyProcess', { folderId: 123 });
+     *
+     * // By folder key (GUID)
+     * await processes.getByName('MyProcess', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await processes.getByName('MyProcess', { folderPath: 'Shared/Finance' });
+     *
+     * // With expand
+     * await processes.getByName('MyProcess', { folderPath: 'Shared/Finance', expand: 'entryPoints' });
+     * ```
+     */
+    getByName(name: string, options?: ProcessGetByNameOptions): Promise<ProcessGetResponse>;
     /**
      * Starts a process with the specified configuration
      *
@@ -770,7 +866,7 @@ interface ProcessServiceModel {
 /**
  * Service for interacting with UiPath Orchestrator Processes API
  */
-declare class ProcessService extends BaseService implements ProcessServiceModel {
+declare class ProcessService extends FolderScopedService implements ProcessServiceModel {
     /**
      * Gets all processes across folders with optional filtering and folder scoping
      *
@@ -861,7 +957,34 @@ declare class ProcessService extends BaseService implements ProcessServiceModel
      * ```
      */
     getById(id: number, folderId: number, options?: ProcessGetByIdOptions): Promise<ProcessGetResponse>;
+    /**
+     * Retrieves a single process by name.
+     *
+     * @param name - Process name to search for
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional query parameters (`expand`, `select`)
+     * @returns Promise resolving to a single process
+     * {@link ProcessGetResponse}
+     * @example
+     * ```typescript
+     * import { Processes } from '@uipath/uipath-typescript/processes';
+     *
+     * const processes = new Processes(sdk);
+     *
+     * // By folder ID
+     * await processes.getByName('MyProcess', { folderId: 123 });
+     *
+     * // By folder key (GUID)
+     * await processes.getByName('MyProcess', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await processes.getByName('MyProcess', { folderPath: 'Shared/Finance' });
+     *
+     * // With expand
+     * await processes.getByName('MyProcess', { folderPath: 'Shared/Finance', expand: 'entryPoints' });
+     * ```
+     */
+    getByName(name: string, options?: ProcessGetByNameOptions): Promise<ProcessGetResponse>;
 }
 
 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, ProcessGetResponse, ProcessProperties, ProcessServiceModel, ProcessStartRequest, ProcessStartRequestWithKey, ProcessStartRequestWithName, ProcessStartResponse, RobotMetadata };
+export type { ArgumentMetadata, BaseProcessStartRequest, FolderProperties, JobAttachment, JobError, Machine, ProcessGetAllOptions, ProcessGetByIdOptions, ProcessGetByNameOptions, ProcessGetResponse, ProcessProperties, ProcessServiceModel, ProcessStartRequest, ProcessStartRequestWithKey, ProcessStartRequestWithName, ProcessStartResponse, RobotMetadata };