@uipath/uipath-typescript 1.3.5 → 1.3.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +1 -1
  2. package/dist/assets/index.cjs +204 -2
  3. package/dist/assets/index.d.ts +112 -13
  4. package/dist/assets/index.mjs +204 -2
  5. package/dist/attachments/index.cjs +3 -2
  6. package/dist/attachments/index.d.ts +7 -0
  7. package/dist/attachments/index.mjs +3 -2
  8. package/dist/buckets/index.cjs +172 -2
  9. package/dist/buckets/index.d.ts +56 -12
  10. package/dist/buckets/index.mjs +172 -2
  11. package/dist/cases/index.cjs +3 -2
  12. package/dist/cases/index.d.ts +7 -0
  13. package/dist/cases/index.mjs +3 -2
  14. package/dist/conversational-agent/index.cjs +196 -81
  15. package/dist/conversational-agent/index.d.ts +326 -80
  16. package/dist/conversational-agent/index.mjs +195 -80
  17. package/dist/core/index.cjs +44 -7
  18. package/dist/core/index.d.ts +11 -1
  19. package/dist/core/index.mjs +44 -7
  20. package/dist/entities/index.cjs +35 -6
  21. package/dist/entities/index.d.ts +101 -11
  22. package/dist/entities/index.mjs +36 -7
  23. package/dist/feedback/index.cjs +40 -5
  24. package/dist/feedback/index.d.ts +59 -1
  25. package/dist/feedback/index.mjs +40 -5
  26. package/dist/index.cjs +312 -14
  27. package/dist/index.d.ts +515 -32
  28. package/dist/index.mjs +313 -15
  29. package/dist/index.umd.js +312 -14
  30. package/dist/jobs/index.cjs +172 -2
  31. package/dist/jobs/index.d.ts +67 -23
  32. package/dist/jobs/index.mjs +172 -2
  33. package/dist/maestro-processes/index.cjs +3 -2
  34. package/dist/maestro-processes/index.d.ts +7 -0
  35. package/dist/maestro-processes/index.mjs +3 -2
  36. package/dist/processes/index.cjs +240 -3
  37. package/dist/processes/index.d.ts +124 -2
  38. package/dist/processes/index.mjs +240 -3
  39. package/dist/queues/index.cjs +172 -2
  40. package/dist/queues/index.d.ts +56 -12
  41. package/dist/queues/index.mjs +172 -2
  42. package/dist/tasks/index.cjs +3 -2
  43. package/dist/tasks/index.d.ts +7 -0
  44. package/dist/tasks/index.mjs +3 -2
  45. package/package.json +1 -1
@@ -505,6 +505,8 @@ class ErrorFactory {
505
505
  }
506
506
  }
507
507
 
508
+ const FOLDER_KEY = 'X-UIPATH-FolderKey';
509
+ const FOLDER_PATH_ENCODED = 'X-UIPATH-FolderPath-Encoded';
508
510
  const FOLDER_ID = 'X-UIPATH-OrganizationUnitId';
509
511
  const TRACEPARENT = 'traceparent';
510
512
  const UIPATH_TRACEPARENT_ID = 'x-uipath-traceparent-id';
