@uipath/uipath-typescript 1.3.11 → 1.4.1

package/dist/entities/index.mjs

@@ -503,6 +503,7 @@ class ErrorFactory {
     }
 }
 
+const FOLDER_KEY = 'X-UIPATH-FolderKey';
 const FOLDER_ID = 'X-UIPATH-OrganizationUnitId';
 const TRACEPARENT = 'traceparent';
 const UIPATH_TRACEPARENT_ID = 'x-uipath-traceparent-id';
@@ -717,6 +718,32 @@ function filterUndefined(obj) {
  */
 const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 isBrowser && window.self != window.top && window.location.href.includes('source=ActionCenter');
+const _params = isBrowser ? new URLSearchParams(window.location.search) : null;
+/**
+ * True when the coded app has been loaded inside a host frame that explicitly
+ * opted into token delegation by adding `?host=embed` to the iframe src URL.
+ */
+const isHostEmbedded = isBrowser && window.self !== window.top && _params?.get('host') === 'embed';
+/**
+ * The validated parent origin, read from the `?basedomain=` query param set
+ * by the embedding host in the iframe src URL.
+ * Mirrors the same mechanism used by ActionCenterTokenManager.
+ * Non-null only when `?host=embed` is present and `?basedomain=` is a valid URL.
+ */
+(() => {
+    if (!isHostEmbedded)
+        return null;
+    const basedomain = _params?.get('basedomain');
+    if (!basedomain)
+        return null;
+    try {
+        return new URL(basedomain).origin;
+    }
+    catch {
+        console.warn('embeddingOrigin: basedomain query param is not a valid URL', basedomain);
+        return null;
+    }
+})();
 
 /**
  * Base64 encoding/decoding
@@ -1249,12 +1276,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,
@@ -1279,7 +1312,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;
@@ -1289,17 +1322,18 @@ 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
             });
         }
         // Extract and transform items from response
-        // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N })
-        const rawItems = Array.isArray(response.data) ? response.data : response.data?.[itemsField];
+        // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N }).
+        // itemsField may be a dotted path (e.g. 'data.agents') for nested envelopes.
+        const rawItems = Array.isArray(response.data) ? response.data : resolveNestedField(response.data, itemsField);
         const rawTotalCount = Array.isArray(response.data) ? undefined : resolveNestedField(response.data, totalCountField);
         const totalCount = typeof rawTotalCount === 'number' ? rawTotalCount : undefined;
         // Parse items - automatically handle JSON string responses
@@ -1345,8 +1379,9 @@ class PaginationHelpers {
                 getEndpoint: config.getEndpoint,
                 folderId,
                 headers: config.headers,
-                paginationParams: cursor ? { cursor, pageSize } : jumpToPage ? { jumpToPage, pageSize } : { pageSize },
+                paginationParams: cursor ? { cursor, pageSize } : jumpToPage !== undefined ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
+                queryParams: config.queryParams,
                 transformFn: config.transformFn,
                 method: config.method,
                 options: {
@@ -1364,6 +1399,7 @@ class PaginationHelpers {
             folderId,
             headers: config.headers,
             additionalParams: prefixedOptions,
+            queryParams: config.queryParams,
             transformFn: config.transformFn,
             method: config.method,
             options: {
@@ -1555,18 +1591,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
@@ -1603,6 +1638,8 @@ class BaseService {
                 // When true (default), converts pageNumber to a skip/offset value (e.g., page 3 with pageSize 10 → skip 20).
                 // When false, passes pageNumber directly as the offset param — used by APIs that accept a page number instead of a record offset.
                 const convertToSkip = paginationParams?.convertToSkip ?? true;
+                // When true, sends pageNumber - 1 (for 0-based APIs). Default false (1-based).
+                const zeroBased = paginationParams?.zeroBased ?? false;
                 requestParams[pageSizeParam] = limitedPageSize;
                 if (convertToSkip) {
                     if (params.pageNumber && params.pageNumber > 1) {
@@ -1610,7 +1647,8 @@ class BaseService {
                     }
                 }
                 else {
-                    requestParams[offsetParam] = params.pageNumber || 1;
+                    const sdkPageNumber = params.pageNumber || 1;
+                    requestParams[offsetParam] = zeroBased ? sdkPageNumber - 1 : sdkPageNumber;
                 }
                 {
                     requestParams[countParam] = true;
@@ -1639,8 +1677,9 @@ class BaseService {
         const totalCountField = fields.totalCountField || 'totalRecordCount';
         const continuationTokenField = fields.continuationTokenField || 'continuationToken';
         // Extract items and metadata
-        // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N })
-        const items = Array.isArray(response.data) ? response.data : (response.data[itemsField] || []);
+        // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N }).
+        // itemsField may be a dotted path (e.g. 'data.agents') for nested envelopes.
+        const items = Array.isArray(response.data) ? response.data : (resolveNestedField(response.data, itemsField) || []);
         const rawTotalCount = Array.isArray(response.data) ? undefined : resolveNestedField(response.data, totalCountField);
         const totalCount = typeof rawTotalCount === 'number' ? rawTotalCount : undefined;
         const continuationToken = response.data[continuationTokenField];
@@ -1723,12 +1762,12 @@ function createEntityMethods(entityData, service) {
                 throw new Error('Entity ID is undefined');
             return service.deleteRecordsById(entityData.id, recordIds, options);
         },
-        async deleteRecord(recordId) {
+        async deleteRecord(recordId, options) {
             if (!entityData.id)
                 throw new Error('Entity ID is undefined');
             if (!recordId)
                 throw new Error('Record ID is undefined');
-            return service.deleteRecordById(entityData.id, recordId);
+            return service.deleteRecordById(entityData.id, recordId, options);
         },
         async getAllRecords(options) {
             if (!entityData.id)
@@ -1742,30 +1781,30 @@ function createEntityMethods(entityData, service) {
                 throw new Error('Record ID is undefined');
             return service.getRecordById(entityData.id, recordId, options);
         },
-        async downloadAttachment(recordId, fieldName) {
+        async downloadAttachment(recordId, fieldName, options) {
             if (!entityData.id)
                 throw new Error('Entity ID is undefined');
-            return service.downloadAttachment(entityData.id, recordId, fieldName);
+            return service.downloadAttachment(entityData.id, recordId, fieldName, options);
         },
         async uploadAttachment(recordId, fieldName, file, options) {
             if (!entityData.id)
                 throw new Error('Entity ID is undefined');
             return service.uploadAttachment(entityData.id, recordId, fieldName, file, options);
         },
-        async deleteAttachment(recordId, fieldName) {
+        async deleteAttachment(recordId, fieldName, options) {
             if (!entityData.id)
                 throw new Error('Entity ID is undefined');
-            return service.deleteAttachment(entityData.id, recordId, fieldName);
+            return service.deleteAttachment(entityData.id, recordId, fieldName, options);
         },
         async queryRecords(options) {
             if (!entityData.id)
                 throw new Error('Entity ID is undefined');
             return service.queryRecordsById(entityData.id, options);
         },
-        async importRecords(file) {
+        async importRecords(file, options) {
             if (!entityData.id)
                 throw new Error('Entity ID is undefined');
-            return service.importRecordsById(entityData.id, file);
+            return service.importRecordsById(entityData.id, file, options);
         },
         async insert(data, options) {
             return this.insertRecord(data, options);
@@ -1776,10 +1815,10 @@ function createEntityMethods(entityData, service) {
         async getRecords(options) {
             return this.getAllRecords(options);
         },
-        async delete() {
+        async delete(options) {
             if (!entityData.id)
                 throw new Error('Entity ID is undefined');
-            return service.deleteById(entityData.id);
+            return service.deleteById(entityData.id, options);
         },
         async update(options) {
             if (!entityData.id)
@@ -1928,6 +1967,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}`,
@@ -2026,6 +2068,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 = {
+    [EntityType.ChoiceSet]: 1,
+};
 /**
  * Maps fields for Entities
  */
@@ -2188,6 +2238,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) The `folderKey` property is **experimental**.
      * @returns Promise resolving to entity metadata with schema information and operation methods
      *
      * @example
