@uipath/uipath-typescript 1.4.0 → 1.4.2

package/dist/entities/index.d.ts

@@ -300,6 +300,24 @@ declare class BaseService {
     private determineHasMorePages;
 }
 
+/**
+ * Shared types for the Data Fabric domain — used by both Entities and ChoiceSets.
+ * Lives here (not in either service's `*.types.ts`) to avoid cross-domain coupling
+ * between sibling services.
+ */
+/**
+ * Common shape for every folder-scoped Data Fabric operation.
+ * Forwarded on the wire as the `X-UIPATH-FolderKey` header.
+ */
+interface EntityFolderScopedOptions {
+    /**
+     * Key identifying the folder the entity belongs to. Omit for tenant-level entities.
+     *
+     * @experimental Folder-scoped Data Fabric is in preview — the contract may change.
+     */
+    folderKey?: string;
+}
+
 /**
  * Entity field data type names (SQL-level types returned by the API)
  */
@@ -416,14 +434,8 @@ interface EntityDeleteOptions extends EntityFolderScopedOptions {
  */
 interface EntityDeleteRecordsOptions extends EntityDeleteOptions {
 }
-/**
- * Options for {@link EntityServiceModel.deleteRecordById}
- */
 interface EntityDeleteRecordByIdOptions extends EntityFolderScopedOptions {
 }
-/**
- * Options for {@link EntityServiceModel.importRecordsById}
- */
 interface EntityImportRecordsByIdOptions extends EntityFolderScopedOptions {
 }
 /**
@@ -590,23 +602,25 @@ interface EntityCreateFieldOptions extends EntityFieldBase {
     referenceEntityId?: string;
     /** UUID of the referenced field on the target entity (required when `type` is `RELATIONSHIP` or `FILE`) */
     referenceFieldId?: string;
+    /**
+     * Folder key of the reference target when it lives outside the source's folder. Pass `'00000000-0000-0000-0000-000000000000'` for tenant-level system targets.
+     *
+     * @experimental Folder-scoped Data Fabric is in preview — the contract may change.
+     */
+    referenceFolderKey?: string;
 }