@@ -1421,8 +1423,9 @@ class BaseService {
1421
1423
  constructor(instance, headers) {
1422
1424
  // Private field - not visible via Object.keys() or any reflection
1423
1425
  _BaseService_apiClient.set(this, void 0);
1424
- const { config, context, tokenManager } = SDKInternalsRegistry.get(instance);
1426
+ const { config, context, tokenManager, folderKey } = SDKInternalsRegistry.get(instance);
1425
1427
  __classPrivateFieldSet(this, _BaseService_apiClient, new ApiClient(config, context, tokenManager, headers ? { headers } : {}), "f");
1428
+ this.config = { folderKey };
1426
1429
  }
1427
1430
  /**
1428
1431
  * Gets a valid authentication token, refreshing if necessary.
@@ -1619,6 +1622,111 @@ class BaseService {
1619
1622
  }
1620
1623
  _BaseService_apiClient = new WeakMap();
1621
1624
 
1625
+ /**
1626
+ * Validates the `name` argument passed to a `getByName(name, ...)` method.
1627
+ * Trims whitespace and rejects empty/whitespace-only names.
1628
+ *
1629
+ * @param resourceType - Resource label used in error messages (e.g. 'Asset', 'Process')
1630
+ * @param name - Resource name to validate
1631
+ * @returns The trimmed name
1632
+ * @throws ValidationError when `name` is missing or empty after trimming
1633
+ */
1634
+ function validateName(resourceType, name) {
1635
+ if (!name) {
1636
+ throw new ValidationError({
1637
+ message: `${resourceType} name is required and cannot be empty.`,
1638
+ });
1639
+ }
1640
+ const trimmed = name.trim();
1641
+ if (!trimmed) {
1642
+ throw new ValidationError({
1643
+ message: `${resourceType} name is required and cannot be empty.`,
1644
+ });
1645
+ }
1646
+ return trimmed;
1647
+ }
1648
+
1649
+ /**
1650
+ * Encodes a folder path for the `X-UIPATH-FolderPath-Encoded` header.
1651
+ *
1652
+ * Orchestrator decodes this header as **base64-encoded UTF-16 LE bytes**
1653
+ * (see `HttpHeadersProviderExtensions.GetDecoded` + `OrganizationUnitProvider`
1654
+ * in the Orchestrator repo, which call `Encoding.Unicode.GetString(...)`).
1655
+ * URL-encoding is NOT what the server expects — it must be base64-of-UTF-16-LE
1656
+ * bytes.
1657
+ *
1658
+ * @param folderPath - The folder path (e.g. 'Shared/Finance')
1659
+ * @returns Base64 string suitable for the `X-UIPATH-FolderPath-Encoded` header
1660
+ */
1661
+ function encodeFolderPathHeader(folderPath) {
1662
+ // Force little-endian regardless of host byte order. `Uint16Array` viewed
1663
+ // as `Uint8Array` would use the host's native order — correct on LE hosts
1664
+ // (x86/ARM-LE) but wrong on BE hosts. `DataView.setUint16(..., true)`
1665
+ // pins LE.
1666
+ const buf = new ArrayBuffer(folderPath.length * 2);
1667
+ const view = new DataView(buf);
1668
+ for (let i = 0; i < folderPath.length; i++) {
1669
+ view.setUint16(i * 2, folderPath.charCodeAt(i), true);
1670
+ }
1671
+ const bytes = new Uint8Array(buf);
1672
+ let binary = '';
1673
+ for (let i = 0; i < bytes.byteLength; i++) {
1674
+ binary += String.fromCharCode(bytes[i]);
1675
+ }
1676
+ // btoa is browser-native; Node 16+ also has it as a global
1677
+ return btoa(binary);
1678
+ }
1679
+
1680
+ /**
1681
+ * Resolves folder context into the appropriate Orchestrator folder headers.
1682
+ *
1683
+ * Centralized so all folder-scoped methods (e.g. `assets.getByName`,
1684
+ * `processes.getByName`, future Queues/Buckets/Jobs) share one implementation.
1685
+ *
1686
+ * Each input field maps directly to its header — no auto-detection or type
1687
+ * coercion. When multiple fields are supplied, all corresponding headers
1688
+ * are forwarded and the server resolves precedence.
1689
+ *
1690
+ * Routing:
1691
+ * - `folderId` → `X-UIPATH-OrganizationUnitId`
1692
+ * - `folderKey` → `X-UIPATH-FolderKey`
1693
+ * - `folderPath` → `X-UIPATH-FolderPath-Encoded`
1694
+ * - none set + `fallbackFolderKey` → fallback used as `X-UIPATH-FolderKey`
1695
+ * - none set + no fallback → `ValidationError`
1696
+ *
1697
+ * @throws ValidationError when no folder context can be resolved.
1698
+ */
1699
+ function resolveFolderHeaders(input) {
1700
+ const { folderId, folderKey, folderPath, resourceType, fallbackFolderKey } = input;
1701
+ const trimmedKey = folderKey?.trim();
1702
+ const trimmedPath = folderPath?.trim();
1703
+ const headers = {};
1704
+ if (folderId !== undefined) {
1705
+ headers[FOLDER_ID] = folderId;
1706
+ }
1707
+ if (trimmedKey) {
1708
+ headers[FOLDER_KEY] = trimmedKey;
1709
+ }
1710
+ if (trimmedPath) {
1711
+ headers[FOLDER_PATH_ENCODED] = encodeFolderPathHeader(trimmedPath);
1712
+ }
1713
+ // No explicit folder context → meta-tag fallback or error.
1714
+ if (Object.keys(headers).length === 0) {
1715
+ if (!fallbackFolderKey) {
1716
+ throw new ValidationError({
1717
+ message: `${resourceType} requires folder context: pass \`folderId\`, \`folderKey\`, or \`folderPath\`, or initialize the SDK with a folder context.`,
1718
+ });
1719
+ }
1720
+ headers[FOLDER_KEY] = fallbackFolderKey;
1721
+ }
1722
+ return createHeaders(headers);
1723
+ }
1724
+
1725
+ /**
1726
+ * Matches single-quote characters in OData string literals — escaped to `''`
1727
+ * inside the `$filter=Name eq '…'` clause built by `getByNameLookup`.
1728
+ */
1729
+ const SINGLE_QUOTE_RE = /'/g;
1622
1730
  /**
1623
1731
  * Base service for services that need folder-specific functionality.
1624
1732
  *
@@ -1652,6 +1760,68 @@ class FolderScopedService extends BaseService {
1652
1760
  }
1653
1761
  return response.data?.value;
1654
1762
  }
1763
+ /**
1764
+ * Look up a single resource by name on a folder-scoped OData collection.
1765
+ *
1766
+ * Shared by `getByName` implementations across services (Assets, Processes, etc).
1767
+ * Handles:
1768
+ * - Name validation via `validateName`
1769
+ * - Folder header resolution via `resolveFolderHeaders` (folderId → ID/key
1770
+ * header by type, folderPath → encoded path header, falls back to
1771
+ * init-time `config.folderKey` from the `uipath:folder-key` meta tag)
1772
+ * - OData `$filter=Name eq '…'` with single-quote escaping + `$top=1`
1773
+ * - Empty-result → `NotFoundError` with folder context in the message
1774
+ *
1775
+ * The transform step is caller-provided because each resource has its own
1776
+ * PascalCase → camelCase field mapping.
1777
+ *
1778
+ * @param resourceType - Resource label used in validation + error messages (e.g. 'Asset', 'Process')
1779
+ * @param endpoint - Folder-scoped OData collection endpoint
1780
+ * @param name - Resource name to search for
1781
+ * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) + OData query options (`expand`, `select`)
1782
+ * @param transform - Maps a raw OData item to the typed response (e.g. PascalCase → camelCase via field map)
1783
+ * @throws ValidationError when inputs are malformed; NotFoundError when no match
1784
+ */
1785
+ async getByNameLookup(resourceType, endpoint, name, options, transform) {
1786
+ const validatedName = validateName(resourceType, name);
1787
+ const { folderId, folderKey, folderPath, ...queryOptions } = options;
1788
+ const headers = resolveFolderHeaders({
1789
+ folderId,
1790
+ folderKey,
1791
+ folderPath,
1792
+ resourceType: `${resourceType}.getByName`,
1793
+ fallbackFolderKey: this.config.folderKey,
1794
+ });
1795
+ const apiOptions = {
1796
+ ...addPrefixToKeys(queryOptions, ODATA_PREFIX, Object.keys(queryOptions)),
1797
+ '$filter': `Name eq '${validatedName.replace(SINGLE_QUOTE_RE, "''")}'`,
1798
+ '$top': '1',
1799
+ };
1800
+ const response = await this.get(endpoint, {
1801
+ headers,
1802
+ params: apiOptions,
1803
+ });
1804
+ const items = response.data?.value;
1805
+ if (!items?.length) {
1806
+ const folderHint = describeFolderForError(folderId, folderKey, folderPath);
1807
+ throw new NotFoundError({
1808
+ message: `${resourceType} '${validatedName}' not found${folderHint}.`,
1809
+ });
1810
+ }
1811
+ return transform(items[0]);
1812
+ }
1813
+ }
1814
+ /** Renders the supplied folder for a NotFoundError message. */
1815
+ function describeFolderForError(folderId, folderKey, folderPath) {
1816
+ const path = folderPath?.trim();
1817
+ if (path)
1818
+ return ` in folder '${path}'`;
1819
+ const key = folderKey?.trim();
1820
+ if (key)
1821
+ return ` in folder (key: ${key})`;
1822
+ if (typeof folderId === 'number')
1823
+ return ` in folder (id: ${folderId})`;
1824
+ return '';
1655
1825
  }