@@ -2197,6 +2248,9 @@ class EntityService extends BaseService {
      * const entities = new Entities(sdk);
      * const entity = await entities.getById("<entityId>");
      *
+     * // Folder-scoped: pass the entity's folder key
+     * const folderEntity = await entities.getById("<entityId>", { folderKey: "<folderKey>" });
+     *
      * // Call operations directly on the entity
      * const records = await entity.getAllRecords();
      *
@@ -2210,9 +2264,9 @@ class EntityService extends BaseService {
      * ]);
      * ```
      */
-    async getById(id) {
+    async getById(id, options) {
         // Get entity metadata
-        const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_BY_ID(id));
+        const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_BY_ID(id), { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         // Apply EntityMap transformations
         const metadata = transformData(response.data, EntityMap);
         // Transform metadata with field mappers
@@ -2224,7 +2278,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
@@ -2252,12 +2306,20 @@ 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) {
+        // folderKey is header-only — destructure it out so PaginationHelpers doesn't serialise it
+        // into the query string as $folderKey.
+        const { folderKey, ...rest } = options ?? {};
+        const downstreamOptions = options === undefined ? undefined : rest;
         return PaginationHelpers.getAll({
             serviceAccess: this.createPaginationServiceAccess(),
             getEndpoint: () => DATA_FABRIC_ENDPOINTS.ENTITY.GET_ENTITY_RECORDS(entityId),
+            headers: createHeaders({ [FOLDER_KEY]: folderKey }),
             pagination: {
                 paginationType: PaginationType.OFFSET,
                 itemsField: ENTITY_PAGINATION.ITEMS_FIELD,
@@ -2269,14 +2331,14 @@ class EntityService extends BaseService {
                 }
             },
             excludeFromPrefix: ['expansionLevel'] // Don't add ODATA prefix to expansionLevel
-        }, options);
+        }, downstreamOptions);
     }
     /**
      * Gets a single entity record by entity ID and record ID
      *
      * @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
@@ -2288,13 +2350,18 @@ 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 = {}) {
         const params = createParams({
             expansionLevel: options.expansionLevel
         });
-        const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_RECORD_BY_ID(entityId, recordId), { params });
+        const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_RECORD_BY_ID(entityId, recordId), { params, headers: createHeaders({ [FOLDER_KEY]: options.folderKey }) });
         return response.data;
     }
     /**
@@ -2302,7 +2369,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
@@ -2318,6 +2385,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 = {}) {
@@ -2326,7 +2398,7 @@ class EntityService extends BaseService {
         });
         const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.INSERT_BY_ID(id), data, {
             params,
-            ...options
+            headers: createHeaders({ [FOLDER_KEY]: options.folderKey }),
         });
         return response.data;
     }
@@ -2335,7 +2407,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
@@ -2358,6 +2430,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 = {}) {
@@ -2367,7 +2445,7 @@ class EntityService extends BaseService {
         });
         const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.BATCH_INSERT_BY_ID(id), data, {
             params,
-            ...options
+            headers: createHeaders({ [FOLDER_KEY]: options.folderKey }),
         });
         return response.data;
     }
@@ -2377,7 +2455,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
@@ -2393,6 +2471,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 = {}) {
@@ -2401,7 +2484,7 @@ class EntityService extends BaseService {
         });
         const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPDATE_RECORD_BY_ID(entityId, recordId), data, {
             params,
-            ...options
+            headers: createHeaders({ [FOLDER_KEY]: options.folderKey }),
         });
         return response.data;
     }
@@ -2411,7 +2494,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
@@ -2434,6 +2517,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 = {}) {
@@ -2443,7 +2531,7 @@ class EntityService extends BaseService {
         });
         const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPDATE_BY_ID(id), data, {
             params,
-            ...options
+            headers: createHeaders({ [FOLDER_KEY]: options.folderKey }),
         });
         return response.data;
     }
@@ -2454,7 +2542,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
@@ -2467,6 +2555,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 = {}) {
@@ -2475,7 +2568,7 @@ class EntityService extends BaseService {
         });
         const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE_BY_ID(id), recordIds, {
             params,
-            ...options
+            headers: createHeaders({ [FOLDER_KEY]: options.folderKey }),
         });
         return response.data;
     }
@@ -2487,6 +2580,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) The `folderKey` property is **experimental**.
      * @returns Promise resolving to void on success
      * @example
      * ```typescript
