@uipath/uipath-typescript 1.4.0 → 1.4.2

package/dist/index.umd.js

@@ -4500,6 +4500,24 @@
         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
@@ -4656,6 +4674,9 @@
     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}`,
@@ -4739,6 +4760,15 @@
             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.
@@ -9081,7 +9111,7 @@
      * SDK's public API.
      */
     /** SDK version placeholder — patched by the SDK publish workflow. */
-    const SDK_VERSION = '1.4.0';
+    const SDK_VERSION = '1.4.2';
     const CLOUD_ROLE_NAME = 'uipath-ts-sdk';
     const SDK_SERVICE_NAME = 'UiPath.TypeScript.Sdk';
     const SDK_LOGGER_NAME = 'uipath-ts-sdk-telemetry';
@@ -9261,8 +9291,8 @@
                 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;
             }
         }
@@ -10321,10 +10351,12 @@
         });
         // 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");
         }
@@ -11550,12 +11582,18 @@
          * @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,
@@ -11580,7 +11618,7 @@
          * @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;
@@ -11590,11 +11628,11 @@
             // 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
                 });
             }
@@ -11649,6 +11687,7 @@
                     headers: config.headers,
                     paginationParams: cursor ? { cursor, pageSize } : jumpToPage !== undefined ? { jumpToPage, pageSize } : { pageSize },
                     additionalParams: prefixedOptions,
+                    queryParams: config.queryParams,
                     transformFn: config.transformFn,
                     method: config.method,
                     options: {
@@ -11666,6 +11705,7 @@
                 folderId,
                 headers: config.headers,
                 additionalParams: prefixedOptions,
+                queryParams: config.queryParams,
                 transformFn: config.transformFn,
                 method: config.method,
                 options: {
@@ -11802,18 +11842,17 @@
             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
@@ -12227,6 +12266,14 @@
         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
      */
@@ -12360,7 +12407,7 @@
          * 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
@@ -12400,7 +12447,7 @@
          * 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
@@ -12428,6 +12475,9 @@
          *   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) {
@@ -12457,7 +12507,7 @@
          *
          * @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
@@ -12469,6 +12519,11 @@
          * 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 = {}) {
@@ -12483,7 +12538,7 @@
          *
          * @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
@@ -12499,6 +12554,11 @@
          * 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 = {}) {
@@ -12516,7 +12576,7 @@
          *
          * @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
@@ -12539,6 +12599,12 @@
          *   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 = {}) {
@@ -12558,7 +12624,7 @@
          * @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
@@ -12574,6 +12640,11 @@
          * 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 = {}) {
@@ -12592,7 +12663,7 @@
          * @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
@@ -12615,6 +12686,11 @@
          *   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 = {}) {
@@ -12635,7 +12711,7 @@
          *
          * @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
@@ -12648,6 +12724,11 @@
          * 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 = {}) {
@@ -12668,7 +12749,7 @@
          *
          * @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
@@ -12686,8 +12767,14 @@
             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
@@ -12696,15 +12783,29 @@
          *
          * 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
@@ -12719,7 +12820,7 @@
          * 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
          *
@@ -12766,18 +12867,24 @@
          *     { 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,
@@ -12788,7 +12895,7 @@
                         countParam: ENTITY_OFFSET_PARAMS.COUNT_PARAM
                     }
                 },
-                excludeFromPrefix: ['expansionLevel', 'filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
+                excludeFromPrefix: ['filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
             }, downstreamOptions);
         }
         /**
@@ -12796,7 +12903,7 @@
          *
          * @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
@@ -12839,7 +12946,7 @@
          * @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
@@ -12877,7 +12984,7 @@
          * @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
@@ -12922,7 +13029,7 @@
          * @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
@@ -12977,7 +13084,7 @@
          * @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
@@ -12993,17 +13100,36 @@
          *   { 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,
@@ -13017,7 +13143,7 @@
          * 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
@@ -13044,7 +13170,7 @@
          * 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
@@ -13156,10 +13282,9 @@
                     };
                 });
             }
-            // 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,
@@ -13257,8 +13382,39 @@
                 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;
@@ -13269,6 +13425,10 @@
                 });
             }
             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,
@@ -13287,7 +13447,8 @@
                 ...(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 } }),
             };
         }
@@ -13450,8 +13611,14 @@
 
     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
@@ -13460,18 +13627,33 @@
          *
          * 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));
@@ -13484,7 +13666,7 @@
          * - 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
@@ -13513,6 +13695,9 @@
          * 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) {
@@ -13521,11 +13706,16 @@
                 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,
@@ -13536,7 +13726,7 @@
                         countParam: ENTITY_OFFSET_PARAMS.COUNT_PARAM
                     }
                 }
-            }, options);
+            }, downstreamOptions);
         }
         /**
          * Creates a new Data Fabric choice set
@@ -13544,7 +13734,7 @@
          * @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
@@ -13575,7 +13765,7 @@
                     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;
         }
         /**
@@ -13585,7 +13775,7 @@
          * 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
@@ -13610,12 +13800,13 @@
             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
@@ -13625,18 +13816,21 @@
          * 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
@@ -13649,16 +13843,22 @@
          *   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);
         }
@@ -13671,6 +13871,7 @@
          * @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
@@ -13682,13 +13883,18 @@
          * 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);
         }
@@ -13697,6 +13903,7 @@
          *
          * @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
@@ -13706,14 +13913,20 @@
          * 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.` });
@@ -15482,17 +15695,19 @@
             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() {
@@ -15805,6 +16020,26 @@
          *   }
          * ]);
          * ```
+         *
+         * @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
@@ -15856,6 +16091,25 @@
          *   }
          * ]);
          * ```
+         *
+         * @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
@@ -17141,48 +17395,32 @@
                 }
             }, 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({
@@ -17198,93 +17436,97 @@
                         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
@@ -17314,23 +17556,18 @@
          * 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,
@@ -17465,16 +17702,16 @@
         /**
          * 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([
@@ -18938,6 +19175,24 @@
         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.
@@ -19242,6 +19497,86 @@
         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
      *
@@ -19318,6 +19653,7 @@
     }
 
     exports.AgentMap = AgentMap;
+    exports.AgentTraceExecutionType = exports.SpanExecutionType;
     exports.AuthenticationError = AuthenticationError;
     exports.AuthorizationError = AuthorizationError;
     exports.ConversationGetAllFilterMap = ConversationGetAllFilterMap;