1656
1826
 
1657
1827
  /**
@@ -1753,7 +1923,7 @@ const JobMap = {
1753
1923
  // Connection string placeholder that will be replaced during build
1754
1924
  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";
1755
1925
  // SDK Version placeholder
1756
- const SDK_VERSION = "1.3.5";
1926
+ const SDK_VERSION = "1.3.7";
1757
1927
  const VERSION = "Version";
1758
1928
  const SERVICE = "Service";
1759
1929
  const CLOUD_ORGANIZATION_NAME = "CloudOrganizationName";
@@ -218,6 +218,13 @@ interface ApiResponse<T> {
218
218
  */
219
219
  declare class BaseService {
220
220
  #private;
221
+ /**
222
+ * SDK configuration (read-only). Available to subclasses so they can
223
+ * fall back to init-time defaults like `folderKey`.
224
+ */
225
+ protected readonly config: {
226
+ folderKey?: string;
227
+ };
221
228
  /**
222
229
  * Creates a base service instance with dependency injection.
223
230
  *
@@ -291,29 +298,6 @@ declare class BaseService {
291
298
  private determineHasMorePages;
292
299
  }
293
300
 
294
- /**
295
- * Base service for services that need folder-specific functionality.
296
- *
297
- * Extends BaseService with additional methods for working with folder-scoped resources
298
- * in UiPath Orchestrator. Services that work with folders (Assets, Queues) extend this class.
299
- *
300
- * @remarks
301
- * This class provides helper methods for making folder-scoped API calls, handling folder IDs
302
- * in request headers, and managing cross-folder queries.
303
- */
304
- declare class FolderScopedService extends BaseService {
305
- /**
306
- * Gets resources in a folder with optional query parameters
307
- *
308
- * @param endpoint - API endpoint to call
309
- * @param folderId - required folder ID
310
- * @param options - Query options
311
- * @param transformFn - Optional function to transform the response data
312
- * @returns Promise resolving to an array of resources
313
- */
314
- protected _getByFolder<T, R = T>(endpoint: string, folderId: number, options?: Record<string, any>, transformFn?: (item: T) => R): Promise<R[]>;
315
- }
316
-
317
301
  /**
318
302
  * Common enum for job state used across services
319
303
  */
@@ -339,6 +323,66 @@ interface RequestOptions extends BaseOptions {
339
323
  filter?: string;
340
324
  orderby?: string;
341
325
  }
326
+ /**
327
+ * Options that scope a name-based lookup (e.g. `getByName`) to a folder.
328
+ * Provide one of `folderId`, `folderKey`, or `folderPath`. When more than
329
+ * one is supplied, all are forwarded; the server applies precedence
330
+ * `folderPath` > `folderKey` > `folderId`.
331
+ */
332
+ interface FolderScopedOptions extends BaseOptions {
333
+ /** Numeric folder ID. */
334
+ folderId?: number;
335
+ /** Folder key (GUID-formatted string). */
336
+ folderKey?: string;
337
+ /** Slash-delimited folder path, e.g. `'Shared/Finance'`. */
338
+ folderPath?: string;
339
+ }
340
+
341
+ /**
342
+ * Base service for services that need folder-specific functionality.
343
+ *
344
+ * Extends BaseService with additional methods for working with folder-scoped resources
345
+ * in UiPath Orchestrator. Services that work with folders (Assets, Queues) extend this class.
346
+ *
347
+ * @remarks
348
+ * This class provides helper methods for making folder-scoped API calls, handling folder IDs
349
+ * in request headers, and managing cross-folder queries.
350
+ */
351
+ declare class FolderScopedService extends BaseService {
352
+ /**
353
+ * Gets resources in a folder with optional query parameters
354
+ *
355
+ * @param endpoint - API endpoint to call
356
+ * @param folderId - required folder ID
357
+ * @param options - Query options
358
+ * @param transformFn - Optional function to transform the response data
359
+ * @returns Promise resolving to an array of resources
360
+ */
361
+ protected _getByFolder<T, R = T>(endpoint: string, folderId: number, options?: Record<string, any>, transformFn?: (item: T) => R): Promise<R[]>;
362
+ /**
363
+ * Look up a single resource by name on a folder-scoped OData collection.
364
+ *
365
+ * Shared by `getByName` implementations across services (Assets, Processes, etc).
366
+ * Handles:
367
+ * - Name validation via `validateName`
368
+ * - Folder header resolution via `resolveFolderHeaders` (folderId → ID/key
369
+ * header by type, folderPath → encoded path header, falls back to
370
+ * init-time `config.folderKey` from the `uipath:folder-key` meta tag)
371
+ * - OData `$filter=Name eq '…'` with single-quote escaping + `$top=1`
372
+ * - Empty-result → `NotFoundError` with folder context in the message
373
+ *
374
+ * The transform step is caller-provided because each resource has its own
375
+ * PascalCase → camelCase field mapping.
376
+ *
377
+ * @param resourceType - Resource label used in validation + error messages (e.g. 'Asset', 'Process')
378
+ * @param endpoint - Folder-scoped OData collection endpoint
379
+ * @param name - Resource name to search for
380
+ * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) + OData query options (`expand`, `select`)
381
+ * @param transform - Maps a raw OData item to the typed response (e.g. PascalCase → camelCase via field map)
382
+ * @throws ValidationError when inputs are malformed; NotFoundError when no match
383
+ */
384
+ protected getByNameLookup<TRaw extends object, T>(resourceType: string, endpoint: string, name: string, options: FolderScopedOptions, transform: (raw: TRaw) => T): Promise<T>;
385
+ }
342
386
 
343
387
  /**
344
388
  * Enum for package types
@@ -503,6 +503,8 @@ class ErrorFactory {
503
503
  }
504
504
  }
505
505
 
506
+ const FOLDER_KEY = 'X-UIPATH-FolderKey';
507
+ const FOLDER_PATH_ENCODED = 'X-UIPATH-FolderPath-Encoded';
506
508
  const FOLDER_ID = 'X-UIPATH-OrganizationUnitId';
507
509
  const TRACEPARENT = 'traceparent';
508
510
  const UIPATH_TRACEPARENT_ID = 'x-uipath-traceparent-id';
@@ -1419,8 +1421,9 @@ class BaseService {
1419
1421
  constructor(instance, headers) {
1420
1422
  // Private field - not visible via Object.keys() or any reflection
1421
1423
  _BaseService_apiClient.set(this, void 0);
1422
- const { config, context, tokenManager } = SDKInternalsRegistry.get(instance);
1424
+ const { config, context, tokenManager, folderKey } = SDKInternalsRegistry.get(instance);
1423
1425
  __classPrivateFieldSet(this, _BaseService_apiClient, new ApiClient(config, context, tokenManager, headers ? { headers } : {}), "f");
1426
+ this.config = { folderKey };
1424
1427
  }
1425
1428
  /**
1426
1429
  * Gets a valid authentication token, refreshing if necessary.
@@ -1617,6 +1620,111 @@ class BaseService {
1617
1620
  }
1618
1621
  _BaseService_apiClient = new WeakMap();
1619
1622
 
1623
+ /**
1624
+ * Validates the `name` argument passed to a `getByName(name, ...)` method.
1625
+ * Trims whitespace and rejects empty/whitespace-only names.
1626
+ *
1627
+ * @param resourceType - Resource label used in error messages (e.g. 'Asset', 'Process')
1628
+ * @param name - Resource name to validate
1629
+ * @returns The trimmed name
1630
+ * @throws ValidationError when `name` is missing or empty after trimming
1631
+ */
1632
+ function validateName(resourceType, name) {
1633
+ if (!name) {
1634
+ throw new ValidationError({
1635
+ message: `${resourceType} name is required and cannot be empty.`,
1636
+ });
1637
+ }
1638
+ const trimmed = name.trim();
1639
+ if (!trimmed) {
1640
+ throw new ValidationError({
1641
+ message: `${resourceType} name is required and cannot be empty.`,
1642
+ });
1643
+ }
1644
+ return trimmed;
1645
+ }
1646
+
1647
+ /**
1648
+ * Encodes a folder path for the `X-UIPATH-FolderPath-Encoded` header.
1649
+ *
1650
+ * Orchestrator decodes this header as **base64-encoded UTF-16 LE bytes**
1651
+ * (see `HttpHeadersProviderExtensions.GetDecoded` + `OrganizationUnitProvider`
1652
+ * in the Orchestrator repo, which call `Encoding.Unicode.GetString(...)`).
1653
+ * URL-encoding is NOT what the server expects — it must be base64-of-UTF-16-LE
1654
+ * bytes.
1655
+ *
1656
+ * @param folderPath - The folder path (e.g. 'Shared/Finance')
1657
+ * @returns Base64 string suitable for the `X-UIPATH-FolderPath-Encoded` header
1658
+ */
1659
+ function encodeFolderPathHeader(folderPath) {
1660
+ // Force little-endian regardless of host byte order. `Uint16Array` viewed
1661
+ // as `Uint8Array` would use the host's native order — correct on LE hosts
1662
+ // (x86/ARM-LE) but wrong on BE hosts. `DataView.setUint16(..., true)`
1663
+ // pins LE.
1664
+ const buf = new ArrayBuffer(folderPath.length * 2);
1665
+ const view = new DataView(buf);
1666
+ for (let i = 0; i < folderPath.length; i++) {
1667
+ view.setUint16(i * 2, folderPath.charCodeAt(i), true);
1668
+ }
1669
+ const bytes = new Uint8Array(buf);
1670
+ let binary = '';
1671
+ for (let i = 0; i < bytes.byteLength; i++) {
1672
+ binary += String.fromCharCode(bytes[i]);
1673
+ }
1674
+ // btoa is browser-native; Node 16+ also has it as a global
1675
+ return btoa(binary);
1676
+ }
1677
+
1678
+ /**
1679
+ * Resolves folder context into the appropriate Orchestrator folder headers.
1680
+ *
1681
+ * Centralized so all folder-scoped methods (e.g. `assets.getByName`,
1682
+ * `processes.getByName`, future Queues/Buckets/Jobs) share one implementation.
1683
+ *
1684
+ * Each input field maps directly to its header — no auto-detection or type
1685
+ * coercion. When multiple fields are supplied, all corresponding headers
1686
+ * are forwarded and the server resolves precedence.
1687
+ *
1688
+ * Routing:
1689
+ * - `folderId` → `X-UIPATH-OrganizationUnitId`
1690
+ * - `folderKey` → `X-UIPATH-FolderKey`
1691
+ * - `folderPath` → `X-UIPATH-FolderPath-Encoded`
1692
+ * - none set + `fallbackFolderKey` → fallback used as `X-UIPATH-FolderKey`
1693
+ * - none set + no fallback → `ValidationError`
1694
+ *
1695
+ * @throws ValidationError when no folder context can be resolved.
1696
+ */
1697
+ function resolveFolderHeaders(input) {
1698
+ const { folderId, folderKey, folderPath, resourceType, fallbackFolderKey } = input;
1699
+ const trimmedKey = folderKey?.trim();
1700
+ const trimmedPath = folderPath?.trim();
1701
+ const headers = {};
1702
+ if (folderId !== undefined) {
1703
+ headers[FOLDER_ID] = folderId;
1704
+ }
1705
+ if (trimmedKey) {
1706
+ headers[FOLDER_KEY] = trimmedKey;
1707
+ }
1708
+ if (trimmedPath) {
1709
+ headers[FOLDER_PATH_ENCODED] = encodeFolderPathHeader(trimmedPath);
1710
+ }
1711
+ // No explicit folder context → meta-tag fallback or error.
1712
+ if (Object.keys(headers).length === 0) {
1713
+ if (!fallbackFolderKey) {
1714
+ throw new ValidationError({
1715
+ message: `${resourceType} requires folder context: pass \`folderId\`, \`folderKey\`, or \`folderPath\`, or initialize the SDK with a folder context.`,
1716
+ });
1717
+ }
1718
+ headers[FOLDER_KEY] = fallbackFolderKey;
1719
+ }
1720
+ return createHeaders(headers);
1721
+ }
1722
+
1723
+ /**
1724
+ * Matches single-quote characters in OData string literals — escaped to `''`
1725
+ * inside the `$filter=Name eq '…'` clause built by `getByNameLookup`.
1726
+ */
1727
+ const SINGLE_QUOTE_RE = /'/g;
1620
1728
  /**
1621
1729
  * Base service for services that need folder-specific functionality.
1622
1730
  *
@@ -1650,6 +1758,68 @@ class FolderScopedService extends BaseService {
1650
1758
  }
1651
1759
  return response.data?.value;
1652
1760
  }
1761
+ /**
1762
+ * Look up a single resource by name on a folder-scoped OData collection.
1763
+ *
1764
+ * Shared by `getByName` implementations across services (Assets, Processes, etc).
1765
+ * Handles:
1766
+ * - Name validation via `validateName`
1767
+ * - Folder header resolution via `resolveFolderHeaders` (folderId → ID/key
1768
+ * header by type, folderPath → encoded path header, falls back to
1769
+ * init-time `config.folderKey` from the `uipath:folder-key` meta tag)
1770
+ * - OData `$filter=Name eq '…'` with single-quote escaping + `$top=1`
1771
+ * - Empty-result → `NotFoundError` with folder context in the message
1772
+ *
1773
+ * The transform step is caller-provided because each resource has its own
1774
+ * PascalCase → camelCase field mapping.
1775
+ *
1776
+ * @param resourceType - Resource label used in validation + error messages (e.g. 'Asset', 'Process')
1777
+ * @param endpoint - Folder-scoped OData collection endpoint
1778
+ * @param name - Resource name to search for
1779
+ * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) + OData query options (`expand`, `select`)
1780
+ * @param transform - Maps a raw OData item to the typed response (e.g. PascalCase → camelCase via field map)
1781
+ * @throws ValidationError when inputs are malformed; NotFoundError when no match
1782
+ */
1783
+ async getByNameLookup(resourceType, endpoint, name, options, transform) {
1784
+ const validatedName = validateName(resourceType, name);
1785
+ const { folderId, folderKey, folderPath, ...queryOptions } = options;
1786
+ const headers = resolveFolderHeaders({
1787
+ folderId,
1788
+ folderKey,
1789
+ folderPath,
1790
+ resourceType: `${resourceType}.getByName`,
1791
+ fallbackFolderKey: this.config.folderKey,
1792
+ });
1793
+ const apiOptions = {
1794
+ ...addPrefixToKeys(queryOptions, ODATA_PREFIX, Object.keys(queryOptions)),
1795
+ '$filter': `Name eq '${validatedName.replace(SINGLE_QUOTE_RE, "''")}'`,
1796
+ '$top': '1',
1797
+ };
1798
+ const response = await this.get(endpoint, {
1799
+ headers,
1800
+ params: apiOptions,
1801
+ });
1802
+ const items = response.data?.value;
1803
+ if (!items?.length) {
1804
+ const folderHint = describeFolderForError(folderId, folderKey, folderPath);
1805
+ throw new NotFoundError({
1806
+ message: `${resourceType} '${validatedName}' not found${folderHint}.`,
1807
+ });
1808
+ }
1809
+ return transform(items[0]);
1810
+ }
1811
+ }
1812
+ /** Renders the supplied folder for a NotFoundError message. */
1813
+ function describeFolderForError(folderId, folderKey, folderPath) {
1814
+ const path = folderPath?.trim();
1815
+ if (path)
1816
+ return ` in folder '${path}'`;
1817
+ const key = folderKey?.trim();
1818
+ if (key)
1819
+ return ` in folder (key: ${key})`;
1820
+ if (typeof folderId === 'number')
1821
+ return ` in folder (id: ${folderId})`;
1822
+ return '';
1653
1823
  }