@@ -2495,14 +2589,23 @@ class EntityService extends BaseService {
      * const entities = new Entities(sdk);
      *
      * await entities.deleteRecordById("<entityId>", "<recordId>");
+     *
+     * // Folder-scoped: pass the entity's folder key
+     * await entities.deleteRecordById("<entityId>", "<recordId>", { folderKey: "<folderKey>" });
      * ```
      */
-    async deleteRecordById(entityId, recordId) {
-        await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE_RECORD_BY_ID(entityId, recordId));
+    async deleteRecordById(entityId, recordId, options) {
+        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
@@ -2511,15 +2614,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
@@ -2534,7 +2651,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
      *
@@ -2581,13 +2698,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; 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,
@@ -2598,14 +2726,15 @@ class EntityService extends BaseService {
                     countParam: ENTITY_OFFSET_PARAMS.COUNT_PARAM
                 }
             },
-            excludeFromPrefix: ['expansionLevel', 'filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
-        }, options);
+            excludeFromPrefix: ['filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
+        }, downstreamOptions);
     }
     /**
      * Imports records from a CSV file into an entity
      *
      * @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) The `folderKey` property is **experimental**.
      * @returns Promise resolving to import result with record counts
      *
      * @example
@@ -2626,10 +2755,12 @@ class EntityService extends BaseService {
      * if (result.errorFileLink) {
      *   console.log(`Error file link: ${result.errorFileLink}`);
      * }
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.importRecordsById("<entityId>", fileInput.files[0], { folderKey: "<folderKey>" });
      * ```
-     * @internal
      */
-    async importRecordsById(id, file) {
+    async importRecordsById(id, file, options) {
         const formData = new FormData();
         if (file instanceof Uint8Array) {
             formData.append('file', new Blob([file.buffer]));
@@ -2637,7 +2768,7 @@ class EntityService extends BaseService {
         else {
             formData.append('file', file);
         }
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.BULK_UPLOAD_BY_ID(id), formData);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.BULK_UPLOAD_BY_ID(id), formData, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         return response.data;
     }
     /**
@@ -2646,6 +2777,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) The `folderKey` property is **experimental**.
      * @returns Promise resolving to Blob containing the file content
      *
      * @example
@@ -2664,11 +2796,15 @@ class EntityService extends BaseService {
      *
      * // Download attachment for a specific record and field
      * const blob = await entities.downloadAttachment(entityId, recordId, 'Documents');
+     *
+     * // Folder-scoped: pass the entity's folder key
+     * const blob = await entities.downloadAttachment(entityId, recordId, 'Documents', { folderKey: "<folderKey>" });
      * ```
      */
-    async downloadAttachment(entityId, recordId, fieldName) {
+    async downloadAttachment(entityId, recordId, fieldName, options) {
         const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.DOWNLOAD_ATTACHMENT(entityId, recordId, fieldName), {
-            responseType: RESPONSE_TYPES.BLOB
+            responseType: RESPONSE_TYPES.BLOB,
+            headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }),
         });
         return response.data;
     }
@@ -2679,7 +2815,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)
+     * @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
@@ -2698,6 +2834,9 @@ class EntityService extends BaseService {
      *
      * // Upload a file attachment
      * const response = await entities.uploadAttachment(entityId, recordId, 'Documents', file);
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.uploadAttachment(entityId, recordId, 'Documents', file, { folderKey: "<folderKey>" });
      * ```
      */
     async uploadAttachment(entityId, recordId, fieldName, file, options) {
@@ -2709,7 +2848,10 @@ class EntityService extends BaseService {
             formData.append('file', file);
         }
         const params = createParams({ expansionLevel: options?.expansionLevel });
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPLOAD_ATTACHMENT(entityId, recordId, fieldName), formData, { params });
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPLOAD_ATTACHMENT(entityId, recordId, fieldName), formData, {
+            params,
+            headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }),
+        });
         return response.data;
     }
     /**
@@ -2718,6 +2860,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) The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link EntityDeleteAttachmentResponse}
      *
      * @example
@@ -2736,10 +2879,13 @@ class EntityService extends BaseService {
      *
      * // Delete attachment for a specific record and field
      * await entities.deleteAttachment(entityId, recordId, 'Documents');
+     *
+     * // Folder-scoped: pass the entity's folder key
+     * await entities.deleteAttachment(entityId, recordId, 'Documents', { folderKey: "<folderKey>" });
      * ```
      */
-    async deleteAttachment(entityId, recordId, fieldName) {
-        const response = await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE_ATTACHMENT(entityId, recordId, fieldName));
+    async deleteAttachment(entityId, recordId, fieldName, options) {
+        const response = await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE_ATTACHMENT(entityId, recordId, fieldName), { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         return response.data;
     }
     /**
@@ -2769,7 +2915,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
@@ -2785,40 +2931,63 @@ 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,
                 externalFields: opts.externalFields ?? [],
             },
         };
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPSERT, payload);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPSERT, payload, { headers: createHeaders({ [FOLDER_KEY]: opts.folderKey }) });
         return response.data;
     }
     /**
      * 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) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the entity is deleted
      *
      * @example
      * ```typescript
      * await entities.deleteById("<entityId>");
+     *
+     * // Folder-scoped: pass the entity's folder key
+     * await entities.deleteById("<entityId>", { folderKey: "<folderKey>" });
      * ```
      * @internal
      */
-    async deleteById(id) {
-        await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE(id));
+    async deleteById(id, options) {
+        await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE(id), { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
     }
     /**
      * Updates an existing Data Fabric entity — schema and/or metadata.
@@ -2832,7 +3001,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
@@ -2865,6 +3034,12 @@ class EntityService extends BaseService {
      *     { id: "<fieldId>", lengthLimit: 1000 },
      *   ],
      * });
+     *
+     * // Folder-scoped entity: add a field to an entity that lives in a non-tenant folder
+     * await entities.updateById("<entityId>", {
+     *   folderKey: "<folderKey>",
+     *   addFields: [{ fieldName: "notes", type: EntityFieldDataType.MULTILINE_TEXT }],
+     * });
      * ```
      * @internal
      */
@@ -2880,7 +3055,7 @@ class EntityService extends BaseService {
                 ...(opts.displayName !== undefined && { displayName: opts.displayName }),
                 ...(opts.description !== undefined && { description: opts.description }),
                 ...(opts.isRbacEnabled !== undefined && { isRbacEnabled: opts.isRbacEnabled }),
-            });
+            }, { headers: createHeaders({ [FOLDER_KEY]: opts.folderKey }) });
         }
     }
     /**
@@ -2891,7 +3066,8 @@ class EntityService extends BaseService {
      * @private
      */
     async applySchemaUpdate(entityId, options) {
-        const entityResponse = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_BY_ID(entityId));
+        const folderHeaders = createHeaders({ [FOLDER_KEY]: options.folderKey });
+        const entityResponse = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_BY_ID(entityId), { headers: folderHeaders });
         const raw = entityResponse.data;
         // Carry forward existing non-system fields from GET response (skip system/primary-key fields)
         let fields = (raw.fields ?? [])
