@uipath/uipath-typescript 1.3.11 → 1.4.0

package/dist/maestro-processes/index.d.ts

@@ -109,6 +109,35 @@ interface GetTopDurationResponse extends GetTopBaseResponse {
     /** Total execution duration in milliseconds */
     duration: number;
 }
+/**
+ * Element count by status for a BPMN element within a process or case
+ */
+interface ElementStats {
+    /** BPMN element identifier */
+    elementId: string;
+    /** Number of successful executions */
+    successCount: number;
+    /** Number of failed executions */
+    failCount: number;
+    /** Number of terminated executions */
+    terminatedCount: number;
+    /** Number of paused executions */
+    pausedCount: number;
+    /** Number of in-progress executions */
+    inProgressCount: number;
+    /** Minimum duration in milliseconds */
+    minDurationMs: number;
+    /** Maximum duration in milliseconds */
+    maxDurationMs: number;
+    /** Average duration in milliseconds */
+    avgDurationMs: number;
+    /** 50th percentile (median) duration in milliseconds */
+    p50DurationMs: number;
+    /** 95th percentile duration in milliseconds */
+    p95DurationMs: number;
+    /** 99th percentile duration in milliseconds */
+    p99DurationMs: number;
+}
 
 /**
  * Maestro Process Types
@@ -495,6 +524,38 @@ interface MaestroProcessesServiceModel {
      * ```
      */
     getTopExecutionDuration(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopDurationResponse[]>;
+    /**
+     * Get element stats for process instances
+     *
+     * Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
+     * duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a process.
+     *
+     * @param processKey - Process key to filter by
+     * @param packageId - Package identifier
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param packageVersion - Package version to filter by
+     * @returns Promise resolving to an array of {@link ElementStats}
+     * @example
+     * ```typescript
+     * // Get element metrics for a process
+     * const elements = await maestroProcesses.getElementStats(
+     *   '<processKey>',
+     *   '<packageId>',
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   '1.0.1'
+     * );
+     *
+     * // Analyze element performance
+     * for (const element of elements) {
+     *   console.log(`Element: ${element.elementId}`);
+     *   console.log(`  Success: ${element.successCount}, Failed: ${element.failCount}`);
+     *   console.log(`  Avg duration: ${element.avgDurationMs}ms, P95: ${element.p95DurationMs}ms`);
+     * }
+     * ```
+     */
+    getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
 }
 interface ProcessMethods {
     /**
@@ -503,6 +564,15 @@ interface ProcessMethods {
      * @returns Promise resolving to array of process incidents
      */
     getIncidents(): Promise<ProcessIncidentGetResponse[]>;
+    /**
+     * Get element stats for this process
+     *
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param packageVersion - Package version to filter by
+     * @returns Promise resolving to an array of {@link ElementStats}
+     */
+    getElementStats(startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
 }
 type MaestroProcessGetAllResponse = RawMaestroProcessGetAllResponse & ProcessMethods;
 /**
@@ -645,8 +715,7 @@ interface ProcessInstanceExecutionHistoryResponse {
     startedTime: string;
     endTime: string | null;
     attributes: string | null;
-    createdTime: string;
-    updatedTime?: string;
+    updatedTime: string;
     expiredTime: string | null;
 }
 /**
@@ -793,24 +862,26 @@ interface ProcessInstancesServiceModel {
     /**
      * Get execution history (spans) for a process instance
      * @param instanceId The ID of the instance to get history for
+     * @param folderKey The folder key for authorization
      * @returns Promise resolving to execution history
      * {@link ProcessInstanceExecutionHistoryResponse}
      * @example
      * ```typescript
      * // Get execution history for a process instance
      * const history = await processInstances.getExecutionHistory(
-     *   <instanceId>
+     *   <instanceId>,
+     *   <folderKey>
      * );
      *
      * // Analyze execution timeline
      * history.forEach(span => {
      *   console.log(`Activity: ${span.name}`);
-     *   console.log(`Start: ${span.startTime}`);
-     *   console.log(`Duration: ${span.duration}ms`);
+     *   console.log(`Start: ${span.startedTime}`);
+     *   console.log(`End: ${span.endTime}`);
      * });
      * ```
      */
-    getExecutionHistory(instanceId: string): Promise<ProcessInstanceExecutionHistoryResponse[]>;
+    getExecutionHistory(instanceId: string, folderKey: string): Promise<ProcessInstanceExecutionHistoryResponse[]>;
     /**
      * Get BPMN XML file for a process instance
      * @param instanceId The ID of the instance to get BPMN for
@@ -1076,6 +1147,7 @@ interface RequestWithPaginationOptions extends RequestSpec {
             tokenParam?: string;
             countParam?: string;
             convertToSkip?: boolean;
+            zeroBased?: boolean;
         };
     };
 }
@@ -1496,6 +1568,38 @@ declare class MaestroProcessesService extends BaseService implements MaestroProc
      * ```
      */
     getTopExecutionDuration(startTime: Date, endTime: Date, options?: TopQueryOptions): Promise<ProcessGetTopDurationResponse[]>;
+    /**
+     * Get element stats for process instances
+     *
+     * Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
+     * duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a process.
+     *
+     * @param processKey - Process key to filter by
+     * @param packageId - Package identifier
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param packageVersion - Package version to filter by
+     * @returns Promise resolving to an array of {@link ElementStats}
+     * @example
+     * ```typescript
+     * // Get element metrics for a process
+     * const elements = await maestroProcesses.getElementStats(
+     *   '<processKey>',
+     *   '<packageId>',
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   '1.0.1'
+     * );
+     *
+     * // Analyze element performance
+     * for (const element of elements) {
+     *   console.log(`Element: ${element.elementId}`);
+     *   console.log(`  Success: ${element.successCount}, Failed: ${element.failCount}`);
+     *   console.log(`  Avg duration: ${element.avgDurationMs}ms, P95: ${element.p95DurationMs}ms`);
+     * }
+     * ```
+     */
+    getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
 }
 
 declare class ProcessInstancesService extends BaseService implements ProcessInstancesServiceModel {
@@ -1550,9 +1654,27 @@ declare class ProcessInstancesService extends BaseService implements ProcessInst
     /**
      * Get execution history (spans) for a process instance
      * @param instanceId The ID of the instance to get history for
-     * @returns Promise<ProcessInstanceExecutionHistoryResponse[]>
+     * @param folderKey The folder key for authorization
+     * @returns Promise resolving to execution history
+     * {@link ProcessInstanceExecutionHistoryResponse}
+     * @example
+     * ```typescript
+     * // Get execution history for a process instance
+     * const history = await processInstances.getExecutionHistory(
+     *   <instanceId>,
+     *   <folderKey>
+     * );
+     *
+     * // Analyze execution timeline
+     * history.forEach(span => {
+     *   console.log(`Activity: ${span.name}`);
+     *   console.log(`Start: ${span.startedTime}`);
+     *   console.log(`End: ${span.endTime}`);
+     * });
+     * ```
      */
-    getExecutionHistory(instanceId: string): Promise<ProcessInstanceExecutionHistoryResponse[]>;
+    getExecutionHistory(instanceId: string, folderKey: string): Promise<ProcessInstanceExecutionHistoryResponse[]>;
+    private mapSpanToHistory;
     /**
      * Get BPMN XML file for a process instance
      * @param instanceId The ID of the instance to get BPMN for
@@ -1652,4 +1774,4 @@ declare class ProcessIncidentsService extends BaseService implements ProcessInci
 }
 
 export { DebugMode, InstanceFinalStatus, MaestroProcessesService as MaestroProcesses, MaestroProcessesService, ProcessIncidentSeverity, ProcessIncidentStatus, ProcessIncidentType, ProcessIncidentsService as ProcessIncidents, ProcessIncidentsService, ProcessInstancesService as ProcessInstances, ProcessInstancesService, TimeInterval, createProcessInstanceWithMethods, createProcessWithMethods };
-export type { BpmnXmlString, ElementGetTopFailedCountResponse, ElementMetaData, GetTopBaseResponse, GetTopDurationResponse, GetTopFaultedCountResponse, GetTopRunCountResponse, GlobalVariableMetaData, InstanceStatusTimelineResponse, MaestroProcessGetAllResponse, MaestroProcessesServiceModel, ProcessGetTopDurationResponse, ProcessGetTopFaultedCountResponse, ProcessGetTopRunCountResponse, ProcessIncidentGetAllResponse, ProcessIncidentGetResponse, ProcessIncidentsServiceModel, ProcessInstanceExecutionHistoryResponse, ProcessInstanceGetAllOptions, ProcessInstanceGetAllWithPaginationOptions, ProcessInstanceGetResponse, ProcessInstanceGetVariablesOptions, ProcessInstanceGetVariablesResponse, ProcessInstanceMethods, ProcessInstanceOperationOptions, ProcessInstanceOperationResponse, ProcessInstanceRun, ProcessInstancesServiceModel, ProcessMethods, RawMaestroProcessGetAllResponse, RawProcessInstanceGetResponse, TimelineOptions, TopQueryOptions };
+export type { BpmnXmlString, ElementGetTopFailedCountResponse, ElementMetaData, ElementStats, GetTopBaseResponse, GetTopDurationResponse, GetTopFaultedCountResponse, GetTopRunCountResponse, GlobalVariableMetaData, InstanceStatusTimelineResponse, MaestroProcessGetAllResponse, MaestroProcessesServiceModel, ProcessGetTopDurationResponse, ProcessGetTopFaultedCountResponse, ProcessGetTopRunCountResponse, ProcessIncidentGetAllResponse, ProcessIncidentGetResponse, ProcessIncidentsServiceModel, ProcessInstanceExecutionHistoryResponse, ProcessInstanceGetAllOptions, ProcessInstanceGetAllWithPaginationOptions, ProcessInstanceGetResponse, ProcessInstanceGetVariablesOptions, ProcessInstanceGetVariablesResponse, ProcessInstanceMethods, ProcessInstanceOperationOptions, ProcessInstanceOperationResponse, ProcessInstanceRun, ProcessInstancesServiceModel, ProcessMethods, RawMaestroProcessGetAllResponse, RawProcessInstanceGetResponse, TimelineOptions, TopQueryOptions };

package/dist/maestro-processes/index.mjs

@@ -46,6 +46,7 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
  * Base path constants for different services
  */
 const PIMS_BASE = 'pims_';
+const LLMOPS_BASE = 'llmopstenant_';
 const INSIGHTS_RTM_BASE = 'insightsrtm_';
 
 /**
@@ -60,7 +61,7 @@ const MAESTRO_ENDPOINTS = {
     INSTANCES: {
         GET_ALL: `${PIMS_BASE}/api/v1/instances`,
         GET_BY_ID: (instanceId) => `${PIMS_BASE}/api/v1/instances/${instanceId}`,
-        GET_EXECUTION_HISTORY: (instanceId) => `${PIMS_BASE}/api/v1/spans/${instanceId}`,
+        GET_ELEMENT_EXECUTIONS: (instanceId) => `${PIMS_BASE}/api/v1/instances/${instanceId}/element-executions`,
         GET_BPMN: (instanceId) => `${PIMS_BASE}/api/v1/instances/${instanceId}/bpmn`,
         GET_VARIABLES: (instanceId) => `${PIMS_BASE}/api/v1/instances/${instanceId}/variables`,
         CANCEL: (instanceId) => `${PIMS_BASE}/api/v1/instances/${instanceId}/cancel`,
@@ -72,6 +73,9 @@ const MAESTRO_ENDPOINTS = {
         GET_BY_PROCESS: (processKey) => `${PIMS_BASE}/api/v1/incidents/process/${processKey}`,
         GET_BY_INSTANCE: (instanceId) => `${PIMS_BASE}/api/v1/instances/${instanceId}/incidents`,
     },
+    TRACES: {
+        GET_SPANS: (traceId) => `${LLMOPS_BASE}/api/Traces/spans?traceId=${traceId}`,
+    },
     INSIGHTS: {
         /** Top processes ranked by run count */
         TOP_PROCESSES_BY_RUN_COUNT: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/TopProcessesByRunCount`,
@@ -83,6 +87,8 @@ const MAESTRO_ENDPOINTS = {
         INSTANCE_STATUS_BY_DATE: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/InstanceStatusByDate`,
         /** Top processes ranked by total duration */
         TOP_PROCESSES_BY_DURATION: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/TopProcessesByDuration`,
+        /** Element count by status for agentic instances (process and case) */
+        ELEMENT_COUNT_BY_STATUS: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/ElementCountByStatus`,
     },
 };
 