1654
1824
 
1655
1825
  /**
@@ -1751,7 +1921,7 @@ const JobMap = {
1751
1921
  // Connection string placeholder that will be replaced during build
1752
1922
  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";
1753
1923
  // SDK Version placeholder
1754
- const SDK_VERSION = "1.3.5";
1924
+ const SDK_VERSION = "1.3.7";
1755
1925
  const VERSION = "Version";
1756
1926
  const SERVICE = "Service";
1757
1927
  const CLOUD_ORGANIZATION_NAME = "CloudOrganizationName";
@@ -1351,8 +1351,9 @@ class BaseService {
1351
1351
  constructor(instance, headers) {
1352
1352
  // Private field - not visible via Object.keys() or any reflection
1353
1353
  _BaseService_apiClient.set(this, void 0);
1354
- const { config, context, tokenManager } = SDKInternalsRegistry.get(instance);
1354
+ const { config, context, tokenManager, folderKey } = SDKInternalsRegistry.get(instance);
1355
1355
  __classPrivateFieldSet(this, _BaseService_apiClient, new ApiClient(config, context, tokenManager, headers ? { headers } : {}), "f");
1356
+ this.config = { folderKey };
1356
1357
  }
1357
1358
  /**
1358
1359
  * Gets a valid authentication token, refreshing if necessary.
@@ -1742,7 +1743,7 @@ class BpmnHelpers {
1742
1743
  // Connection string placeholder that will be replaced during build
1743
1744
  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";
1744
1745
  // SDK Version placeholder
1745
- const SDK_VERSION = "1.3.5";
1746
+ const SDK_VERSION = "1.3.7";
1746
1747
  const VERSION = "Version";
1747
1748
  const SERVICE = "Service";
1748
1749
  const CLOUD_ORGANIZATION_NAME = "CloudOrganizationName";
@@ -862,6 +862,13 @@ interface ApiResponse<T> {
862
862
  */