@@ -2937,10 +3113,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,
@@ -2954,7 +3129,7 @@ class EntityService extends BaseService {
                 isInsightsEnabled: raw.isInsightsEnabled ?? false,
                 externalFields: raw.externalFields ?? [],
             },
-        });
+        }, { headers: folderHeaders });
     }
     /**
      * Orchestrates all field mapping transformations
@@ -3038,8 +3213,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: EntityType.ChoiceSet,
+                entityTypeId: ENTITY_TYPE_IDS[EntityType.ChoiceSet],
+            };
+        }
+        return meta;
+    }
     /** Converts a user-facing EntityCreateFieldOptions to the raw API field payload */
-    buildSchemaFieldPayload(field) {
+    buildSchemaFieldPayload(field, refMeta) {
         const fieldType = field.type ?? EntityFieldDataType.STRING;
         this.validateFieldConstraints(fieldType, field, field.fieldName);
         const isRelationship = fieldType === EntityFieldDataType.RELATIONSHIP;
@@ -3050,6 +3256,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,
@@ -3068,7 +3278,8 @@ class EntityService extends BaseService {
             ...(field.choiceSetId !== undefined && { choiceSetId: field.choiceSetId }),
             ...((isRelationship || isFile) && { isForeignKey: true }),
             ...(isRelationship && { referenceType: ReferenceType.ManyToOne }),
-            ...(field.referenceEntityId !== undefined && { referenceEntity: { id: field.referenceEntityId } }),
+            ...(referenceEntityBody !== undefined && { referenceEntity: referenceEntityBody }),
+            ...(referenceChoiceSetBody !== undefined && { referenceChoiceSet: referenceChoiceSetBody }),
             ...(field.referenceFieldId !== undefined && { referenceField: { id: field.referenceFieldId } }),
         };
     }
@@ -3231,8 +3442,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
@@ -3241,18 +3458,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));
@@ -3265,7 +3497,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
@@ -3294,6 +3526,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) {
@@ -3302,11 +3537,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,
@@ -3317,7 +3557,7 @@ class ChoiceSetService extends BaseService {
                     countParam: ENTITY_OFFSET_PARAMS.COUNT_PARAM
                 }
             }
-        }, options);
+        }, downstreamOptions);
     }
     /**
      * Creates a new Data Fabric choice set
@@ -3325,7 +3565,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
@@ -3356,7 +3596,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;
     }
     /**
@@ -3366,7 +3606,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
@@ -3391,12 +3631,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
@@ -3406,18 +3647,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
@@ -3430,16 +3674,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);
     }
@@ -3452,6 +3702,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
@@ -3463,13 +3714,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);
     }
@@ -3478,6 +3734,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
@@ -3487,14 +3744,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.` });