@uipath/uipath-typescript 1.4.0 → 1.4.1

package/dist/index.cjs

@@ -4498,6 +4498,24 @@ exports.TaskActivityType = void 0;
     TaskActivityType["BulkCompleted"] = "BulkCompleted";
     TaskActivityType["FirstOpened"] = "FirstOpened";
 })(exports.TaskActivityType || (exports.TaskActivityType = {}));
+/**
+ * Defines how a task assignment is distributed.
+ *
+ * Defaults to {@link TaskAssignmentCriteria.SingleUser} (a direct single-user
+ * assignment) when not specified. The group-based criteria tell Action Center
+ * how to distribute the task across the members of a directory group.
+ */
+exports.TaskAssignmentCriteria = void 0;
+(function (TaskAssignmentCriteria) {
+    /** Assigned to a single user, like a direct assignment. */
+    TaskAssignmentCriteria["SingleUser"] = "SingleUser";
+    /** Assigned to the group member with the fewest pending tasks. */
+    TaskAssignmentCriteria["Workload"] = "Workload";
+    /** Assigned to all users in the group. */
+    TaskAssignmentCriteria["AllUsers"] = "AllUsers";
+    /** Assigned in a round-robin manner across the group's members. */
+    TaskAssignmentCriteria["RoundRobin"] = "RoundRobin";
+})(exports.TaskAssignmentCriteria || (exports.TaskAssignmentCriteria = {}));
 
 /**
  * Base path constants for different services
@@ -4654,6 +4672,9 @@ const DATA_FABRIC_TENANT_FOLDER_ID = '00000000-0000-0000-0000-000000000000';
 const DATA_FABRIC_ENDPOINTS = {
     ENTITY: {
         GET_ALL: `${DATAFABRIC_BASE}/api/Entity`,
+        // Lists tenant-level and folder-level entities together.
+        // Used by getAll when includeFolderEntities is true.
+        GET_ALL_V2: `${DATAFABRIC_BASE}/api/v2/Entity`,
         GET_ENTITY_RECORDS: (entityId) => `${DATAFABRIC_BASE}/api/EntityService/entity/${entityId}/read`,
         GET_BY_ID: (entityId) => `${DATAFABRIC_BASE}/api/Entity/${entityId}`,
         GET_RECORD_BY_ID: (entityId, recordId) => `${DATAFABRIC_BASE}/api/EntityService/entity/${entityId}/read/${recordId}`,
@@ -4737,6 +4758,15 @@ function isTokenExpired(tokenInfo) {
         return true;
     return new Date() >= tokenInfo.expiresAt;
 }
+/**
+ * The validated host origin when the app is running as a trusted, generic
+ * host-embedded app (`?host=embed&basedomain=<origin>` with an allowlisted
+ * UiPath origin); otherwise null. Shared by TokenManager (to create the
+ * EmbeddedTokenManager) and UiPath init (to seed an empty token so getValidToken
+ * can bootstrap the postMessage token flow), which previously duplicated this
+ * condition inline.
+ */
+const trustedEmbeddingOrigin = isHostEmbedded && embeddingOrigin && isValidHostOrigin(embeddingOrigin) ? embeddingOrigin : null;
 /**
  * Waits for the next window message that satisfies `filter`.
  * Rejects if the AbortSignal fires before a matching message arrives.
@@ -4983,7 +5013,7 @@ class EmbeddedTokenManager {
  * SDK's public API.
  */
 /** SDK version placeholder — patched by the SDK publish workflow. */
-const SDK_VERSION = '1.4.0';
+const SDK_VERSION = '1.4.1';
 const CLOUD_ROLE_NAME = 'uipath-ts-sdk';
 const SDK_SERVICE_NAME = 'UiPath.TypeScript.Sdk';
 const SDK_LOGGER_NAME = 'uipath-ts-sdk-telemetry';
@@ -5163,8 +5193,8 @@ class TokenManager {
             this.actionCenterTokenManager = new ActionCenterTokenManager(config, (tokenInfo) => this.setToken(tokenInfo));
             this.isOAuth = false;
         }
-        else if (isHostEmbedded && embeddingOrigin && isValidHostOrigin(embeddingOrigin)) {
-            this.embeddedTokenManager = new EmbeddedTokenManager(embeddingOrigin, config, tokenInfo => this.setToken(tokenInfo));
+        else if (trustedEmbeddingOrigin) {
+            this.embeddedTokenManager = new EmbeddedTokenManager(trustedEmbeddingOrigin, config, tokenInfo => this.setToken(tokenInfo));
             this.isOAuth = false;
         }
     }
@@ -6223,10 +6253,12 @@ _UiPath_config = new WeakMap(), _UiPath_authService = new WeakMap(), _UiPath_ini
     });
     // Track SDK initialization
     trackEvent('Sdk.Auth');
-    /** Auto-initialize for secret-based auth
-     * When viewed in Action Center, initialize tokenInfo with empty token. When an sdk call is made Action Center passes the token to sdk.
+    /** Auto-initialize for secret-based auth, Action Center, and generic host-embedded apps.
+     * When viewed in Action Center or embedded in a UiPath host frame via the UIP protocol,
+     * initialize tokenInfo with an empty token so getValidToken() can bootstrap via postMessage.
+     * When an sdk call is made, the host passes the token to the sdk.
      */