863
863
  declare class BaseService {
864
864
  #private;
865
+ /**
866
+ * SDK configuration (read-only). Available to subclasses so they can
867
+ * fall back to init-time defaults like `folderKey`.
868
+ */
869
+ protected readonly config: {
870
+ folderKey?: string;
871
+ };
865
872
  /**
866
873
  * Creates a base service instance with dependency injection.
867
874
  *
@@ -1349,8 +1349,9 @@ class BaseService {
1349
1349
  constructor(instance, headers) {
1350
1350
  // Private field - not visible via Object.keys() or any reflection
1351
1351
  _BaseService_apiClient.set(this, void 0);
1352
- const { config, context, tokenManager } = SDKInternalsRegistry.get(instance);
1352
+ const { config, context, tokenManager, folderKey } = SDKInternalsRegistry.get(instance);
1353
1353
  __classPrivateFieldSet(this, _BaseService_apiClient, new ApiClient(config, context, tokenManager, headers ? { headers } : {}), "f");
1354
+ this.config = { folderKey };
1354
1355
  }
1355
1356
  /**
1356
1357
  * Gets a valid authentication token, refreshing if necessary.
@@ -1740,7 +1741,7 @@ class BpmnHelpers {
1740
1741
  // Connection string placeholder that will be replaced during build
1741
1742
  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";
1742
1743
  // SDK Version placeholder
1743
- const SDK_VERSION = "1.3.5";
1744
+ const SDK_VERSION = "1.3.7";
1744
1745
  const VERSION = "Version";
1745
1746
  const SERVICE = "Service";
1746
1747
  const CLOUD_ORGANIZATION_NAME = "CloudOrganizationName";