@@ -105,6 +111,13 @@ function createProcessMethods(processData, service) {
             if (!processData.folderKey)
                 throw new Error('Folder key is undefined');
             return service.getIncidents(processData.processKey, processData.folderKey);
+        },
+        getElementStats(startTime, endTime, packageVersion) {
+            if (!processData.processKey)
+                throw new Error('Process key is undefined');
+            if (!processData.packageId)
+                throw new Error('Package ID is undefined');
+            return service.getElementStats(processData.processKey, processData.packageId, startTime, endTime, packageVersion);
         }
     };
 }
@@ -166,6 +179,28 @@ async function fetchInstanceStatusTimeline(postFn, startTime, endTime, isCaseMan
     });
     return response.data ?? [];
 }
+/**
+ * Builds the request body for the ElementCountByStatus endpoint.
+ *
+ * @param processKey - Process key to filter by
+ * @param packageId - Package identifier
+ * @param startTime - Start of the time range to query
+ * @param endTime - End of the time range to query
+ * @param packageVersion - Package version to filter by
+ * @returns Request body for the ElementCountByStatus endpoint
+ * @internal
+ */
+function buildElementCountByStatusBody(processKey, packageId, startTime, endTime, packageVersion) {
+    return {
+        commonParams: {
+            processKey,
+            packageId,
+            startTime: startTime.getTime(),
+            endTime: endTime.getTime(),
+            version: packageVersion
+        }
+    };
+}
 
 /**
  * Common constants used across the SDK
@@ -1158,6 +1193,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
@@ -1484,8 +1545,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
@@ -1531,7 +1593,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,
@@ -1789,6 +1851,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) {
@@ -1796,7 +1860,8 @@ class BaseService {
                     }
                 }
                 else {
-                    requestParams[offsetParam] = params.pageNumber || 1;
+                    const sdkPageNumber = params.pageNumber || 1;
+                    requestParams[offsetParam] = zeroBased ? sdkPageNumber - 1 : sdkPageNumber;
                 }
                 {
                     requestParams[countParam] = true;
@@ -1825,8 +1890,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];
@@ -1913,7 +1979,9 @@ function createProcessInstanceMethods(instanceData, service) {
         async getExecutionHistory() {
             if (!instanceData.instanceId)
                 throw new Error('Process instance ID is undefined');
-            return service.getExecutionHistory(instanceData.instanceId);
+            if (!instanceData.folderKey)
+                throw new Error('Process instance folder key is undefined');
+            return service.getExecutionHistory(instanceData.instanceId, instanceData.folderKey);
         },
         async getBpmn() {
             if (!instanceData.instanceId)
@@ -2110,12 +2178,6 @@ const ProcessInstanceMap = {
     createdAt: 'createdTime',
     updatedAt: 'updatedTime'
 };
-/**
- * Maps fields for Process Instance Execution History to ensure consistent naming
- */
-const ProcessInstanceExecutionHistoryMap = {
-    startTime: 'startedTime'
-};
 
 class ProcessInstancesService extends BaseService {
     /**
@@ -2196,11 +2258,66 @@ class ProcessInstancesService extends BaseService {
     /**
      * Get execution history (spans) for a process instance
      * @param instanceId The ID of the instance to get history for
-     * @returns Promise<ProcessInstanceExecutionHistoryResponse[]>
+     * @param folderKey The folder key for authorization
+     * @returns Promise resolving to execution history
+     * {@link ProcessInstanceExecutionHistoryResponse}
+     * @example
+     * ```typescript
+     * // Get execution history for a process instance
+     * const history = await processInstances.getExecutionHistory(
+     *   <instanceId>,
+     *   <folderKey>
+     * );
+     *
+     * // Analyze execution timeline
+     * history.forEach(span => {
+     *   console.log(`Activity: ${span.name}`);
+     *   console.log(`Start: ${span.startedTime}`);
+     *   console.log(`End: ${span.endTime}`);
+     * });
+     * ```
      */
-    async getExecutionHistory(instanceId) {
-        const response = await this.get(MAESTRO_ENDPOINTS.INSTANCES.GET_EXECUTION_HISTORY(instanceId));
-        return response.data.map(historyItem => transformData(historyItem, ProcessInstanceExecutionHistoryMap));
+    async getExecutionHistory(instanceId, folderKey) {
+        const headers = createHeaders({ [FOLDER_KEY]: folderKey });
+        const elementExecResponse = await this.get(MAESTRO_ENDPOINTS.INSTANCES.GET_ELEMENT_EXECUTIONS(instanceId), { headers });
+        const traceId = elementExecResponse.data.traceId;
+        const spansResponse = await this.get(MAESTRO_ENDPOINTS.TRACES.GET_SPANS(traceId), { headers });
+        // Build span lookup keyed by elementRunId extracted from Attributes JSON
+        const spanMap = new Map();
+        for (const span of spansResponse.data) {
+            try {
+                const attrs = span.Attributes ? JSON.parse(span.Attributes) : null;
+                if (attrs?.elementRunId) {
+                    spanMap.set(attrs.elementRunId, span);
+                }
+            }
+            catch {
+                // skip spans with unparseable Attributes — they won't match any elementRunId
+            }
+        }
+        const results = [];
+        for (const elementExec of elementExecResponse.data.elementExecutions) {
+            for (const run of elementExec.elementRuns) {
+                const span = spanMap.get(run.elementRunId);
+                if (span) {
+                    results.push(this.mapSpanToHistory(span));
+                }
+            }
+        }
+        return results;
+    }
+    mapSpanToHistory(span) {
+        return {
+            id: span.Id,
+            traceId: span.TraceId,
+            parentId: span.ParentId,
+            name: span.Name,
+            startedTime: span.StartTime,
+            endTime: span.EndTime,
+            attributes: span.Attributes,
+            updatedTime: span.UpdatedAt,
+            expiredTime: span.ExpiryTimeUtc,
+        };
     }
     /**
      * Get BPMN XML file for a process instance
@@ -2692,6 +2809,41 @@ class MaestroProcessesService extends BaseService {
         const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.TOP_PROCESSES_BY_DURATION, buildInsightsTopBody(startTime, endTime, false, options));
         return (data ?? []).map(process => ({ ...process, name: process.packageId }));
     }
+    /**
+     * Get element stats for process instances
+     *
+     * Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
+     * duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a process.
+     *
+     * @param processKey - Process key to filter by
+     * @param packageId - Package identifier
+     * @param startTime - Start of the time range to query
+     * @param endTime - End of the time range to query
+     * @param packageVersion - Package version to filter by
+     * @returns Promise resolving to an array of {@link ElementStats}
+     * @example
+     * ```typescript
+     * // Get element metrics for a process
+     * const elements = await maestroProcesses.getElementStats(
+     *   '<processKey>',
+     *   '<packageId>',
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   '1.0.1'
+     * );
+     *
+     * // Analyze element performance
+     * for (const element of elements) {
+     *   console.log(`Element: ${element.elementId}`);
+     *   console.log(`  Success: ${element.successCount}, Failed: ${element.failCount}`);
+     *   console.log(`  Avg duration: ${element.avgDurationMs}ms, P95: ${element.p95DurationMs}ms`);
+     * }
+     * ```
+     */
+    async getElementStats(processKey, packageId, startTime, endTime, packageVersion) {
+        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.ELEMENT_COUNT_BY_STATUS, buildElementCountByStatusBody(processKey, packageId, startTime, endTime, packageVersion));
+        return data ?? [];
+    }
 }
 __decorate([
     track('MaestroProcesses.GetAll')
@@ -2714,6 +2866,9 @@ __decorate([
 __decorate([
     track('MaestroProcesses.GetTopExecutionDuration')
 ], MaestroProcessesService.prototype, "getTopExecutionDuration", null);
+__decorate([
+    track('MaestroProcesses.GetElementStats')
+], MaestroProcessesService.prototype, "getElementStats", null);
 
 /**
  * Service class for Maestro Process Incidents

package/dist/processes/index.cjs

@@ -721,6 +721,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
@@ -1344,8 +1370,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
@@ -1391,7 +1418,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,
@@ -1649,6 +1676,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) {
@@ -1656,7 +1685,8 @@ class BaseService {
                     }
                 }
                 else {
-                    requestParams[offsetParam] = params.pageNumber || 1;
+                    const sdkPageNumber = params.pageNumber || 1;
+                    requestParams[offsetParam] = zeroBased ? sdkPageNumber - 1 : sdkPageNumber;
                 }
                 {
                     requestParams[countParam] = true;
@@ -1685,8 +1715,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/processes/index.d.ts

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