-/**
- * Common shape for every folder-scoped Data Fabric entity operation.
- * Forwarded on the wire as the `X-UIPATH-FolderKey` header.
- */
-interface EntityFolderScopedOptions {
-    /** Key identifying the folder the entity belongs to. Omit for tenant-level entities. */
-    folderKey?: string;
+interface EntityGetAllOptions extends EntityFolderScopedOptions {
+    /**
+     * When `true`, returns tenant-level and folder-level entities together.
+     * Omit (or `false`, the default) to return only tenant-level entities.
+     * Ignored when `folderKey` is provided — `folderKey` is preferred over `includeFolderEntities` when both are set.
+     *
+     * @experimental Folder-scoped Data Fabric is in preview — the contract may change.
+     */
+    includeFolderEntities?: boolean;
 }
-/**
- * Options for {@link EntityServiceModel.getById}
- */
 interface EntityGetByIdOptions extends EntityFolderScopedOptions {
 }
-/**
- * Options for {@link EntityServiceModel.deleteById}
- */
 interface EntityDeleteByIdOptions extends EntityFolderScopedOptions {
 }
 /**
@@ -951,23 +965,35 @@ interface RawEntityGetResponse {
  */
 interface EntityServiceModel {
     /**
-     * Gets all entities in the system
+     * Gets entities in the tenant.
      *
-     * @returns Promise resolving to either an array of entities NonPaginatedResponse<EntityGetResponse> or a PaginatedResponse<EntityGetResponse> when pagination options are used.
+     * 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
      * {@link EntityGetResponse}
      * @example
      * ```typescript
-     * // 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 });
      *
      * // Iterate through entities
-     * allEntities.forEach(entity => {
+     * tenantEntities.forEach(entity => {
      *   console.log(`Entity: ${entity.displayName} (${entity.name})`);
      *   console.log(`Type: ${entity.entityType}`);
      * });
      *
      * // Find a specific entity by name
-     * const customerEntity = allEntities.find(e => e.name === 'Customer');
+     * const customerEntity = tenantEntities.find(e => e.name === 'Customer');
      *
      * // Use entity methods directly
      * if (customerEntity) {
@@ -985,12 +1011,12 @@ interface EntityServiceModel {
      * }
      * ```
      */
-    getAll(): Promise<EntityGetResponse[]>;
+    getAll(options?: EntityGetAllOptions): Promise<EntityGetResponse[]>;
     /**
      * 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 operation methods
      * {@link EntityGetResponse}
      * @example
@@ -1030,7 +1056,7 @@ interface EntityServiceModel {
      * Gets entity records by entity ID
      *
      * @param entityId - UUID of the entity
-     * @param options - Query options
+     * @param options - Query options The `folderKey` property is **experimental**.
      * @returns Promise resolving to either an array of entity records NonPaginatedResponse<EntityRecord> or a PaginatedResponse<EntityRecord> when pagination options are used.
      * {@link EntityRecord}
      * @example
@@ -1054,6 +1080,9 @@ interface EntityServiceModel {
      *   cursor: paginatedResponse.nextCursor,
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * const records = await entities.getAllRecords("<entityId>", { folderKey: "<folderKey>" });
      * ```
      */
     getAllRecords<T extends EntityGetAllRecordsOptions = EntityGetAllRecordsOptions>(entityId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<EntityRecord> : NonPaginatedResponse<EntityRecord>>;
@@ -1067,7 +1096,7 @@ interface EntityServiceModel {
      *
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record
-     * @param options - Query options
+     * @param options - Query options The `folderKey` property is **experimental**.
      * @returns Promise resolving to a single entity record
      * {@link EntityRecord}
      * @example
@@ -1083,6 +1112,11 @@ interface EntityServiceModel {
      * const record = await entities.getRecordById(<entityId>, recordId, {
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * const record = await entities.getRecordById(<entityId>, recordId, {
+     *   folderKey: "<folderKey>"
+     * });
      * ```
      */
     getRecordById(entityId: string, recordId: string, options?: EntityGetRecordByIdOptions): Promise<EntityRecord>;
@@ -1094,7 +1128,7 @@ interface EntityServiceModel {
      *
      * @param id - 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
      * {@link EntityInsertResponse}
      * @example
@@ -1106,6 +1140,11 @@ interface EntityServiceModel {
      * 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>"
+     * });
      * ```
      */
     insertRecordById(id: string, data: Record<string, any>, options?: EntityInsertRecordOptions): Promise<EntityInsertResponse>;
@@ -1122,7 +1161,7 @@ interface EntityServiceModel {
      *
      * @param id - 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
      * {@link EntityBatchInsertResponse}
      * @example
@@ -1141,6 +1180,12 @@ interface EntityServiceModel {
      *   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>" });
      * ```
      */
     insertRecordsById(id: string, data: Record<string, any>[], options?: EntityInsertRecordsOptions): Promise<EntityBatchInsertResponse>;
@@ -1158,7 +1203,7 @@ interface EntityServiceModel {
      * @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
      * {@link EntityUpdateRecordResponse}
      * @example
@@ -1170,6 +1215,11 @@ interface EntityServiceModel {
      * 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>"
+     * });
      * ```
      */
     updateRecordById(entityId: string, recordId: string, data: Record<string, any>, options?: EntityUpdateRecordOptions): Promise<EntityUpdateRecordResponse>;
@@ -1180,7 +1230,7 @@ interface EntityServiceModel {
      *
      * @param id - UUID of the entity
      * @param data - Array of records to update. Each record MUST contain the record id.
-     * @param options - Update options
+     * @param options - Update options The `folderKey` property is **experimental**.
      * @returns Promise resolving to update response
      * {@link EntityUpdateResponse}
      * @example
@@ -1199,6 +1249,11 @@ interface EntityServiceModel {
      *   expansionLevel: 1,
      *   failOnFirst: true
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.updateRecordsById(<entityId>, [
+     *   { Id: "123", name: "John Updated" }
+     * ], { folderKey: "<folderKey>" });
      * ```
      */
     updateRecordsById(id: string, data: EntityRecord[], options?: EntityUpdateRecordsOptions): Promise<EntityUpdateResponse>;
@@ -1209,7 +1264,7 @@ interface EntityServiceModel {
      *
      * @param id - 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
      * {@link EntityDeleteResponse}
      * @example
@@ -1218,6 +1273,11 @@ interface EntityServiceModel {
      * 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>" });
      * ```
      */
     deleteRecordsById(id: string, recordIds: string[], options?: EntityDeleteRecordsOptions): Promise<EntityDeleteResponse>;
@@ -1229,7 +1289,7 @@ interface EntityServiceModel {
      *
      * @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
@@ -1248,7 +1308,7 @@ interface EntityServiceModel {
      * Queries entity records with filters, sorting, aggregates, and SDK-managed 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
      * @example
@@ -1282,6 +1342,12 @@ interface EntityServiceModel {
      *   ],
      * });
      *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.queryRecordsById(<id>, {
+     *   filterGroup: { queryFilters: [{ fieldName: "status", operator: QueryFilterOperator.Equals, value: "active" }] },
+     *   folderKey: "<folderKey>",
+     * });
+     *
      * // Aggregate: total sum and average across all records (no grouping)
      * await entities.queryRecordsById(<id>, {
      *   aggregates: [
@@ -1297,7 +1363,7 @@ interface EntityServiceModel {
      *
      * @param id - UUID of the entity
      * @param file - CSV file to import as a Blob or 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 {@link EntityImportRecordsResponse} with record counts
      * @example
      * ```typescript
@@ -1317,7 +1383,7 @@ interface EntityServiceModel {
      * @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
      * ```typescript
@@ -1374,7 +1440,7 @@ interface EntityServiceModel {
      * @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
      * ```typescript
@@ -1411,7 +1477,7 @@ interface EntityServiceModel {
      * @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
      * ```typescript
@@ -1442,7 +1508,7 @@ interface EntityServiceModel {
      * @param name - Entity name — must start with a letter, letters/numbers/underscores only
      *   (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
      * ```typescript
@@ -1461,6 +1527,24 @@ interface EntityServiceModel {
      *   { 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
      */
@@ -1469,7 +1553,7 @@ interface EntityServiceModel {
      * 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
      * ```typescript
@@ -1489,7 +1573,7 @@ interface EntityServiceModel {
      * only when the corresponding fields are provided.
      *
      * @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
@@ -1607,7 +1691,7 @@ interface EntityMethods {
     /**
      * Get all records from this entity
      *
-     * @param options - Query options
+     * @param options - Query options The `folderKey` property is **experimental**.
      * @returns Promise resolving to query response
      */
     getAllRecords<T extends EntityGetAllRecordsOptions = EntityGetAllRecordsOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<EntityRecord> : NonPaginatedResponse<EntityRecord>>;
@@ -1624,7 +1708,7 @@ interface EntityMethods {
      *
      * @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)
+     * @param options - Optional {@link EntityDownloadAttachmentOptions} (e.g. folderKey) The `folderKey` property is **experimental**.
      * @returns Promise resolving to Blob containing the file content
      */
     downloadAttachment(recordId: string, fieldName: string, options?: EntityDownloadAttachmentOptions): Promise<Blob>;
@@ -1634,7 +1718,7 @@ interface EntityMethods {
      * @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)
+     * @param options - Optional {@link EntityUploadAttachmentOptions} (e.g. expansionLevel, folderKey) The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link EntityUploadAttachmentResponse}
      */
     uploadAttachment(recordId: string, fieldName: string, file: EntityFileType, options?: EntityUploadAttachmentOptions): Promise<EntityUploadAttachmentResponse>;
@@ -1643,7 +1727,7 @@ interface EntityMethods {
      *
      * @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)
+     * @param options - Optional {@link EntityDeleteAttachmentOptions} (e.g. folderKey) The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link EntityDeleteAttachmentResponse}
      */
     deleteAttachment(recordId: string, fieldName: string, options?: EntityDeleteAttachmentOptions): Promise<EntityDeleteAttachmentResponse>;
@@ -1783,7 +1867,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * 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
@@ -1814,7 +1898,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * 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
@@ -1842,6 +1926,9 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *   cursor: paginatedResponse.nextCursor,
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * const records = await entities.getAllRecords("<entityId>", { folderKey: "<folderKey>" });
      * ```
      */
     getAllRecords<T extends EntityGetAllRecordsOptions = EntityGetAllRecordsOptions>(entityId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<EntityRecord> : NonPaginatedResponse<EntityRecord>>;
@@ -1850,7 +1937,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *
      * @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
@@ -1862,6 +1949,11 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * 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>"
+     * });
      * ```
      */
     getRecordById(entityId: string, recordId: string, options?: EntityGetRecordByIdOptions): Promise<EntityRecord>;
@@ -1870,7 +1962,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *
      * @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
@@ -1886,6 +1978,11 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * 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>"
+     * });
      * ```
      */
     insertRecordById(id: string, data: Record<string, any>, options?: EntityInsertRecordOptions): Promise<EntityInsertResponse>;
@@ -1894,7 +1991,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *
      * @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
@@ -1917,6 +2014,12 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *   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>" });
      * ```
      */
     insertRecordsById(id: string, data: Record<string, any>[], options?: EntityInsertRecordsOptions): Promise<EntityBatchInsertResponse>;
@@ -1926,7 +2029,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * @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
@@ -1942,6 +2045,11 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * 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>"
+     * });
      * ```
      */
     updateRecordById(entityId: string, recordId: string, data: Record<string, any>, options?: EntityUpdateRecordOptions): Promise<EntityUpdateRecordResponse>;
@@ -1951,7 +2059,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * @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
@@ -1974,6 +2082,11 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *   expansionLevel: 1,
      *   failOnFirst: true
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.updateRecordsById("<entityId>", [
+     *   { Id: "123", name: "John Updated" }
+     * ], { folderKey: "<folderKey>" });
      * ```
      */
     updateRecordsById(id: string, data: EntityRecord[], options?: EntityUpdateRecordsOptions): Promise<EntityUpdateResponse>;
@@ -1984,7 +2097,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *
      * @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
@@ -1997,6 +2110,11 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * 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>" });
      * ```
      */
     deleteRecordsById(id: string, recordIds: string[], options?: EntityDeleteRecordsOptions): Promise<EntityDeleteResponse>;
@@ -2008,7 +2126,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *
      * @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
@@ -2024,8 +2142,14 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      */
     deleteRecordById(entityId: string, recordId: string, options?: EntityDeleteRecordByIdOptions): Promise<void>;
     /**
-     * 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
@@ -2034,19 +2158,25 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *
      * 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();
      * ```
      */
-    getAll(): Promise<EntityGetResponse[]>;
+    getAll(options?: EntityGetAllOptions): Promise<EntityGetResponse[]>;
     /**
      * 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
      *
@@ -2093,6 +2223,12 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *     { 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>",
+     * });
      * ```
      */
     queryRecordsById<T extends EntityQueryRecordsOptions = EntityQueryRecordsOptions>(id: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<EntityRecord> : NonPaginatedResponse<EntityRecord>>;
@@ -2101,7 +2237,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *
      * @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
@@ -2134,7 +2270,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * @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
@@ -2166,7 +2302,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * @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
@@ -2197,7 +2333,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * @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
@@ -2243,7 +2379,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * @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
@@ -2259,6 +2395,24 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      *   { 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
      */
@@ -2267,7 +2421,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * 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
@@ -2292,7 +2446,7 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * 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
@@ -2375,6 +2529,8 @@ declare class EntityService extends BaseService implements EntityServiceModel {
      * @private
      */
     private mapExternalFields;
+    private buildFieldsWithReferenceMeta;
+    private buildReferenceMeta;
     /** Converts a user-facing EntityCreateFieldOptions to the raw API field payload */
     private buildSchemaFieldPayload;
     /**
@@ -2448,40 +2604,54 @@ interface ChoiceSetGetResponse {
     /** User ID of the record owner */
     recordOwner?: string;
 }
+interface ChoiceSetGetAllOptions extends EntityFolderScopedOptions {
+    /**
+     * When `true`, also returns folder-level choice sets alongside tenant ones.
+     * Omit (or `false`, the default) to return only tenant-level choice sets.
+     * Ignored when `folderKey` is provided — `folderKey` is preferred over `includeFolderChoiceSets` when both are set.
+     *
+     * @experimental Folder-scoped Data Fabric is in preview — the contract may change.
+     */
+    includeFolderChoiceSets?: boolean;
+}
 /**
  * Options for getting choice set values by choice set ID
  */
-type ChoiceSetGetByIdOptions = PaginationOptions;
+type ChoiceSetGetByIdOptions = PaginationOptions & EntityFolderScopedOptions;
 /**
  * Options for creating a new choice set
  */
-interface ChoiceSetCreateOptions {
+interface ChoiceSetCreateOptions extends EntityFolderScopedOptions {
     /** Human-readable display name */
     displayName?: string;
     /** Optional choice set description */
     description?: string;
-    /** UUID of the folder to place the choice set in (defaults to the tenant-level folder) */
-    folderKey?: string;
 }
 /**
  * Options for updating an existing choice set's metadata
  */
-interface ChoiceSetUpdateOptions {
+interface ChoiceSetUpdateOptions extends EntityFolderScopedOptions {
     /** New display name for the choice set */
     displayName?: string;
     /** New description for the choice set */
     description?: string;
 }
+interface ChoiceSetDeleteByIdOptions extends EntityFolderScopedOptions {
+}
 /**
  * Optional fields when inserting a single value into a choice set.
  *
  * The required `name` identifier is passed as a positional argument to
  * `insertValueById`.
  */
-interface ChoiceSetValueInsertOptions {
+interface ChoiceSetValueInsertOptions extends EntityFolderScopedOptions {
     /** Human-readable display name */
     displayName?: string;
 }
+interface ChoiceSetValueUpdateOptions extends EntityFolderScopedOptions {
+}
+interface ChoiceSetValueDeleteOptions extends EntityFolderScopedOptions {
+}
 /**
  * Response returned after inserting a choice-set value — the full value object.
  */
@@ -2511,33 +2681,32 @@ interface ChoiceSetValueUpdateResponse extends ChoiceSetGetResponse {
  */
 interface ChoiceSetServiceModel {
     /**
-     * Gets all choice sets in the org
+     * 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
      * {@link ChoiceSetGetAllResponse}
      * @example
      * ```typescript
-     * // 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}`);
-     *   console.log(`Created by: ${choiceSet.createdBy}`);
-     * });
+     * // A single folder's choice sets (preferred when targeting a specific folder)
+     * const folderChoiceSets = await choicesets.getAll({ folderKey: "<folderKey>" });
      *
-     * // Find a specific choice set by name
-     * const expenseTypes = allChoiceSets.find(cs => cs.name === 'ExpenseTypes');
+     * // Tenant + folder choice sets together
+     * const allChoiceSets = await choicesets.getAll({ includeFolderChoiceSets: true });
      *
-     * // Check choice set details
-     * if (expenseTypes) {
-     *   console.log(`Last updated: ${expenseTypes.updatedTime}`);
-     *   console.log(`Updated by: ${expenseTypes.updatedBy}`);
-     * }
+     * // Find a specific choice set by name
+     * const expenseTypes = tenantChoiceSets.find(cs => cs.name === 'ExpenseTypes');
      * ```
      */
-    getAll(): Promise<ChoiceSetGetAllResponse[]>;
+    getAll(options?: ChoiceSetGetAllOptions): Promise<ChoiceSetGetAllResponse[]>;
     /**
      * Gets choice set values by choice set ID with optional pagination
      *
@@ -2546,7 +2715,7 @@ interface ChoiceSetServiceModel {
      * - 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` (omit for tenant-level choice sets) The `folderKey` property is **experimental**.
      * @returns Promise resolving to choice set values or paginated result
      * {@link ChoiceSetGetResponse}
      * @example
@@ -2571,6 +2740,9 @@ interface ChoiceSetServiceModel {
      * if (page1.hasNextPage) {
      *   const page2 = await choicesets.getById(choiceSetId, { cursor: page1.nextCursor });
      * }
+     *
+     * // Folder-scoped choice set
+     * const folderValues = await choicesets.getById(choiceSetId, { folderKey: "<folderKey>" });
      * ```
      */
     getById<T extends ChoiceSetGetByIdOptions = ChoiceSetGetByIdOptions>(choiceSetId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<ChoiceSetGetResponse> : NonPaginatedResponse<ChoiceSetGetResponse>>;
@@ -2580,7 +2752,7 @@ interface ChoiceSetServiceModel {
      * @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
@@ -2604,7 +2776,7 @@ interface ChoiceSetServiceModel {
      * 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
@@ -2625,6 +2797,7 @@ interface ChoiceSetServiceModel {
      * Deletes a Data Fabric choice set and all its values.
      *
      * @param choiceSetId - UUID of the choice set to delete
+     * @param options - Optional {@link ChoiceSetDeleteByIdOptions} — pass `folderKey` for folder-scoped choice sets; omit for tenant-level The `folderKey` property is **experimental**.
      * @returns Promise resolving when the choice set is deleted
      *
      * @example
@@ -2634,16 +2807,19 @@ interface ChoiceSetServiceModel {
      * 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
      */
-    deleteById(choiceSetId: string): Promise<void>;
+    deleteById(choiceSetId: string, options?: ChoiceSetDeleteByIdOptions): Promise<void>;
     /**
      * 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
@@ -2656,6 +2832,12 @@ interface ChoiceSetServiceModel {
      *   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
      */
@@ -2669,6 +2851,7 @@ interface ChoiceSetServiceModel {
      * @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
@@ -2680,15 +2863,21 @@ interface ChoiceSetServiceModel {
      * 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
      */
-    updateValueById(choiceSetId: string, valueId: string, displayName: string): Promise<ChoiceSetValueUpdateResponse>;
+    updateValueById(choiceSetId: string, valueId: string, displayName: string, options?: ChoiceSetValueUpdateOptions): Promise<ChoiceSetValueUpdateResponse>;
     /**
      * Deletes one or more values from a choice set.
      *
      * @param choiceSetId - UUID of the parent choice set
      * @param valueIds - Array of value UUIDs to delete
+     * @param options - Optional {@link ChoiceSetValueDeleteOptions} — pass `folderKey` for folder-scoped choice sets; omit for tenant-level The `folderKey` property is **experimental**.
      * @returns Promise resolving when the values are deleted
      *
      * @example
@@ -2698,16 +2887,25 @@ interface ChoiceSetServiceModel {
      * 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
      */
-    deleteValuesById(choiceSetId: string, valueIds: string[]): Promise<void>;
+    deleteValuesById(choiceSetId: string, valueIds: string[], options?: ChoiceSetValueDeleteOptions): Promise<void>;
 }
 
 declare class ChoiceSetService extends BaseService implements ChoiceSetServiceModel {
     /**
-     * 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
@@ -2716,17 +2914,23 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      *
      * 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 });
      * ```
      */
-    getAll(): Promise<ChoiceSetGetAllResponse[]>;
+    getAll(options?: ChoiceSetGetAllOptions): Promise<ChoiceSetGetAllResponse[]>;
+    /**
+     * 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.
+     */
+    private fetchAllChoiceSets;
     /**
      * Gets choice set values by choice set ID with optional pagination
      *
@@ -2735,7 +2939,7 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * - 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
@@ -2764,6 +2968,9 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * if (page1.hasNextPage) {
      *   const page2 = await choiceSets.getById(choiceSetId, { cursor: page1.nextCursor });
      * }
+     *
+     * // Folder-scoped choice set
+     * const folderValues = await choiceSets.getById(choiceSetId, { folderKey: "<folderKey>" });
      * ```
      */
     getById<T extends ChoiceSetGetByIdOptions = ChoiceSetGetByIdOptions>(choiceSetId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<ChoiceSetGetResponse> : NonPaginatedResponse<ChoiceSetGetResponse>>;
@@ -2773,7 +2980,7 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * @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
@@ -2801,7 +3008,7 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * 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
@@ -2822,6 +3029,7 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * 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
@@ -2831,16 +3039,19 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * 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
      */
-    deleteById(choiceSetId: string): Promise<void>;
+    deleteById(choiceSetId: string, options?: ChoiceSetDeleteByIdOptions): Promise<void>;
     /**
      * 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
@@ -2853,6 +3064,12 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      *   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
      */
@@ -2866,6 +3083,7 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * @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
@@ -2877,15 +3095,21 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * 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
      */
-    updateValueById(choiceSetId: string, valueId: string, displayName: string): Promise<ChoiceSetValueUpdateResponse>;
+    updateValueById(choiceSetId: string, valueId: string, displayName: string, options?: ChoiceSetValueUpdateOptions): Promise<ChoiceSetValueUpdateResponse>;
     /**
      * Deletes one or more values from a choice set.
      *
      * @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
@@ -2895,12 +3119,15 @@ declare class ChoiceSetService extends BaseService implements ChoiceSetServiceMo
      * 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
      */
-    deleteValuesById(choiceSetId: string, valueIds: string[]): Promise<void>;
+    deleteValuesById(choiceSetId: string, valueIds: string[], options?: ChoiceSetValueDeleteOptions): Promise<void>;
     private resolveChoiceSetName;
 }
 
 export { ChoiceSetService, ChoiceSetService as ChoiceSets, DataDirectionType, EntityService as Entities, EntityAggregateFunction, EntityFieldDataType, EntityService, EntityType, FieldDisplayType, JoinType, LogicalOperator, QueryFilterOperator, ReferenceType, createEntityWithMethods };
-export type { ChoiceSetCreateOptions, ChoiceSetGetAllResponse, ChoiceSetGetByIdOptions, ChoiceSetGetResponse, ChoiceSetServiceModel, ChoiceSetUpdateOptions, ChoiceSetValueInsertOptions, ChoiceSetValueInsertResponse, ChoiceSetValueUpdateResponse, EntityAggregate, EntityBatchInsertOptions, EntityBatchInsertResponse, EntityCreateFieldOptions, EntityCreateOptions, EntityDeleteAttachmentOptions, EntityDeleteAttachmentResponse, EntityDeleteByIdOptions, EntityDeleteOptions, EntityDeleteRecordByIdOptions, EntityDeleteRecordsOptions, EntityDeleteResponse, EntityDownloadAttachmentOptions, EntityFieldBase, EntityFieldUpdateOptions, EntityFileType, EntityFolderScopedOptions, EntityGetAllRecordsOptions, EntityGetByIdOptions, EntityGetRecordByIdOptions, EntityGetRecordsByIdOptions, EntityGetResponse, EntityImportRecordsByIdOptions, EntityImportRecordsResponse, EntityInsertOptions, EntityInsertRecordOptions, EntityInsertRecordsOptions, EntityInsertResponse, EntityMethods, EntityOperationOptions, EntityOperationResponse, EntityQueryFilter, EntityQueryFilterGroup, EntityQueryRecordsOptions, EntityQueryRecordsResponse, EntityQuerySortOption, EntityRecord, EntityRemoveFieldOptions, EntityServiceModel, EntityUpdateByIdOptions, EntityUpdateOptions, EntityUpdateRecordOptions, EntityUpdateRecordResponse, EntityUpdateRecordsOptions, EntityUpdateResponse, EntityUploadAttachmentOptions, EntityUploadAttachmentResponse, ExternalConnection, ExternalField, ExternalFieldMapping, ExternalObject, ExternalSourceFields, FailureRecord, Field, FieldDataType, FieldMetaData, RawEntityGetResponse, SourceJoinCriteria, SqlType };
+export type { ChoiceSetCreateOptions, ChoiceSetDeleteByIdOptions, ChoiceSetGetAllOptions, ChoiceSetGetAllResponse, ChoiceSetGetByIdOptions, ChoiceSetGetResponse, ChoiceSetServiceModel, ChoiceSetUpdateOptions, ChoiceSetValueDeleteOptions, ChoiceSetValueInsertOptions, ChoiceSetValueInsertResponse, ChoiceSetValueUpdateOptions, ChoiceSetValueUpdateResponse, EntityAggregate, EntityBatchInsertOptions, EntityBatchInsertResponse, EntityCreateFieldOptions, EntityCreateOptions, EntityDeleteAttachmentOptions, EntityDeleteAttachmentResponse, EntityDeleteByIdOptions, EntityDeleteOptions, EntityDeleteRecordByIdOptions, EntityDeleteRecordsOptions, EntityDeleteResponse, EntityDownloadAttachmentOptions, EntityFieldBase, EntityFieldUpdateOptions, EntityFileType, EntityFolderScopedOptions, EntityGetAllOptions, EntityGetAllRecordsOptions, EntityGetByIdOptions, EntityGetRecordByIdOptions, EntityGetRecordsByIdOptions, EntityGetResponse, EntityImportRecordsByIdOptions, EntityImportRecordsResponse, EntityInsertOptions, EntityInsertRecordOptions, EntityInsertRecordsOptions, EntityInsertResponse, EntityMethods, EntityOperationOptions, EntityOperationResponse, EntityQueryFilter, EntityQueryFilterGroup, EntityQueryRecordsOptions, EntityQueryRecordsResponse, EntityQuerySortOption, EntityRecord, EntityRemoveFieldOptions, EntityServiceModel, EntityUpdateByIdOptions, EntityUpdateOptions, EntityUpdateRecordOptions, EntityUpdateRecordResponse, EntityUpdateRecordsOptions, EntityUpdateResponse, EntityUploadAttachmentOptions, EntityUploadAttachmentResponse, ExternalConnection, ExternalField, ExternalFieldMapping, ExternalObject, ExternalSourceFields, FailureRecord, Field, FieldDataType, FieldMetaData, RawEntityGetResponse, SourceJoinCriteria, SqlType };