@uipath/uipath-typescript 1.3.11 → 1.4.0

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
@@ -1298,8 +1325,9 @@ class PaginationHelpers {
             });
         }
         // 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,7 +1373,7 @@ 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,
                 transformFn: config.transformFn,
                 method: config.method,
@@ -1603,6 +1631,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 +1640,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 +1670,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 +1755,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 +1774,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 +1808,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)
@@ -2188,6 +2220,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)
      * @returns Promise resolving to entity metadata with schema information and operation methods
      *
      * @example
@@ -2197,6 +2230,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 +2246,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
@@ -2255,9 +2291,14 @@ class EntityService extends BaseService {
      * ```
      */
     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,7 +2310,7 @@ 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
@@ -2294,7 +2335,7 @@ class EntityService extends BaseService {
         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;
     }
     /**
@@ -2326,7 +2367,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;
     }
@@ -2367,7 +2408,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;
     }
@@ -2401,7 +2442,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;
     }
@@ -2443,7 +2484,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;
     }
@@ -2475,7 +2516,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 +2528,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)
      * @returns Promise resolving to void on success
      * @example
      * ```typescript
@@ -2495,10 +2537,13 @@ 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
@@ -2584,10 +2629,15 @@ class EntityService extends BaseService {
      * ```
      */
     async queryRecordsById(id, options) {
+        // folderKey is header-only — destructure it out so PaginationHelpers doesn't include
+        // it in the POST body alongside the query filters.
+        const { folderKey, ...rest } = options ?? {};
+        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 }),
             pagination: {
                 paginationType: PaginationType.OFFSET,
                 itemsField: ENTITY_PAGINATION.ITEMS_FIELD,
@@ -2599,13 +2649,14 @@ class EntityService extends BaseService {
                 }
             },
             excludeFromPrefix: ['expansionLevel', 'filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
-        }, options);
+        }, 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)
      * @returns Promise resolving to import result with record counts
      *
      * @example
@@ -2626,10 +2677,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 +2690,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 +2699,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)
      * @returns Promise resolving to Blob containing the file content
      *
      * @example
@@ -2664,11 +2718,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 +2737,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)
      * @returns Promise resolving to {@link EntityUploadAttachmentResponse}
      *
      * @example
@@ -2698,6 +2756,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 +2770,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 +2782,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)
      * @returns Promise resolving to {@link EntityDeleteAttachmentResponse}
      *
      * @example
@@ -2736,10 +2801,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;
     }
     /**
@@ -2802,23 +2870,27 @@ class EntityService extends BaseService {
                 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)
      * @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.
@@ -2865,6 +2937,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 +2958,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 +2969,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 ?? [])
@@ -2954,7 +3033,7 @@ class EntityService extends BaseService {
                 isInsightsEnabled: raw.isInsightsEnabled ?? false,
                 externalFields: raw.externalFields ?? [],
             },
-        });
+        }, { headers: folderHeaders });
     }
     /**
      * Orchestrates all field mapping transformations

package/dist/feedback/index.cjs

@@ -720,6 +720,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
@@ -1209,8 +1235,9 @@ class PaginationHelpers {
             });
         }
         // 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
@@ -1256,7 +1283,7 @@ 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,
                 transformFn: config.transformFn,
                 method: config.method,
@@ -1514,6 +1541,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) {
@@ -1521,7 +1550,8 @@ class BaseService {
                     }
                 }
                 else {
-                    requestParams[offsetParam] = params.pageNumber || 1;
+                    const sdkPageNumber = params.pageNumber || 1;
+                    requestParams[offsetParam] = zeroBased ? sdkPageNumber - 1 : sdkPageNumber;
                 }
                 {
                     requestParams[countParam] = true;
@@ -1550,8 +1580,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];

package/dist/feedback/index.d.ts

@@ -107,6 +107,7 @@ interface RequestWithPaginationOptions extends RequestSpec {
             tokenParam?: string;
             countParam?: string;
             convertToSkip?: boolean;
+            zeroBased?: boolean;
         };
     };
 }

package/dist/feedback/index.mjs

@@ -718,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
@@ -1207,8 +1233,9 @@ class PaginationHelpers {
             });
         }
         // 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
@@ -1254,7 +1281,7 @@ 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,
                 transformFn: config.transformFn,
                 method: config.method,
@@ -1512,6 +1539,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) {
@@ -1519,7 +1548,8 @@ class BaseService {
                     }
                 }
                 else {
-                    requestParams[offsetParam] = params.pageNumber || 1;
+                    const sdkPageNumber = params.pageNumber || 1;
+                    requestParams[offsetParam] = zeroBased ? sdkPageNumber - 1 : sdkPageNumber;
                 }
                 {
                     requestParams[countParam] = true;
@@ -1548,8 +1578,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];