-    if (hasSecretAuth || isInActionCenter) {
+    if (hasSecretAuth || isInActionCenter || trustedEmbeddingOrigin) {
         __classPrivateFieldGet(this, _UiPath_authService, "f").authenticateWithSecret(config.secret ?? '');
         __classPrivateFieldSet(this, _UiPath_initialized, true, "f");
     }
@@ -7452,12 +7484,18 @@ class PaginationHelpers {
      * @returns Promise resolving to a paginated result
      */
     static async getAllPaginated(params) {
-        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, queryParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         const endpoint = getEndpoint(folderId);
         const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
+        // On POST, the caller's options go in the body; queryParams stays in the URL.
+        // On GET, everything is URL — queryParams merges with additionalParams.
+        const isPost = method === HTTP_METHODS.POST;
+        const requestSpec = isPost
+            ? { body: additionalParams, params: queryParams }
+            : { params: { ...additionalParams, ...queryParams } };
         const paginatedResponse = await serviceAccess.requestWithPagination(method, endpoint, paginationParams, {
             headers,
-            params: additionalParams,
+            ...requestSpec,
             pagination: {
                 paginationType: options.paginationType || PaginationType.OFFSET,
                 itemsField: options.itemsField || DEFAULT_ITEMS_FIELD,
@@ -7482,7 +7520,7 @@ class PaginationHelpers {
      * @returns Promise resolving to an object with data and totalCount
      */
     static async getAllNonPaginated(params) {
-        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, queryParams, 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;
@@ -7492,11 +7530,11 @@ class PaginationHelpers {
         // Make the API call based on method
         let response;
         if (method === HTTP_METHODS.POST) {
-            response = await serviceAccess.post(endpoint, additionalParams, { headers });
+            response = await serviceAccess.post(endpoint, additionalParams, { headers, params: queryParams });
         }
         else {
             response = await serviceAccess.get(endpoint, {
-                params: additionalParams,
+                params: { ...additionalParams, ...queryParams },
                 headers
             });
         }
@@ -7551,6 +7589,7 @@ class PaginationHelpers {
                 headers: config.headers,
                 paginationParams: cursor ? { cursor, pageSize } : jumpToPage !== undefined ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
+                queryParams: config.queryParams,
                 transformFn: config.transformFn,
                 method: config.method,
                 options: {
@@ -7568,6 +7607,7 @@ class PaginationHelpers {
             folderId,
             headers: config.headers,
             additionalParams: prefixedOptions,
+            queryParams: config.queryParams,
             transformFn: config.transformFn,
             method: config.method,
             options: {
@@ -7704,18 +7744,17 @@ class BaseService {
         const params = this.validateAndPreparePaginationParams(paginationType, paginationOptions);
         // Prepare request parameters based on pagination type
         const requestParams = this.preparePaginationRequestParams(paginationType, params, options.pagination);
-        // For POST requests, merge pagination params into body and set params to undefined; for GET, use query params
+        // Route pagination state to wherever the API expects it (body for POST, URL for GET).
+        // Caller-supplied options.body / options.params are respected as-is — the api-client
+        // already handles params (URL) and body (request body) independently for every method.
         if (method.toUpperCase() === 'POST') {
             const existingBody = (options.body && typeof options.body === 'object') ? options.body : {};
             options.body = {
                 ...existingBody,
-                ...options.params,
                 ...requestParams
             };
-            options.params = undefined;
         }
         else {
-            // Merge pagination parameters with existing parameters
             options.params = {
                 ...options.params,
                 ...requestParams
@@ -8129,6 +8168,14 @@ var SqlFieldType;
     SqlFieldType["MULTILINE"] = "MULTILINE";
 })(SqlFieldType || (SqlFieldType = {}));
 
+/**
+ * Numeric type IDs that pair with {@link EntityType} on reference payloads
+ * (entityType + entityTypeId travel together in `referenceEntity` /
+ * `referenceChoiceSet` bodies on cross-folder schema upserts).
+ */
+const ENTITY_TYPE_IDS = {
+    [exports.EntityType.ChoiceSet]: 1,
+};
 /**
  * Maps fields for Entities
  */
@@ -8262,7 +8309,7 @@ class EntityService extends BaseService {
      * Gets entity metadata by entity ID with attached operation methods
      *
      * @param id - UUID of the entity
-     * @param options - Optional {@link EntityGetByIdOptions} (e.g. `folderKey` for folder-scoped entities)
+     * @param options - Optional {@link EntityGetByIdOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to entity metadata with schema information and operation methods
      *
      * @example
@@ -8302,7 +8349,7 @@ class EntityService extends BaseService {
      * Gets entity records by entity ID
      *
      * @param entityId - UUID of the entity
-     * @param options - Query options including expansionLevel and pagination options
+     * @param options - Query options including expansionLevel and pagination options The `folderKey` property is **experimental**.
      * @returns Promise resolving to an array of entity records or paginated response
      *
      * @example
@@ -8330,6 +8377,9 @@ class EntityService extends BaseService {
      *   cursor: paginatedResponse.nextCursor,
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * const records = await entities.getAllRecords("<entityId>", { folderKey: "<folderKey>" });
      * ```
      */
     async getAllRecords(entityId, options) {
@@ -8359,7 +8409,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record
-     * @param options - Query options including expansionLevel
+     * @param options - Query options including `expansionLevel` and `folderKey` The `folderKey` property is **experimental**.
      * @returns Promise resolving to the entity record
      *
      * @example
@@ -8371,6 +8421,11 @@ class EntityService extends BaseService {
      * const record = await sdk.entities.getRecordById(<entityId>, <recordId>, {
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * const record = await sdk.entities.getRecordById(<entityId>, <recordId>, {
+     *   folderKey: "<folderKey>"
+     * });
      * ```
      */
     async getRecordById(entityId, recordId, options = {}) {
@@ -8385,7 +8440,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param data - Record to insert
-     * @param options - Insert options
+     * @param options - Insert options The `folderKey` property is **experimental**.
      * @returns Promise resolving to the inserted record with generated record ID
      *
      * @example
@@ -8401,6 +8456,11 @@ class EntityService extends BaseService {
      * const result = await entities.insertRecordById("<entityId>", { name: "John", age: 30 }, {
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.insertRecordById("<entityId>", { name: "John", age: 30 }, {
+     *   folderKey: "<folderKey>"
+     * });
      * ```
      */
     async insertRecordById(id, data, options = {}) {
@@ -8418,7 +8478,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param data - Array of records to insert
-     * @param options - Insert options
+     * @param options - Insert options The `folderKey` property is **experimental**.
      * @returns Promise resolving to insert response
      *
      * @example
@@ -8441,6 +8501,12 @@ class EntityService extends BaseService {
      *   expansionLevel: 1,
      *   failOnFirst: true
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.insertRecordsById("<entityId>", [
+     *   { name: "John", age: 30 },
+     *   { name: "Jane", age: 25 }
+     * ], { folderKey: "<folderKey>" });
      * ```
      */
     async insertRecordsById(id, data, options = {}) {
@@ -8460,7 +8526,7 @@ class EntityService extends BaseService {
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record to update
      * @param data - Key-value pairs of fields to update
-     * @param options - Update options
+     * @param options - Update options The `folderKey` property is **experimental**.
      * @returns Promise resolving to the updated record
      *
      * @example
@@ -8476,6 +8542,11 @@ class EntityService extends BaseService {
      * const result = await entities.updateRecordById("<entityId>", "<recordId>", { name: "John Updated", age: 31 }, {
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.updateRecordById("<entityId>", "<recordId>", { name: "John Updated" }, {
+     *   folderKey: "<folderKey>"
+     * });
      * ```
      */
     async updateRecordById(entityId, recordId, data, options = {}) {
@@ -8494,7 +8565,7 @@ class EntityService extends BaseService {
      * @param entityId - UUID of the entity
      * @param data - Array of records to update. Each record MUST contain the record Id,
      *               otherwise the update will fail.
-     * @param options - Update options
+     * @param options - Update options The `folderKey` property is **experimental**.
      * @returns Promise resolving to update response
      *
      * @example
@@ -8517,6 +8588,11 @@ class EntityService extends BaseService {
      *   expansionLevel: 1,
      *   failOnFirst: true
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.updateRecordsById("<entityId>", [
+     *   { Id: "123", name: "John Updated" }
+     * ], { folderKey: "<folderKey>" });
      * ```
      */
     async updateRecordsById(id, data, options = {}) {
@@ -8537,7 +8613,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param recordIds - Array of record UUIDs to delete
-     * @param options - Delete options
+     * @param options - Delete options The `folderKey` property is **experimental**.
      * @returns Promise resolving to delete response
      *
      * @example
@@ -8550,6 +8626,11 @@ class EntityService extends BaseService {
      * const result = await entities.deleteRecordsById("<entityId>", [
      *   "<recordId-1>", "<recordId-2>"
      * ]);
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.deleteRecordsById("<entityId>", [
+     *   "<recordId-1>", "<recordId-2>"
+     * ], { folderKey: "<folderKey>" });
      * ```
      */
     async deleteRecordsById(id, recordIds, options = {}) {
@@ -8570,7 +8651,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record to delete
-     * @param options - Optional {@link EntityDeleteRecordByIdOptions} (e.g. `folderKey` for folder-scoped entities)
+     * @param options - Optional {@link EntityDeleteRecordByIdOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to void on success
      * @example
      * ```typescript
@@ -8588,8 +8669,14 @@ class EntityService extends BaseService {
         await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE_RECORD_BY_ID(entityId, recordId), { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
     }
     /**
-     * Gets all entities in the system
+     * Gets entities in the tenant.
+     *
+     * Three call modes:
+     * - `getAll()` — default. Returns only tenant-level entities.
+     * - `getAll({ folderKey: "<uuid>" })` — preferred for folder-scoped data. Returns only entities in that folder.
+     * - `getAll({ includeFolderEntities: true })` — returns tenant-level **and** folder-level entities together. `folderKey` is preferred over `includeFolderEntities` when both are set.
      *
+     * @param options - Optional {@link EntityGetAllOptions} (`folderKey` to list a single folder's entities — preferred when scoping to a folder; `includeFolderEntities: true` to list tenant + folder entities together) The `folderKey` property is **experimental**.
      * @returns Promise resolving to an array of entity metadata
      *
      * @example
@@ -8598,15 +8685,29 @@ class EntityService extends BaseService {
      *
      * const entities = new Entities(sdk);
      *
-     * // Get all entities
-     * const allEntities = await entities.getAll();
+     * // Tenant-only (default)
+     * const tenantEntities = await entities.getAll();
+     *
+     * // A single folder's entities (preferred when targeting a specific folder)
+     * const folderEntities = await entities.getAll({ folderKey: "<folderKey>" });
+     *
+     * // Tenant + folder entities together
+     * const allEntities = await entities.getAll({ includeFolderEntities: true });
      *
      * // Call operations on an entity
-     * const records = await allEntities[0].getAllRecords();
+     * const records = await tenantEntities[0].getAllRecords();
      * ```
      */
-    async getAll() {
-        const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_ALL);
+    async getAll(options) {
+        // folderKey is preferred over includeFolderEntities: when present, scope to that folder
+        // via the v1 endpoint + header. Only when no folderKey is given AND includeFolderEntities
+        // is explicitly true does the SDK switch to the v2 endpoint (returns tenant + folder
+        // entities together). Default (no options or includeFolderEntities omitted) stays on
+        // the v1 endpoint = tenant only.
+        const endpoint = !options?.folderKey && options?.includeFolderEntities
+            ? DATA_FABRIC_ENDPOINTS.ENTITY.GET_ALL_V2
+            : DATA_FABRIC_ENDPOINTS.ENTITY.GET_ALL;
+        const response = await this.get(endpoint, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         // Apply transformations
         const entities = response.data.map(entity => {
             // Transform each entity
@@ -8621,7 +8722,7 @@ class EntityService extends BaseService {
      * Queries entity records with filters, sorting, aggregates, and pagination
      *
      * @param id - UUID of the entity
-     * @param options - Query options including filterGroup, selectedFields, sortOptions, aggregates, groupBy, and pagination
+     * @param options - Query options including filterGroup, selectedFields, sortOptions, aggregates, groupBy, and pagination The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link NonPaginatedResponse} without pagination options,
      *   or {@link PaginatedResponse} when `pageSize`, `cursor`, or `jumpToPage` are provided
      *
@@ -8668,18 +8769,24 @@ class EntityService extends BaseService {
      *     { function: EntityAggregateFunction.Avg, field: "amount", alias: "avgAmount" },
      *   ],
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.queryRecordsById("<entityId>", {
+     *   filterGroup: { queryFilters: [{ fieldName: "status", operator: QueryFilterOperator.Equals, value: "active" }] },
+     *   folderKey: "<folderKey>",
+     * });
      * ```
      */
     async queryRecordsById(id, options) {
-        // folderKey is header-only — destructure it out so PaginationHelpers doesn't include
-        // it in the POST body alongside the query filters.
-        const { folderKey, ...rest } = options ?? {};
+        // folderKey is header-only; expansionLevel must be sent as a query param by PaginationHelpers.
+        const { folderKey, expansionLevel, ...rest } = options ?? {};
         const downstreamOptions = options === undefined ? undefined : rest;
         return PaginationHelpers.getAll({
             serviceAccess: this.createPaginationServiceAccess(),
             getEndpoint: () => DATA_FABRIC_ENDPOINTS.ENTITY.QUERY_BY_ID(id),
             method: HTTP_METHODS.POST,
             headers: createHeaders({ [FOLDER_KEY]: folderKey }),
+            queryParams: createParams({ expansionLevel }),
             pagination: {
                 paginationType: PaginationType.OFFSET,
                 itemsField: ENTITY_PAGINATION.ITEMS_FIELD,
@@ -8690,7 +8797,7 @@ class EntityService extends BaseService {
                     countParam: ENTITY_OFFSET_PARAMS.COUNT_PARAM
                 }
             },
-            excludeFromPrefix: ['expansionLevel', 'filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
+            excludeFromPrefix: ['filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
         }, downstreamOptions);
     }
     /**
@@ -8698,7 +8805,7 @@ class EntityService extends BaseService {
      *
      * @param id - UUID of the entity
      * @param file - CSV file to import (Blob, File, or Uint8Array)
-     * @param options - Optional {@link EntityImportRecordsByIdOptions} (e.g. `folderKey` for folder-scoped entities)
+     * @param options - Optional {@link EntityImportRecordsByIdOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to import result with record counts
      *
      * @example
@@ -8741,7 +8848,7 @@ class EntityService extends BaseService {
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record containing the attachment
      * @param fieldName - Name of the File-type field containing the attachment
-     * @param options - Optional {@link EntityDownloadAttachmentOptions} (e.g. `folderKey` for folder-scoped entities)
+     * @param options - Optional {@link EntityDownloadAttachmentOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to Blob containing the file content
      *
      * @example
@@ -8779,7 +8886,7 @@ class EntityService extends BaseService {
      * @param recordId - UUID of the record to upload the attachment to
      * @param fieldName - Name of the File-type field
      * @param file - File to upload (Blob, File, or Uint8Array)
-     * @param options - Optional {@link EntityUploadAttachmentOptions} (e.g. `expansionLevel`, `folderKey` for folder-scoped entities)
+     * @param options - Optional {@link EntityUploadAttachmentOptions} (e.g. `expansionLevel`, `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link EntityUploadAttachmentResponse}
      *
      * @example
@@ -8824,7 +8931,7 @@ class EntityService extends BaseService {
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record containing the attachment
      * @param fieldName - Name of the File-type field containing the attachment
-     * @param options - Optional {@link EntityDeleteAttachmentOptions} (e.g. `folderKey` for folder-scoped entities)
+     * @param options - Optional {@link EntityDeleteAttachmentOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link EntityDeleteAttachmentResponse}
      *
      * @example
@@ -8879,7 +8986,7 @@ class EntityService extends BaseService {
      * @param name - Entity name — must start with a letter and contain
      *   only letters, numbers, and underscores (e.g., `"productCatalog"`).
      * @param fields - Array of field definitions
-     * @param options - Optional entity-level settings ({@link EntityCreateOptions})
+     * @param options - Optional entity-level settings ({@link EntityCreateOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving to the ID of the created entity
      *
      * @example
@@ -8895,17 +9002,36 @@ class EntityService extends BaseService {
      *   { fieldName: "price", type: EntityFieldDataType.DECIMAL, decimalPrecision: 4, maxValue: 999999, minValue: 0 },
      *   { fieldName: "quantity", type: EntityFieldDataType.INTEGER, maxValue: 10000, minValue: 1, defaultValue: "0" },
      * ]);
+     *
+     * // Cross-folder references — link a folder-scoped entity to entities and
+     * // system choice sets that live in another folder or at the tenant level.
+     * await entities.create("orderLine", [
+     *   {
+     *     fieldName: "order",
+     *     type: EntityFieldDataType.RELATIONSHIP,
+     *     referenceEntityId: "<orderEntityId>",
+     *     referenceFieldId: "<orderEntityPkId>",
+     *     referenceFolderKey: "<otherFolderKey>",     // target lives in a different folder
+     *   },
+     *   {
+     *     fieldName: "userType",
+     *     type: EntityFieldDataType.CHOICE_SET_SINGLE,
+     *     choiceSetId: "<systemUserTypeChoiceSetId>", // tenant-level system choice set
+     *     // referenceFolderKey omitted → SDK looks up the target at tenant scope
+     *   },
+     * ], { folderKey: "<sourceFolderKey>" });
      * ```
      * @internal
      */
     async create(name, fields, options) {
         const opts = options ?? {};
+        const fieldPayloads = await this.buildFieldsWithReferenceMeta(fields);
         const payload = {
             ...(opts.description !== undefined && { description: opts.description }),
             displayName: opts.displayName ?? name,
             entityDefinition: {
                 name,
-                fields: fields.map(f => this.buildSchemaFieldPayload(f)),
+                fields: fieldPayloads,
                 folderId: opts.folderKey ?? DATA_FABRIC_TENANT_FOLDER_ID,
                 isRbacEnabled: opts.isRbacEnabled ?? false,
                 isInsightsEnabled: opts.isAnalyticsEnabled ?? false,
@@ -8919,7 +9045,7 @@ class EntityService extends BaseService {
      * Deletes a Data Fabric entity and all its records
      *
      * @param id - UUID of the entity to delete
-     * @param options - Optional {@link EntityDeleteByIdOptions} (e.g. `folderKey` for folder-scoped entities)
+     * @param options - Optional {@link EntityDeleteByIdOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the entity is deleted
      *
      * @example
@@ -8946,7 +9072,7 @@ class EntityService extends BaseService {
      * overwrite each other's changes.
      *
      * @param id - UUID of the entity to update
-     * @param options - Changes to apply ({@link EntityUpdateByIdOptions})
+     * @param options - Changes to apply ({@link EntityUpdateByIdOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the update is complete
      *
      * @example
@@ -9058,10 +9184,9 @@ class EntityService extends BaseService {
                 };
             });
         }
-        // Build and append new fields
         const newFields = [];
         if (options.addFields?.length) {
-            newFields.push(...options.addFields.map(f => this.buildSchemaFieldPayload(f)));
+            newFields.push(...await this.buildFieldsWithReferenceMeta(options.addFields));
         }
         await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPSERT, {
             displayName: raw.displayName,
@@ -9159,8 +9284,39 @@ class EntityService extends BaseService {
             return externalSource;
         });
     }
+    async buildFieldsWithReferenceMeta(fields) {
+        const metas = await Promise.all(fields.map(f => this.buildReferenceMeta(f)));
+        return fields.map((f, i) => this.buildSchemaFieldPayload(f, metas[i]));
+    }
+    // Choice-set targets resolve server-side by NAME (the API rejects cross-folder
+    // refs with empty target name even when folderId is supplied), so the SDK
+    // fetches the name once for each cross-folder choice-set field. Relationship
+    // targets resolve by folderId — no lookup needed.
+    async buildReferenceMeta(field) {
+        if (field.referenceFolderKey === undefined)
+            return undefined;
+        if (field.referenceEntityId === undefined && field.choiceSetId === undefined)
+            return undefined;
+        const folderId = field.referenceFolderKey;
+        const meta = {};
+        if (field.referenceEntityId !== undefined) {
+            meta.referenceEntity = { id: field.referenceEntityId, folderId };
+        }
+        if (field.choiceSetId !== undefined) {
+            const lookupFolderKey = folderId === DATA_FABRIC_TENANT_FOLDER_ID ? undefined : folderId;
+            const target = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_BY_ID(field.choiceSetId), { headers: createHeaders({ [FOLDER_KEY]: lookupFolderKey }) });
+            meta.referenceChoiceSet = {
+                id: field.choiceSetId,
+                name: target.data.name,
+                folderId,
+                entityType: exports.EntityType.ChoiceSet,
+                entityTypeId: ENTITY_TYPE_IDS[exports.EntityType.ChoiceSet],
+            };
+        }
+        return meta;
+    }
     /** Converts a user-facing EntityCreateFieldOptions to the raw API field payload */
-    buildSchemaFieldPayload(field) {
+    buildSchemaFieldPayload(field, refMeta) {
         const fieldType = field.type ?? exports.EntityFieldDataType.STRING;
         this.validateFieldConstraints(fieldType, field, field.fieldName);
         const isRelationship = fieldType === exports.EntityFieldDataType.RELATIONSHIP;
@@ -9171,6 +9327,10 @@ class EntityService extends BaseService {
             });
         }
         const mapping = EntitySchemaFieldTypeMap[fieldType];
+        // Prefer the resolved {id, name, folderId} body so cross-folder targets resolve
+        // server-side; fall back to a bare {id} when no meta was fetched.
+        const referenceEntityBody = refMeta?.referenceEntity ?? (field.referenceEntityId === undefined ? undefined : { id: field.referenceEntityId });
+        const referenceChoiceSetBody = refMeta?.referenceChoiceSet;
         return {
             name: field.fieldName,
             displayName: field.displayName ?? field.fieldName,
@@ -9189,7 +9349,8 @@ class EntityService extends BaseService {
             ...(field.choiceSetId !== undefined && { choiceSetId: field.choiceSetId }),
             ...((isRelationship || isFile) && { isForeignKey: true }),
             ...(isRelationship && { referenceType: exports.ReferenceType.ManyToOne }),
-            ...(field.referenceEntityId !== undefined && { referenceEntity: { id: field.referenceEntityId } }),
+            ...(referenceEntityBody !== undefined && { referenceEntity: referenceEntityBody }),
+            ...(referenceChoiceSetBody !== undefined && { referenceChoiceSet: referenceChoiceSetBody }),
             ...(field.referenceFieldId !== undefined && { referenceField: { id: field.referenceFieldId } }),
         };
     }
@@ -9352,8 +9513,14 @@ __decorate([
 
 class ChoiceSetService extends BaseService {
     /**
-     * Gets all choice sets in the system
+     * Gets choice sets in the tenant.
+     *
+     * Three call modes:
+     * - `getAll()` — default. Returns only tenant-level choice sets.
+     * - `getAll({ folderKey: "<uuid>" })` — preferred for folder-scoped data. Returns only choice sets in that folder.
+     * - `getAll({ includeFolderChoiceSets: true })` — returns tenant-level **and** folder-level choice sets together. `folderKey` is preferred over `includeFolderChoiceSets` when both are set.
      *
+     * @param options - Optional {@link ChoiceSetGetAllOptions} (`folderKey` to list a single folder's choice sets — preferred when scoping to a folder; `includeFolderChoiceSets: true` to list tenant + folder choice sets together) The `folderKey` property is **experimental**.
      * @returns Promise resolving to an array of choice set metadata
      *
      * @example
@@ -9362,18 +9529,33 @@ class ChoiceSetService extends BaseService {
      *
      * const choiceSets = new ChoiceSets(sdk);
      *
-     * // Get all choice sets
-     * const allChoiceSets = await choiceSets.getAll();
+     * // Tenant-only (default)
+     * const tenantChoiceSets = await choiceSets.getAll();
      *
-     * // Iterate through choice sets
-     * allChoiceSets.forEach(choiceSet => {
-     *   console.log(`ChoiceSet: ${choiceSet.displayName} (${choiceSet.name})`);
-     *   console.log(`Description: ${choiceSet.description}`);
-     * });
+     * // A single folder's choice sets (preferred when targeting a specific folder)
+     * const folderChoiceSets = await choiceSets.getAll({ folderKey: "<folderKey>" });
+     *
+     * // Tenant + folder choice sets together
+     * const allChoiceSets = await choiceSets.getAll({ includeFolderChoiceSets: true });
      * ```
      */
-    async getAll() {
-        const rawResponse = await this.get(DATA_FABRIC_ENDPOINTS.CHOICESETS.GET_ALL);
+    async getAll(options) {
+        return this.fetchAllChoiceSets(options);
+    }
+    /**
+     * Internal helper that performs the choice-set fetch. Kept separate from the
+     * public `getAll()` so that internal callers (e.g. `resolveChoiceSetName`)
+     * can reuse it without triggering double `@track` telemetry.
+     */
+    async fetchAllChoiceSets(options) {
+        // The choice-set endpoint returns cross-scope results when called without
+        // a folder header. To stay tenant-only by default, send the tenant-marker
+        // UUID as the folder key unless the caller explicitly opts into cross-scope
+        // via includeFolderChoiceSets: true. folderKey is preferred over
+        // includeFolderChoiceSets when both are set.
+        const folderKey = options?.folderKey
+            ?? (options?.includeFolderChoiceSets ? undefined : DATA_FABRIC_TENANT_FOLDER_ID);
+        const rawResponse = await this.get(DATA_FABRIC_ENDPOINTS.CHOICESETS.GET_ALL, { headers: createHeaders({ [FOLDER_KEY]: folderKey }) });
         // Transform field names
         const data = rawResponse.data || [];
         return data.map(choiceSet => transformData(choiceSet, EntityMap));
@@ -9386,7 +9568,7 @@ class ChoiceSetService extends BaseService {
      * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
      *
      * @param choiceSetId - UUID of the choice set
-     * @param options - Pagination options
+     * @param options - Pagination options and optional `folderKey` for folder-scoped choice sets The `folderKey` property is **experimental**.
      * @returns Promise resolving to choice set values or paginated result
      *
      * @example
@@ -9415,6 +9597,9 @@ class ChoiceSetService extends BaseService {
      * if (page1.hasNextPage) {
      *   const page2 = await choiceSets.getById(choiceSetId, { cursor: page1.nextCursor });
      * }
+     *
+     * // Folder-scoped choice set
+     * const folderValues = await choiceSets.getById(choiceSetId, { folderKey: "<folderKey>" });
      * ```
      */
     async getById(choiceSetId, options) {
@@ -9423,11 +9608,16 @@ class ChoiceSetService extends BaseService {
             const camelCased = pascalToCamelCaseKeys(item);
             return transformData(camelCased, EntityMap);
         };
+        // folderKey is header-only — destructure it out so PaginationHelpers doesn't
+        // include it in the POST body alongside pagination params.
+        const { folderKey, ...rest } = options ?? {};
+        const downstreamOptions = options === undefined ? undefined : rest;
         return PaginationHelpers.getAll({
             serviceAccess: this.createPaginationServiceAccess(),
             getEndpoint: () => DATA_FABRIC_ENDPOINTS.CHOICESETS.GET_BY_ID(choiceSetId),
             transformFn,
             method: HTTP_METHODS.POST,
+            headers: createHeaders({ [FOLDER_KEY]: folderKey }),
             pagination: {
                 paginationType: PaginationType.OFFSET,
                 itemsField: CHOICESET_VALUES_PAGINATION.ITEMS_FIELD,
@@ -9438,7 +9628,7 @@ class ChoiceSetService extends BaseService {
                     countParam: ENTITY_OFFSET_PARAMS.COUNT_PARAM
                 }
             }
-        }, options);
+        }, downstreamOptions);
     }
     /**
      * Creates a new Data Fabric choice set
@@ -9446,7 +9636,7 @@ class ChoiceSetService extends BaseService {
      * @param name - Choice set name. Must start with a
      *   letter, may contain only letters, numbers, and underscores, length
      *   3–100 characters (e.g., `"expenseTypes"`).
-     * @param options - Optional choice-set-level settings ({@link ChoiceSetCreateOptions})
+     * @param options - Optional choice-set-level settings ({@link ChoiceSetCreateOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving to the UUID of the created choice set
      *
      * @example
@@ -9477,7 +9667,7 @@ class ChoiceSetService extends BaseService {
                 folderId: opts.folderKey ?? DATA_FABRIC_TENANT_FOLDER_ID,
             },
         };
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.CREATE, payload);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.CREATE, payload, { headers: createHeaders({ [FOLDER_KEY]: opts.folderKey }) });
         return response.data;
     }
     /**
@@ -9487,7 +9677,7 @@ class ChoiceSetService extends BaseService {
      * the call throws `ValidationError` if both are omitted.
      *
      * @param choiceSetId - UUID of the choice set to update
-     * @param options - Metadata fields to change ({@link ChoiceSetUpdateOptions})
+     * @param options - Metadata fields to change ({@link ChoiceSetUpdateOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the update is complete
      *
      * @example
@@ -9512,12 +9702,13 @@ class ChoiceSetService extends BaseService {
         await this.patch(DATA_FABRIC_ENDPOINTS.CHOICESETS.UPDATE(choiceSetId), {
             ...(options.displayName !== undefined && { displayName: options.displayName }),
             ...(options.description !== undefined && { description: options.description }),
-        });
+        }, { headers: createHeaders({ [FOLDER_KEY]: options.folderKey }) });
     }
     /**
      * Deletes a Data Fabric choice set and all its values.
      *
      * @param choiceSetId - UUID of the choice set to delete
+     * @param options - Optional {@link ChoiceSetDeleteByIdOptions} (e.g. `folderKey` for folder-scoped choice sets) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the choice set is deleted
      *
      * @example
@@ -9527,18 +9718,21 @@ class ChoiceSetService extends BaseService {
      * const expenseTypes = allChoiceSets.find(cs => cs.name === 'expense_types');
      *
      * await choicesets.deleteById(expenseTypes.id);
+     *
+     * // Folder-scoped choice set
+     * await choicesets.deleteById(expenseTypes.id, { folderKey: "<folderKey>" });
      * ```
      * @internal
      */
-    async deleteById(choiceSetId) {
-        await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.DELETE(choiceSetId), {});
+    async deleteById(choiceSetId, options) {
+        await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.DELETE(choiceSetId), {}, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
     }
     /**
      * Inserts a single value into a choice set.
      *
      * @param choiceSetId - UUID of the parent choice set
      * @param name - Identifier name of the new value (e.g., `"TRAVEL"`)
-     * @param options - Optional fields ({@link ChoiceSetValueInsertOptions})
+     * @param options - Optional fields ({@link ChoiceSetValueInsertOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving to the inserted value ({@link ChoiceSetValueInsertResponse})
      *
      * @example
@@ -9551,16 +9745,22 @@ class ChoiceSetService extends BaseService {
      *   displayName: 'Travel',
      * });
      * console.log(inserted.id);
+     *
+     * // Folder-scoped choice set: folderKey is required on the wire
+     * await choicesets.insertValueById(expenseTypes.id, 'TRAVEL', {
+     *   displayName: 'Travel',
+     *   folderKey: "<folderKey>",
+     * });
      * ```
      * @internal
      */
     async insertValueById(choiceSetId, name, options) {
-        const choiceSetName = await this.resolveChoiceSetName(choiceSetId);
+        const choiceSetName = await this.resolveChoiceSetName(choiceSetId, options?.folderKey);
         const payload = {
             Name: name,
             ...(options?.displayName !== undefined && { DisplayName: options.displayName }),
         };
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.INSERT_BY_NAME(choiceSetName), payload);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.INSERT_BY_NAME(choiceSetName), payload, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         const camelCased = pascalToCamelCaseKeys(response.data);
         return transformData(camelCased, EntityMap);
     }
@@ -9573,6 +9773,7 @@ class ChoiceSetService extends BaseService {
      * @param choiceSetId - UUID of the parent choice set
      * @param valueId - UUID of the value to update
      * @param displayName - New human-readable display name for the value
+     * @param options - Optional {@link ChoiceSetValueUpdateOptions} — pass `folderKey` for folder-scoped choice sets; omit for tenant-level. The `folderKey` property is **experimental**.
      * @returns Promise resolving to the updated value ({@link ChoiceSetValueUpdateResponse})
      *
      * @example
@@ -9584,13 +9785,18 @@ class ChoiceSetService extends BaseService {
      * const travel = values.items.find(v => v.name === 'TRAVEL');
      *
      * await choicesets.updateValueById(expenseTypes.id, travel.id, 'Business Travel');
+     *
+     * // Folder-scoped choice set: folderKey is required on the wire
+     * await choicesets.updateValueById(expenseTypes.id, travel.id, 'Business Travel', {
+     *   folderKey: "<folderKey>",
+     * });
      * ```
      * @internal
      */
-    async updateValueById(choiceSetId, valueId, displayName) {
-        const choiceSetName = await this.resolveChoiceSetName(choiceSetId);
+    async updateValueById(choiceSetId, valueId, displayName, options) {
+        const choiceSetName = await this.resolveChoiceSetName(choiceSetId, options?.folderKey);
         const payload = { DisplayName: displayName };
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.UPDATE_BY_NAME(choiceSetName, valueId), payload);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.UPDATE_BY_NAME(choiceSetName, valueId), payload, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         const camelCased = pascalToCamelCaseKeys(response.data);
         return transformData(camelCased, EntityMap);
     }
@@ -9599,6 +9805,7 @@ class ChoiceSetService extends BaseService {
      *
      * @param choiceSetId - UUID of the parent choice set
      * @param valueIds - Array of value UUIDs to delete
+     * @param options - Optional {@link ChoiceSetValueDeleteOptions} (e.g. `folderKey` for folder-scoped choice sets) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the values are deleted
      *
      * @example
@@ -9608,14 +9815,20 @@ class ChoiceSetService extends BaseService {
      * const idsToDelete = values.items.slice(0, 2).map(v => v.id);
      *
      * await choicesets.deleteValuesById('<choiceSetId>', idsToDelete);
+     *
+     * // Folder-scoped choice set
+     * await choicesets.deleteValuesById('<choiceSetId>', idsToDelete, { folderKey: "<folderKey>" });
      * ```
      * @internal
      */
-    async deleteValuesById(choiceSetId, valueIds) {
-        await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.DELETE_BY_ID(choiceSetId), valueIds);
+    async deleteValuesById(choiceSetId, valueIds, options) {
+        await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.DELETE_BY_ID(choiceSetId), valueIds, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
     }
-    async resolveChoiceSetName(choiceSetId) {
-        const all = await this.getAll();
+    async resolveChoiceSetName(choiceSetId, folderKey) {
+        // Use the un-tracked helper directly so we don't fire a duplicate
+        // `Choicesets.GetAll` telemetry event for every insertValueById /
+        // updateValueById call.
+        const all = await this.fetchAllChoiceSets(folderKey === undefined ? undefined : { folderKey });
         const match = all.find(cs => cs.id === choiceSetId);
         if (!match) {
             throw new NotFoundError({ message: `Choice set with id '${choiceSetId}' not found.` });
@@ -11384,17 +11597,19 @@ function createTaskMethods(taskData, service) {
         async assign(options) {
             if (!taskData.id)
                 throw new Error('Task ID is undefined');
+            const criteria = options.assignmentCriteria !== undefined ? { assignmentCriteria: options.assignmentCriteria } : {};
             const assignmentOptions = 'userId' in options && options.userId !== undefined
-                ? { taskId: taskData.id, userId: options.userId }
-                : { taskId: taskData.id, userNameOrEmail: options.userNameOrEmail };
+                ? { taskId: taskData.id, userId: options.userId, ...criteria }
+                : { taskId: taskData.id, userNameOrEmail: options.userNameOrEmail, ...criteria };
             return service.assign(assignmentOptions);
         },
         async reassign(options) {
             if (!taskData.id)
                 throw new Error('Task ID is undefined');
+            const criteria = options.assignmentCriteria !== undefined ? { assignmentCriteria: options.assignmentCriteria } : {};
             const assignmentOptions = 'userId' in options && options.userId !== undefined
-                ? { taskId: taskData.id, userId: options.userId }
-                : { taskId: taskData.id, userNameOrEmail: options.userNameOrEmail };
+                ? { taskId: taskData.id, userId: options.userId, ...criteria }
+                : { taskId: taskData.id, userNameOrEmail: options.userNameOrEmail, ...criteria };
             return service.reassign(assignmentOptions);
         },
         async unassign() {
@@ -11707,6 +11922,26 @@ class TaskService extends BaseService {
      *   }
      * ]);
      * ```
+     *
+     * @example Group assignment
+     * ```typescript
+     * import { TaskAssignmentCriteria } from '@uipath/uipath-typescript/tasks';
+     *
+     * // Assign to a directory group by userId + criteria — Action Center
+     * // distributes the task across the group's members based on the criteria
+     * const result = await tasks.assign({
+     *   taskId: 123,
+     *   userId: 456, // a DirectoryGroup id from tasks.getUsers()
+     *   assignmentCriteria: TaskAssignmentCriteria.AllUsers
+     * });
+     *
+     * // ...or identify the group by name instead of id
+     * const result2 = await tasks.assign({
+     *   taskId: 123,
+     *   userNameOrEmail: "My Group",
+     *   assignmentCriteria: TaskAssignmentCriteria.AllUsers
+     * });
+     * ```
      */
     async assign(taskAssignments) {
         // Normalize input to array
@@ -11758,6 +11993,25 @@ class TaskService extends BaseService {
      *   }
      * ]);
      * ```
+     *
+     * @example Group reassignment
+     * ```typescript
+     * import { TaskAssignmentCriteria } from '@uipath/uipath-typescript/tasks';
+     *
+     * // Reassign to a directory group by userId + criteria
+     * const result = await tasks.reassign({
+     *   taskId: 123,
+     *   userId: 456, // a DirectoryGroup id from tasks.getUsers()
+     *   assignmentCriteria: TaskAssignmentCriteria.AllUsers
+     * });
+     *
+     * // ...or identify the group by name instead of id
+     * const result2 = await tasks.reassign({
+     *   taskId: 123,
+     *   userNameOrEmail: "My Group",
+     *   assignmentCriteria: TaskAssignmentCriteria.AllUsers
+     * });
+     * ```
      */
     async reassign(taskAssignments) {
         // Normalize input to array
@@ -13043,48 +13297,32 @@ class BucketService extends FolderScopedService {
             }
         }, options);
     }
-    /**
-     * Gets metadata for files in a bucket with optional filtering and pagination
-     *
-     * The method returns either:
-     * - A NonPaginatedResponse with items array (when no pagination parameters are provided)
-     * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
-     *
-     * @param bucketId - The ID of the bucket to get file metadata from
-     * @param folderId - Required folder ID for organization unit context
-     * @param options - Optional parameters for filtering, pagination and access URL generation
-     * @returns Promise resolving to the list of file metadata in the bucket or paginated result
-     *
-     * @example
-     * ```typescript
-     * import { Buckets } from '@uipath/uipath-typescript/buckets';
-     *
-     * const buckets = new Buckets(sdk);
-     *
-     * // Get metadata for all files in a bucket
-     * const fileMetadata = await buckets.getFileMetaData(123, 456);
-     *
-     * // Get file metadata with a specific prefix
-     * const fileMetadata = await buckets.getFileMetaData(123, 456, {
-     *   prefix: '/folder1'
-     * });
-     *
-     * // First page with pagination
-     * const page1 = await buckets.getFileMetaData(123, 456, { pageSize: 10 });
-     *
-     * // Navigate using cursor
-     * if (page1.hasNextPage) {
-     *   const page2 = await buckets.getFileMetaData(123, 456, { cursor: page1.nextCursor });
-     * }
-     * ```
-     */
-    async getFileMetaData(bucketId, folderId, options) {
+    async getFileMetaData(bucketId, optionsOrFolderId, legacyOptions) {
         if (!bucketId) {
             throw new ValidationError({ message: 'bucketId is required for getFileMetaData' });
         }
-        if (!folderId) {
-            throw new ValidationError({ message: 'folderId is required for getFileMetaData' });
+        // Normalize the two overload forms into a single internal shape.
+        let folderId;
+        let folderKey;
+        let folderPath;
+        let restOptions;
+        if (typeof optionsOrFolderId === 'number') {
+            // Deprecated positional form: getFileMetaData(bucketId, folderId, options?)
+            folderId = optionsOrFolderId;
+            restOptions = (legacyOptions ?? {});
         }
+        else {
+            // Preferred form: getFileMetaData(bucketId, options?)
+            const opts = optionsOrFolderId ?? {};
+            ({ folderId, folderKey, folderPath, ...restOptions } = opts);
+        }
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: 'Buckets.getFileMetaData',
+            fallbackFolderKey: this.config.folderKey,
+        });
         // Transformation function for blob items
         const transformBlobItem = (item) => transformData(item, BucketMap);
         return PaginationHelpers.getAll({
@@ -13100,93 +13338,97 @@ class BucketService extends FolderScopedService {
                     tokenParam: BUCKET_TOKEN_PARAMS.TOKEN_PARAM
                 }
             },
-            excludeFromPrefix: ['prefix'] // Bucket-specific param, not OData
-        }, { ...options, folderId });
+            excludeFromPrefix: ['prefix'], // Bucket-specific param, not OData
+            headers,
+        }, restOptions);
     }
-    /**
-     * Uploads a file to a bucket
-     *
-     * @param options - Options for file upload including bucket ID, folder ID, path, content, and optional parameters
-     * @returns Promise resolving to a response with success status and HTTP status code
-     *
-     * @example
-     * ```typescript
-     * import { Buckets } from '@uipath/uipath-typescript/buckets';
-     *
-     * const buckets = new Buckets(sdk);
-     *
-     * // Upload a file from browser
-     * const file = new File(['file content'], 'example.txt');
-     * const result = await buckets.uploadFile({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/example.txt',
-     *   content: file
-     * });
-     *
-     * // In Node env with Buffer
-     * const buffer = Buffer.from('file content');
-     * const result = await buckets.uploadFile({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/example.txt',
-     *   content: buffer
-     * });
-     * ```
-     */
-    async uploadFile(options) {
-        const { bucketId, folderId, path, content } = options;
+    async uploadFile(bucketIdOrOptions, path, content, options) {
+        // Normalize the two overload forms into a single internal shape.
+        let bucketId;
+        let resolvedPath;
+        let resolvedContent;
+        let folderId;
+        let folderKey;
+        let folderPath;
+        if (bucketIdOrOptions !== null && typeof bucketIdOrOptions === 'object') {
+            // Deprecated options-only form: uploadFile({ bucketId, path, content, ... })
+            ({ bucketId, path: resolvedPath, content: resolvedContent, folderId, folderKey, folderPath } = bucketIdOrOptions);
+        }
+        else {
+            // Preferred positional form: uploadFile(bucketId, path, content, options?)
+            bucketId = bucketIdOrOptions;
+            resolvedPath = path;
+            resolvedContent = content;
+            const opts = options ?? {};
+            ({ folderId, folderKey, folderPath } = opts);
+        }
         if (!bucketId) {
             throw new ValidationError({ message: 'bucketId is required for uploadFile' });
         }
-        if (!folderId) {
-            throw new ValidationError({ message: 'folderId is required for uploadFile' });
-        }
-        if (!path) {
+        if (!resolvedPath) {
             throw new ValidationError({ message: 'path is required for uploadFile' });
         }
-        if (!content) {
+        if (!resolvedContent) {
             throw new ValidationError({ message: 'content is required for uploadFile' });
         }
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: 'Buckets.uploadFile',
+            fallbackFolderKey: this.config.folderKey,
+        });
         const uriResponse = await this._getWriteUri({
             bucketId,
-            folderId,
-            path,
+            path: resolvedPath,
+            headers,
         });
         // Upload file to the provided URI
-        const response = await this._uploadToUri(uriResponse, content);
+        const response = await this._uploadToUri(uriResponse, resolvedContent);
         return {
             success: response.status >= 200 && response.status < 300,
             statusCode: response.status
         };
     }
-    /**
-     * Gets a direct download URL for a file in the bucket
-     *
-     * @param options - Contains bucketId, folderId, file path and optional expiry time
-     * @returns Promise resolving to blob file access information
-     *
-     * @example
-     * ```typescript
-     * import { Buckets } from '@uipath/uipath-typescript/buckets';
-     *
-     * const buckets = new Buckets(sdk);
-     *
-     * // Get download URL for a file
-     * const fileAccess = await buckets.getReadUri({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/file.pdf'
-     * });
-     * ```
-     */
-    async getReadUri(options) {
-        const { bucketId, folderId, path, expiryInMinutes, ...restOptions } = options;
+    async getReadUri(bucketIdOrOptions, path, options) {
+        // Normalize the two overload forms into a single internal shape.
+        let bucketId;
+        let resolvedPath;
+        let folderId;
+        let folderKey;
+        let folderPath;
+        let expiryInMinutes;
+        let restOptions;
+        if (bucketIdOrOptions !== null && typeof bucketIdOrOptions === 'object') {
+            // Deprecated options-only form: getReadUri({ bucketId, path, ... })
+            const { bucketId: bid, path: p, expiryInMinutes: e, folderId: fid, folderKey: fkey, folderPath: fpath, ...rest } = bucketIdOrOptions;
+            bucketId = bid;
+            resolvedPath = p;
+            expiryInMinutes = e;
+            folderId = fid;
+            folderKey = fkey;
+            folderPath = fpath;
+            restOptions = rest;
+        }
+        else {
+            // Preferred positional form: getReadUri(bucketId, path, options?)
+            bucketId = bucketIdOrOptions;
+            resolvedPath = path;
+            const opts = options ?? {};
+            ({ expiryInMinutes, folderId, folderKey, folderPath, ...restOptions } = opts);
+        }
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: 'Buckets.getReadUri',
+            fallbackFolderKey: this.config.folderKey,
+        });
         const queryOptions = {
             expiryInMinutes,
             ...addPrefixToKeys(restOptions, ODATA_PREFIX, Object.keys(restOptions))
         };
-        return this._getUri(BUCKET_ENDPOINTS.GET_READ_URI(bucketId), bucketId, folderId, path, queryOptions);
+        return this._getUri(BUCKET_ENDPOINTS.GET_READ_URI(bucketId), bucketId, resolvedPath, headers, queryOptions);
     }
     /**
      * Uploads content to the provided URI
@@ -13216,23 +13458,18 @@ class BucketService extends FolderScopedService {
      * Private method to handle common URI request logic
      * @param endpoint - The API endpoint to call
      * @param bucketId - The bucket ID
-     * @param folderId - The folder ID
      * @param path - The file path
+     * @param headers - Pre-built folder-context headers (built via `resolveFolderHeaders`)
      * @param queryOptions - Additional query parameters
      * @returns Promise resolving to blob file access information
      */
-    async _getUri(endpoint, bucketId, folderId, path, queryOptions = {}) {
+    async _getUri(endpoint, bucketId, path, headers, queryOptions = {}) {
         if (!bucketId) {
             throw new ValidationError({ message: 'bucketId is required for getUri' });
         }
-        if (!folderId) {
-            throw new ValidationError({ message: 'folderId is required for getUri' });
-        }
         if (!path) {
             throw new ValidationError({ message: 'path is required for getUri' });
         }
-        // Create headers with required folder ID
-        const headers = createHeaders({ [FOLDER_ID]: folderId });
         // Filter out undefined values and build query params
         const queryParams = filterUndefined({
             path,
@@ -13367,16 +13604,16 @@ class BucketService extends FolderScopedService {
     /**
      * Gets a direct upload URL for a file in the bucket
      *
-     * @param options - Contains bucketId, folderId, file path, optional expiry time
+     * @param options - Contains bucketId, file path, optional expiry time, and pre-built folder-context headers
      * @returns Promise resolving to blob file access information
      */
     async _getWriteUri(options) {
-        const { bucketId, folderId, path, expiryInMinutes, ...restOptions } = options;
+        const { bucketId, path, expiryInMinutes, headers, ...restOptions } = options;
         const queryOptions = {
             expiryInMinutes,
             ...addPrefixToKeys(restOptions, ODATA_PREFIX, Object.keys(restOptions))
         };
-        return this._getUri(BUCKET_ENDPOINTS.GET_WRITE_URI(bucketId), bucketId, folderId, path, queryOptions);
+        return this._getUri(BUCKET_ENDPOINTS.GET_WRITE_URI(bucketId), bucketId, path, headers, queryOptions);
     }
 }
 __decorate([
@@ -14840,6 +15077,24 @@ exports.AgentListSortColumn = void 0;
     AgentListSortColumn["QuantityPLTU"] = "QuantityPLTU";
     AgentListSortColumn["FolderPath"] = "FolderPath";
 })(exports.AgentListSortColumn || (exports.AgentListSortColumn = {}));
+/**
+ * Columns available for ordering / grouping the agent errors list.
+ */
+exports.AgentErrorSortColumn = void 0;
+(function (AgentErrorSortColumn) {
+    AgentErrorSortColumn["AgentId"] = "AgentId";
+    AgentErrorSortColumn["AgentName"] = "AgentName";
+    AgentErrorSortColumn["ParentProcessName"] = "ParentProcessName";
+    AgentErrorSortColumn["ErrorTitle"] = "ErrorTitle";
+    AgentErrorSortColumn["FirstSeenStartTime"] = "FirstSeenStartTime";
+    AgentErrorSortColumn["ExecutionCount"] = "ExecutionCount";
+    AgentErrorSortColumn["Type"] = "Type";
+    AgentErrorSortColumn["FirstSeenFolderName"] = "FirstSeenFolderName";
+    AgentErrorSortColumn["FirstSeenFolderPath"] = "FirstSeenFolderPath";
+    AgentErrorSortColumn["LastSeenStartTime"] = "LastSeenStartTime";
+    AgentErrorSortColumn["LastSeenFolderName"] = "LastSeenFolderName";
+    AgentErrorSortColumn["LastSeenFolderPath"] = "LastSeenFolderPath";
+})(exports.AgentErrorSortColumn || (exports.AgentErrorSortColumn = {}));
 
 /**
  * Types for the Agent Memory metrics service.
@@ -15144,6 +15399,86 @@ exports.PolicyEvaluationResult = void 0;
     PolicyEvaluationResult["SimulatedDeny"] = "SimulatedDeny";
 })(exports.PolicyEvaluationResult || (exports.PolicyEvaluationResult = {}));
 
+/** Status of a span: whether it completed successfully, with an error, or was not set. */
+exports.SpanStatus = void 0;
+(function (SpanStatus) {
+    SpanStatus["Unset"] = "Unset";
+    SpanStatus["Ok"] = "Ok";
+    SpanStatus["Error"] = "Error";
+    /** Span is still in progress. */
+    SpanStatus["Running"] = "Running";
+    /** Span data is hidden from the caller due to tenant/folder permission rules. */
+    SpanStatus["Restricted"] = "Restricted";
+    /** Span was cancelled before completion. */
+    SpanStatus["Cancelled"] = "Cancelled";
+})(exports.SpanStatus || (exports.SpanStatus = {}));
+/** Platform source that produced the span. */
+exports.SpanSource = void 0;
+(function (SpanSource) {
+    SpanSource["Testing"] = "Testing";
+    SpanSource["Agents"] = "Agents";
+    SpanSource["ProcessOrchestration"] = "ProcessOrchestration";
+    SpanSource["ApiWorkflows"] = "ApiWorkflows";
+    SpanSource["Robots"] = "Robots";
+    SpanSource["ConversationalAgentsService"] = "ConversationalAgentsService";
+    SpanSource["IntegrationServiceTrigger"] = "IntegrationServiceTrigger";
+    SpanSource["Playground"] = "Playground";
+    SpanSource["Governance"] = "Governance";
+    /** Intelligent Experience Platform — unstructured and complex document processing source. */
+    SpanSource["IXPUnstructuredAndComplexDocuments"] = "IXPUnstructuredAndComplexDocuments";
+    /** Agents authored in code (as opposed to visual/no-code designers). */
+    SpanSource["CodedAgents"] = "CodedAgents";
+    /** Intelligent Experience Platform — communications mining source. */
+    SpanSource["IXPCommunicationsMining"] = "IXPCommunicationsMining";
+    /** UiPath Context Grounding — span produced by the Enterprise Context Service for RAG/knowledge-base operations. */
+    SpanSource["EnterpriseContextService"] = "EnterpriseContextService";
+    /** Model Context Protocol — span produced by an MCP server integration. */
+    SpanSource["MCP"] = "MCP";
+    /** Agent-to-Agent — span produced by an A2A protocol call between agents. */
+    SpanSource["A2A"] = "A2A";
+    /** Serverless — span produced by a serverless function execution. */
+    SpanSource["Serverless"] = "Serverless";
+})(exports.SpanSource || (exports.SpanSource = {}));
+/** Minimum severity level of events captured in the span. */
+exports.SpanVerbosityLevel = void 0;
+(function (SpanVerbosityLevel) {
+    SpanVerbosityLevel["Verbose"] = "Verbose";
+    SpanVerbosityLevel["Trace"] = "Trace";
+    SpanVerbosityLevel["Information"] = "Information";
+    SpanVerbosityLevel["Warning"] = "Warning";
+    SpanVerbosityLevel["Error"] = "Error";
+    SpanVerbosityLevel["Critical"] = "Critical";
+    SpanVerbosityLevel["Off"] = "Off";
+})(exports.SpanVerbosityLevel || (exports.SpanVerbosityLevel = {}));
+/** Whether the span was produced during a debug or production runtime. */
+exports.SpanExecutionType = void 0;
+(function (SpanExecutionType) {
+    SpanExecutionType["Debug"] = "Debug";
+    SpanExecutionType["Runtime"] = "Runtime";
+})(exports.SpanExecutionType || (exports.SpanExecutionType = {}));
+/** Whether the caller has permission to read this span's data. */
+exports.SpanPermissionStatus = void 0;
+(function (SpanPermissionStatus) {
+    SpanPermissionStatus["Allow"] = "Allow";
+    /** Some span fields are redacted due to permission constraints (e.g. attributes visible but payload hidden). */
+    SpanPermissionStatus["PartialBlock"] = "PartialBlock";
+    SpanPermissionStatus["Block"] = "Block";
+})(exports.SpanPermissionStatus || (exports.SpanPermissionStatus = {}));
+/** Storage provider that created or manages the attachment. */
+exports.SpanAttachmentProvider = void 0;
+(function (SpanAttachmentProvider) {
+    SpanAttachmentProvider["Orchestrator"] = "Orchestrator";
+    /** Span attachment stored by the observability platform. */
+    SpanAttachmentProvider["LLMOps"] = "LLMOps";
+})(exports.SpanAttachmentProvider || (exports.SpanAttachmentProvider = {}));
+/** Whether the attachment is an input, output, or neither. */
+exports.SpanAttachmentDirection = void 0;
+(function (SpanAttachmentDirection) {
+    SpanAttachmentDirection["None"] = "None";
+    SpanAttachmentDirection["In"] = "In";
+    SpanAttachmentDirection["Out"] = "Out";
+})(exports.SpanAttachmentDirection || (exports.SpanAttachmentDirection = {}));
+
 /**
  * Asset resolution utilities for UiPath Coded Apps
  *
@@ -15220,6 +15555,7 @@ function getAppBase() {
 }
 
 exports.AgentMap = AgentMap;
+exports.AgentTraceExecutionType = exports.SpanExecutionType;
 exports.AuthenticationError = AuthenticationError;
 exports.AuthorizationError = AuthorizationError;
 exports.ConversationGetAllFilterMap = ConversationGetAllFilterMap;