@uipath/uipath-typescript 1.3.11 → 1.4.1

package/dist/index.cjs

@@ -4020,7 +4020,7 @@ object({
     secret: string().optional(),
     clientId: string().optional(),
     redirectUri: string().url().optional(),
-    scope: string().optional()
+    scope: string().optional(),
 });
 class UiPathConfig {
     constructor(options) {
@@ -4071,6 +4071,32 @@ class ExecutionContext {
  */
 const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 const isInActionCenter = 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.
+ */
+const embeddingOrigin = (() => {
+    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;
+    }
+})();
 
 /**
  * Session storage keys used by the auth module
@@ -4472,6 +4498,24 @@ exports.TaskActivityType = void 0;
     TaskActivityType["BulkCompleted"] = "BulkCompleted";
     TaskActivityType["FirstOpened"] = "FirstOpened";
 })(exports.TaskActivityType || (exports.TaskActivityType = {}));
+/**
+ * Defines how a task assignment is distributed.
+ *
+ * Defaults to {@link TaskAssignmentCriteria.SingleUser} (a direct single-user
+ * assignment) when not specified. The group-based criteria tell Action Center
+ * how to distribute the task across the members of a directory group.
+ */
+exports.TaskAssignmentCriteria = void 0;
+(function (TaskAssignmentCriteria) {
+    /** Assigned to a single user, like a direct assignment. */
+    TaskAssignmentCriteria["SingleUser"] = "SingleUser";
+    /** Assigned to the group member with the fewest pending tasks. */
+    TaskAssignmentCriteria["Workload"] = "Workload";
+    /** Assigned to all users in the group. */
+    TaskAssignmentCriteria["AllUsers"] = "AllUsers";
+    /** Assigned in a round-robin manner across the group's members. */
+    TaskAssignmentCriteria["RoundRobin"] = "RoundRobin";
+})(exports.TaskAssignmentCriteria || (exports.TaskAssignmentCriteria = {}));
 
 /**
  * Base path constants for different services
@@ -4480,6 +4524,7 @@ const ORCHESTRATOR_BASE = 'orchestrator_';
 const PIMS_BASE = 'pims_';
 const DATAFABRIC_BASE = 'datafabric_';
 const IDENTITY_BASE = 'identity_';
+const LLMOPS_BASE = 'llmopstenant_';
 const INSIGHTS_RTM_BASE = 'insightsrtm_';
 
 /**
@@ -4572,7 +4617,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`,
@@ -4584,6 +4629,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}`,
+    },
     CASES: {
         GET_CASE_JSON: (instanceId) => `${PIMS_BASE}/api/v1/cases/${instanceId}/case-json`,
         GET_ELEMENT_EXECUTIONS: (instanceId) => `${PIMS_BASE}/api/v1/element-executions/case-instances/${instanceId}`,
@@ -4604,6 +4652,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`,
     },
 };
 
@@ -4622,6 +4672,9 @@ const DATA_FABRIC_TENANT_FOLDER_ID = '00000000-0000-0000-0000-000000000000';
 const DATA_FABRIC_ENDPOINTS = {
     ENTITY: {
         GET_ALL: `${DATAFABRIC_BASE}/api/Entity`,
+        // Lists tenant-level and folder-level entities together.
+        // Used by getAll when includeFolderEntities is true.
+        GET_ALL_V2: `${DATAFABRIC_BASE}/api/v2/Entity`,
         GET_ENTITY_RECORDS: (entityId) => `${DATAFABRIC_BASE}/api/EntityService/entity/${entityId}/read`,
         GET_BY_ID: (entityId) => `${DATAFABRIC_BASE}/api/Entity/${entityId}`,
         GET_RECORD_BY_ID: (entityId, recordId) => `${DATAFABRIC_BASE}/api/EntityService/entity/${entityId}/read/${recordId}`,
@@ -4678,6 +4731,105 @@ var ActionCenterEventNames;
 })(ActionCenterEventNames || (ActionCenterEventNames = {}));
 
 const AUTHENTICATION_TIMEOUT = 8000;
+const ALLOWED_HOST_ORIGINS = new Set([
+    'https://alpha.uipath.com',
+    'https://staging.uipath.com',
+    'https://cloud.uipath.com',
+]);
+/**
+ * Returns true if the origin is a trusted UiPath host that may initiate
+ * token delegation. Mirrors the same allowlist used by ActionCenterTokenManager.
+ */
+function isValidHostOrigin(origin) {
+    if (!origin)
+        return false;
+    if (ALLOWED_HOST_ORIGINS.has(origin))
+        return true;
+    try {
+        return new URL(origin).hostname === 'localhost';
+    }
+    catch {
+        console.warn('isValidHostOrigin: received a malformed origin URL', origin);
+        return false;
+    }
+}
+function isTokenExpired(tokenInfo) {
+    if (!tokenInfo?.expiresAt)
+        return true;
+    return new Date() >= tokenInfo.expiresAt;
+}
+/**
+ * The validated host origin when the app is running as a trusted, generic
+ * host-embedded app (`?host=embed&basedomain=<origin>` with an allowlisted
+ * UiPath origin); otherwise null. Shared by TokenManager (to create the
+ * EmbeddedTokenManager) and UiPath init (to seed an empty token so getValidToken
+ * can bootstrap the postMessage token flow), which previously duplicated this
+ * condition inline.
+ */
+const trustedEmbeddingOrigin = isHostEmbedded && embeddingOrigin && isValidHostOrigin(embeddingOrigin) ? embeddingOrigin : null;
+/**
+ * Waits for the next window message that satisfies `filter`.
+ * Rejects if the AbortSignal fires before a matching message arrives.
+ */
+function waitForMessage(filter, signal) {
+    return new Promise((resolve, reject) => {
+        const handler = (event) => {
+            if (!filter(event))
+                return;
+            window.removeEventListener('message', handler);
+            resolve(event);
+        };
+        signal.addEventListener('abort', () => {
+            window.removeEventListener('message', handler);
+            reject(signal.reason);
+        }, { once: true });
+        window.addEventListener('message', handler);
+    });
+}
+/**
+ * Sends a token-refresh request to a parent host frame and waits for the
+ * response. Handles timeout, origin filtering, and listener cleanup.
+ *
+ * Both ActionCenterTokenManager and EmbeddedTokenManager delegate to this
+ * function; they differ only in the event names and message shape they use.
+ */
+function requestHostToken(options) {
+    const { pinnedOrigin, sendRequest, responseEventType, extractToken, onTokenRefreshed } = options;
+    const controller = new AbortController();
+    const cancel = () => controller.abort(new AuthenticationError({
+        message: 'Token refresh cancelled',
+        statusCode: HttpStatus.UNAUTHORIZED,
+    }));
+    const promise = (async () => {
+        const timer = setTimeout(() => controller.abort(new AuthenticationError({
+            message: `Token refresh timed out after ${AUTHENTICATION_TIMEOUT}ms waiting for host response`,
+            statusCode: HttpStatus.UNAUTHORIZED,
+        })), AUTHENTICATION_TIMEOUT);
+        try {
+            // Register listener before sending — avoids any race between send and response
+            const responsePromise = waitForMessage(event => event.origin === pinnedOrigin && event.data?.eventType === responseEventType, controller.signal);
+            sendRequest();
+            const event = await responsePromise;
+            const token = extractToken(event.data);
+            if (!token) {
+                throw new AuthenticationError({
+                    message: 'Host responded but did not include a valid access token',
+                    statusCode: HttpStatus.UNAUTHORIZED,
+                });
+            }
+            // type: 'secret' intentionally prevents the SDK's internal OAuth refresh path
+            // from running — the host manager owns the refresh cycle via requestHostToken.
+            // This mirrors the same pattern used by ActionCenterTokenManager.
+            onTokenRefreshed({ token: token.accessToken, type: 'secret', expiresAt: token.expiresAt });
+            return token.accessToken;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    })();
+    return { promise, cancel };
+}
+
 class ActionCenterTokenManager {
     constructor(config, onTokenRefreshed) {
         this.config = config;
@@ -4686,84 +4838,334 @@ class ActionCenterTokenManager {
         this.refreshPromise = null;
     }
     async refreshAccessToken(tokenInfo) {
-        if (!this.isTokenExpired(tokenInfo)) {
+        if (!isTokenExpired(tokenInfo)) {
             return tokenInfo.token;
         }
         if (this.refreshPromise) {
             return this.refreshPromise;
         }
-        this.refreshPromise = new Promise((resolve, reject) => {
-            const content = {
+        const parentOrigin = this.parentOrigin;
+        if (!parentOrigin) {
+            return Promise.reject(new AuthenticationError({
+                message: 'Cannot refresh token: basedomain query parameter is missing',
+                statusCode: HttpStatus.UNAUTHORIZED,
+            }));
+        }
+        // Guard before requestHostToken registers the inbound listener — an untrusted
+        // basedomain would otherwise leave the listener live for the full timeout window,
+        // accepting a forged TOKENREFRESHED from that origin.
+        if (!isValidHostOrigin(parentOrigin)) {
+            return Promise.reject(new AuthenticationError({
+                message: 'Cannot refresh token: basedomain is not a trusted UiPath host origin',
+                statusCode: HttpStatus.UNAUTHORIZED,
+            }));
+        }
+        const { promise } = requestHostToken({
+            pinnedOrigin: parentOrigin,
+            sendRequest: () => this.sendMessageToParent(ActionCenterEventNames.REFRESHTOKEN, {
                 clientId: this.config.clientId,
                 scope: this.config.scope,
-            };
-            this.sendMessageToParent(ActionCenterEventNames.REFRESHTOKEN, content);
-            const messageListener = (event) => {
-                if (event.origin !== this.parentOrigin)
-                    return;
-                if (event.data?.eventType !== ActionCenterEventNames.TOKENREFRESHED)
-                    return;
-                clearTimeout(timer);
-                if (event.data?.content?.token) {
-                    const { accessToken, expiresAt } = event.data.content.token;
-                    this.onTokenRefreshed({ token: accessToken, type: 'secret', expiresAt });
-                    resolve(accessToken);
-                }
-                else {
-                    reject(new AuthenticationError({
-                        message: 'Failed to fetch access token',
-                        statusCode: HttpStatus.UNAUTHORIZED,
-                    }));
-                }
-                this.refreshPromise = null;
-                this.cleanup(messageListener);
-            };
-            const timer = setTimeout(() => {
-                reject(new AuthenticationError({
-                    message: 'Failed to fetch access token',
-                    statusCode: HttpStatus.UNAUTHORIZED,
-                }));
-                this.refreshPromise = null;
-                this.cleanup(messageListener);
-            }, AUTHENTICATION_TIMEOUT);
-            window.addEventListener('message', messageListener);
+            }),
+            responseEventType: ActionCenterEventNames.TOKENREFRESHED,
+            extractToken: (data) => {
+                const token = data?.content?.token;
+                if (!token?.accessToken)
+                    return undefined;
+                return { accessToken: token.accessToken, expiresAt: token.expiresAt };
+            },
+            onTokenRefreshed: this.onTokenRefreshed,
         });
-        return this.refreshPromise;
-    }
-    isTokenExpired(tokenInfo) {
-        if (!tokenInfo?.expiresAt) {
-            return true;
+        this.refreshPromise = promise;
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
         }
-        return new Date() >= tokenInfo.expiresAt;
     }
     sendMessageToParent(eventType, content) {
-        if (window.parent && this.isValidOrigin(this.parentOrigin)) {
+        if (window.parent && isValidHostOrigin(this.parentOrigin)) {
             try {
                 window.parent.postMessage({ eventType, content }, this.parentOrigin);
             }
             catch (error) {
-                console.warn('Failed to send message to Action Center', JSON.stringify(error));
+                console.warn('ActionCenterTokenManager: postMessage to host failed', JSON.stringify(error));
             }
         }
     }
-    cleanup(messageListener) {
-        window.removeEventListener('message', messageListener);
+}
+
+/**
+ * Event names and payload types for the UIP.* postMessage protocol used
+ * when a coded app is embedded inside a UiPath host (e.g. Governance Portal, Insights UI).
+ *
+ * Flow — app-initiated, mirrors the Action Center protocol:
+ *  App → Host: UIP.refreshToken   (requests a token; carries clientId + scope
+ *                                   so the host knows which OAuth client to use)
+ *  Host → App: UIP.tokenRefreshed (delivers the access token)
+ *
+ * Detection: the host signals embedding via `?host=embed&basedomain=<origin>` in
+ * the iframe src URL. No explicit init message from the host is required.
+ */
+var UipEmbeddedEventNames;
+(function (UipEmbeddedEventNames) {
+    UipEmbeddedEventNames["REFRESH_TOKEN"] = "UIP.refreshToken";
+    UipEmbeddedEventNames["TOKEN_REFRESHED"] = "UIP.tokenRefreshed";
+})(UipEmbeddedEventNames || (UipEmbeddedEventNames = {}));
+
+function parseExpiresAt(raw) {
+    const d = new Date(raw);
+    if (isNaN(d.getTime())) {
+        console.warn('EmbeddedTokenManager: host sent a malformed expiresAt value — treating token as already expired', raw);
+        return new Date(0);
+    }
+    return d;
+}
+function extractToken(data) {
+    const token = data?.content?.token;
+    if (!token?.accessToken)
+        return undefined;
+    return { accessToken: token.accessToken, expiresAt: parseExpiresAt(token.expiresAt) };
+}
+/**
+ * Handles token delegation for coded apps embedded inside a UiPath host
+ * (e.g. Governance Portal, Insights UI).
+ *
+ * Detection: the host signals embedding via `?host=embed&basedomain=<origin>`
+ * in the iframe src URL. `parentOrigin` is read from `?basedomain=` and validated
+ * against the trusted UiPath host allowlist before this manager is constructed.
+ * This mirrors the mechanism used by ActionCenterTokenManager.
+ *
+ * On every token expiry the SDK sends `UIP.refreshToken` with `clientId` and
+ * `scope`; the host performs silent SSO and responds with `UIP.tokenRefreshed`.
+ */
+class EmbeddedTokenManager {
+    /**
+     * @param parentOrigin Validated UiPath host origin from the `?basedomain=` query parameter.
+     * @param config SDK configuration — `clientId` and `scope` are required and forwarded
+     *   in every `UIP.refreshToken` request so the host knows which OAuth client to use.
+     * @param onTokenRefreshed Called with the refreshed TokenInfo so the caller
+     *   can persist it in the execution context.
+     * @throws {AuthenticationError} if `config.clientId` or `config.scope` are not set.
+     */
+    constructor(parentOrigin, config, onTokenRefreshed) {
+        this.parentOrigin = parentOrigin;
+        this.onTokenRefreshed = onTokenRefreshed;
+        this.refreshPromise = null;
+        this.cancelRefresh = null;
+        if (!config.clientId || !config.scope) {
+            throw new ValidationError({
+                message: 'EmbeddedTokenManager requires clientId and scope to be configured for host-delegated authentication',
+            });
+        }
+        this.clientId = config.clientId;
+        this.scope = config.scope;
     }
-    isValidOrigin(origin) {
-        const ALLOWED_ORIGINS = ['https://alpha.uipath.com', 'https://staging.uipath.com', 'https://cloud.uipath.com'];
-        if (!origin) {
-            return false;
+    async refreshAccessToken(tokenInfo) {
+        if (!isTokenExpired(tokenInfo)) {
+            return tokenInfo.token;
         }
-        if (ALLOWED_ORIGINS.includes(origin)) {
-            return true;
+        if (this.refreshPromise) {
+            return this.refreshPromise;
         }
+        const { promise, cancel } = requestHostToken({
+            pinnedOrigin: this.parentOrigin,
+            sendRequest: () => {
+                try {
+                    const message = {
+                        eventType: UipEmbeddedEventNames.REFRESH_TOKEN,
+                        content: { clientId: this.clientId, scope: this.scope },
+                    };
+                    window.parent.postMessage(message, this.parentOrigin);
+                }
+                catch (error) {
+                    console.warn('EmbeddedTokenManager: postMessage to host failed', error);
+                }
+            },
+            responseEventType: UipEmbeddedEventNames.TOKEN_REFRESHED,
+            extractToken,
+            onTokenRefreshed: this.onTokenRefreshed,
+        });
+        this.cancelRefresh = cancel;
+        this.refreshPromise = promise;
         try {
-            const url = new URL(origin);
-            return url.hostname === 'localhost';
+            return await this.refreshPromise;
         }
-        catch {
-            return false;
+        finally {
+            this.refreshPromise = null;
+            this.cancelRefresh = null;
+        }
+    }
+    /** Cancels any in-flight token-refresh request. */
+    destroy() {
+        this.cancelRefresh?.();
+    }
+}
+
+/**
+ * SDK Telemetry constants.
+ *
+ * Only the SDK's identity (version, service name, role name, …) lives
+ * here. The Application Insights connection string is injected into
+ * `@uipath/core-telemetry` itself at publish time, and the generic attribute
+ * keys (`Version`, `Service`, `CloudOrganizationName`, …) are owned by
+ * `@uipath/core-telemetry` and consumed there — they are not part of the
+ * SDK's public API.
+ */
+/** SDK version placeholder — patched by the SDK publish workflow. */
+const SDK_VERSION = '1.4.1';
+const CLOUD_ROLE_NAME = 'uipath-ts-sdk';
+const SDK_SERVICE_NAME = 'UiPath.TypeScript.Sdk';
+const SDK_LOGGER_NAME = 'uipath-ts-sdk-telemetry';
+const SDK_RUN_EVENT = 'Sdk.Run';
+
+/**
+ * UiPath TypeScript SDK Telemetry
+ *
+ * Constructs the SDK's own `TelemetryClient` and binds the SDK-local
+ * `track` / `trackEvent` to it. Each consumer of `@uipath/core-telemetry`
+ * does this independently, so events carry their own consumer's identity
+ * and tenant context.
+ */
+// Keyed by `CLOUD_ROLE_NAME` so every SDK subpath bundle resolves to the
+// same `TelemetryClient` instance at runtime. A single `initialize(...)`
+// from the `UiPath` constructor therefore wires up `@track` decorators
+// across every subpath bundle (`assets`, `feedback`, `tasks`, …).
+const sdkClient = coreTelemetry.getOrCreateClient(CLOUD_ROLE_NAME);
+const track = coreTelemetry.createTrack(sdkClient);
+const trackEvent = coreTelemetry.createTrackEvent(sdkClient);
+const telemetryClient = {
+    initialize(context) {
+        sdkClient.initialize({
+            sdkVersion: SDK_VERSION,
+            serviceName: SDK_SERVICE_NAME,
+            cloudRoleName: CLOUD_ROLE_NAME,
+            loggerName: SDK_LOGGER_NAME,
+            defaultEventName: SDK_RUN_EVENT,
+            context,
+        });
+    },
+    /**
+     * Sets the authenticated user's id so every subsequently emitted event
+     * carries it as `CloudUserId`.
+     */
+    setUserId(userId) {
+        sdkClient.setUserId(userId);
+    },
+};
+
+/**
+ * Base64 encoding/decoding
+ */
+/**
+ * Encodes a string to base64
+ * @param str - The string to encode
+ * @returns Base64 encoded string
+ */
+function encodeBase64(str) {
+    // TextEncoder for UTF-8 encoding (works in both browser and Node.js)
+    const encoder = new TextEncoder();
+    const data = encoder.encode(str);
+    // Convert Uint8Array to base64
+    if (isBrowser) {
+        // Browser environment
+        // Convert Uint8Array to binary string then to base64
+        const binaryString = Array.from(data, byte => String.fromCharCode(byte)).join('');
+        return btoa(binaryString);
+    }
+    else {
+        // Node.js environment
+        return Buffer.from(data).toString('base64');
+    }
+}
+/**
+ * Decodes a base64 string
+ * @param base64 - The base64 string to decode
+ * @returns Decoded string
+ */
+function decodeBase64(base64) {
+    let bytes;
+    if (isBrowser) {
+        // Browser environment
+        const binaryString = atob(base64);
+        bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
+        }
+    }
+    else {
+        // Node.js environment
+        bytes = new Uint8Array(Buffer.from(base64, 'base64'));
+    }
+    // TextDecoder for UTF-8 decoding (works in both browser and Node.js)
+    const decoder = new TextDecoder();
+    return decoder.decode(bytes);
+}
+
+/**
+ * Encodes a folder path for the `X-UIPATH-FolderPath-Encoded` header.
+ *
+ * Orchestrator decodes this header as **base64-encoded UTF-16 LE bytes**
+ * (see `HttpHeadersProviderExtensions.GetDecoded` + `OrganizationUnitProvider`
+ * in the Orchestrator repo, which call `Encoding.Unicode.GetString(...)`).
+ * URL-encoding is NOT what the server expects — it must be base64-of-UTF-16-LE
+ * bytes.
+ *
+ * @param folderPath - The folder path (e.g. 'Shared/Finance')
+ * @returns Base64 string suitable for the `X-UIPATH-FolderPath-Encoded` header
+ */
+function encodeFolderPathHeader(folderPath) {
+    // Force little-endian regardless of host byte order. `Uint16Array` viewed
+    // as `Uint8Array` would use the host's native order — correct on LE hosts
+    // (x86/ARM-LE) but wrong on BE hosts. `DataView.setUint16(..., true)`
+    // pins LE.
+    const buf = new ArrayBuffer(folderPath.length * 2);
+    const view = new DataView(buf);
+    for (let i = 0; i < folderPath.length; i++) {
+        view.setUint16(i * 2, folderPath.charCodeAt(i), true);
+    }
+    const bytes = new Uint8Array(buf);
+    let binary = '';
+    for (let i = 0; i < bytes.byteLength; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    // btoa is browser-native; Node 16+ also has it as a global
+    return btoa(binary);
+}
+
+/**
+ * JWT decoding helpers — payload inspection only, no signature verification.
+ */
+const BASE64URL_DASH_RE = /-/g;
+const BASE64URL_UNDERSCORE_RE = /_/g;
+/**
+ * Converts a base64url-encoded JWT segment to standard base64 with padding.
+ */
+function base64UrlToBase64(value) {
+    const base64 = value
+        .replace(BASE64URL_DASH_RE, '+')
+        .replace(BASE64URL_UNDERSCORE_RE, '/');
+    return base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+}
+/**
+ * Extracts the user id (`sub` claim) from a JWT access token payload.
+ * Returns an empty string for opaque (non-JWT) tokens or malformed payloads.
+ *
+ * @param token - The access token to inspect
+ * @returns The user id, or an empty string if it cannot be extracted
+ */
+function extractUserIdFromToken(token) {
+    try {
+        const payload = token.split('.')[1];
+        if (!payload) {
+            return '';
         }
+        const claims = JSON.parse(decodeBase64(base64UrlToBase64(payload)));
+        const sub = claims['sub'];
+        return typeof sub === 'string' && sub ? sub : '';
+    }
+    catch {
+        return '';
     }
 }
 
@@ -4786,10 +5188,15 @@ class TokenManager {
         this.isOAuth = isOAuth;
         this.refreshPromise = null;
         this.actionCenterTokenManager = null;
+        this.embeddedTokenManager = null;
         if (isInActionCenter) {
             this.actionCenterTokenManager = new ActionCenterTokenManager(config, (tokenInfo) => this.setToken(tokenInfo));
             this.isOAuth = false;
         }
+        else if (trustedEmbeddingOrigin) {
+            this.embeddedTokenManager = new EmbeddedTokenManager(trustedEmbeddingOrigin, config, tokenInfo => this.setToken(tokenInfo));
+            this.isOAuth = false;
+        }
     }
     /**
      * Checks if a token is expired
@@ -4820,6 +5227,10 @@ class TokenManager {
         if (this.actionCenterTokenManager) {
             return await this.actionCenterTokenManager.refreshAccessToken(tokenInfo);
         }
+        // Generic embedded path — active whenever the app is embedded in a UiPath host page
+        if (this.embeddedTokenManager) {
+            return await this.embeddedTokenManager.refreshAccessToken(tokenInfo);
+        }
         // For secret-based tokens, they never expire
         if (tokenInfo.type === 'secret') {
             return tokenInfo.token;
@@ -4958,6 +5369,13 @@ class TokenManager {
         }
         return true;
     }
+    /**
+     * Releases resources held by this instance.
+     * Must be called when the TokenManager is no longer needed to prevent listener leaks.
+     */
+    destroy() {
+        this.embeddedTokenManager?.destroy();
+    }
     /**
      * Clears the current token
      */
@@ -4979,6 +5397,7 @@ class TokenManager {
      */
     _updateExecutionContext(tokenInfo) {
         this.executionContext.set('tokenInfo', tokenInfo);
+        telemetryClient.setUserId(extractUserIdFromToken(tokenInfo.token));
     }
     /**
      * Refreshes the access token using the stored refresh token.
@@ -5008,6 +5427,9 @@ class TokenManager {
      * Internal method to perform the actual token refresh
      */
     async _doRefreshToken() {
+        // Destructure before the type guard — hasOAuthConfig narrows this.config to
+        // { clientId, redirectUri, scope } which does not include BaseConfig fields.
+        const { orgName, baseUrl } = this.config;
         // Check if we're in OAuth flow
         if (!hasOAuthConfig(this.config)) {
             throw new Error('refreshAccessToken is only available in OAuth flow');
@@ -5017,13 +5439,12 @@ class TokenManager {
         if (!tokenInfo?.refreshToken) {
             throw new Error('No refresh token available. User may need to re-authenticate.');
         }
-        const orgName = this.config.orgName;
         const body = new URLSearchParams({
             grant_type: 'refresh_token',
             client_id: this.config.clientId,
             refresh_token: tokenInfo.refreshToken
         });
-        const response = await fetch(`${this.config.baseUrl}/${orgName}/identity_/connect/token`, {
+        const response = await fetch(`${baseUrl}/${orgName}/identity_/connect/token`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/x-www-form-urlencoded'
@@ -5483,51 +5904,6 @@ function normalizeBaseUrl(url) {
     return url.endsWith('/') ? url.slice(0, -1) : url;
 }
 
-/**
- * SDK Telemetry constants.
- *
- * Only the SDK's identity (version, service name, role name, …) lives
- * here. The Application Insights connection string is injected into
- * `@uipath/core-telemetry` itself at publish time, and the generic attribute
- * keys (`Version`, `Service`, `CloudOrganizationName`, …) are owned by
- * `@uipath/core-telemetry` and consumed there — they are not part of the
- * SDK's public API.
- */
-/** SDK version placeholder — patched by the SDK publish workflow. */
-const SDK_VERSION = '1.3.11';
-const CLOUD_ROLE_NAME = 'uipath-ts-sdk';
-const SDK_SERVICE_NAME = 'UiPath.TypeScript.Sdk';
-const SDK_LOGGER_NAME = 'uipath-ts-sdk-telemetry';
-const SDK_RUN_EVENT = 'Sdk.Run';
-
-/**
- * UiPath TypeScript SDK Telemetry
- *
- * Constructs the SDK's own `TelemetryClient` and binds the SDK-local
- * `track` / `trackEvent` to it. Each consumer of `@uipath/core-telemetry`
- * does this independently, so events carry their own consumer's identity
- * and tenant context.
- */
-// Keyed by `CLOUD_ROLE_NAME` so every SDK subpath bundle resolves to the
-// same `TelemetryClient` instance at runtime. A single `initialize(...)`
-// from the `UiPath` constructor therefore wires up `@track` decorators
-// across every subpath bundle (`assets`, `feedback`, `tasks`, …).
-const sdkClient = coreTelemetry.getOrCreateClient(CLOUD_ROLE_NAME);
-const track = coreTelemetry.createTrack(sdkClient);
-const trackEvent = coreTelemetry.createTrackEvent(sdkClient);
-const telemetryClient = {
-    initialize(context) {
-        sdkClient.initialize({
-            sdkVersion: SDK_VERSION,
-            serviceName: SDK_SERVICE_NAME,
-            cloudRoleName: CLOUD_ROLE_NAME,
-            loggerName: SDK_LOGGER_NAME,
-            defaultEventName: SDK_RUN_EVENT,
-            context,
-        });
-    },
-};
-
 /**
  * SDK Internals Registry - Internal registry for SDK instances
  *
@@ -5637,7 +6013,7 @@ function loadFromMetaTags() {
     return hasAnyValue ? config : null;
 }
 
-var _UiPath_instances, _UiPath_config, _UiPath_authService, _UiPath_initialized, _UiPath_partialConfig, _UiPath_multiLogin, _UiPath_metaFolderKey, _UiPath_initializeWithConfig, _UiPath_loadConfig;
+var _UiPath_instances, _UiPath_config, _UiPath_authService, _UiPath_initialized, _UiPath_partialConfig, _UiPath_multiLogin, _UiPath_metaFolderKey, _UiPath_metaOrgId, _UiPath_metaTenantId, _UiPath_initializeWithConfig, _UiPath_loadConfig;
 /**
  * UiPath - Core SDK class for authentication and configuration management.
  *
@@ -5682,9 +6058,18 @@ let UiPath$1 = class UiPath {
         // deployments). Not accepted via the public constructor; lives here so the
         // SDK can flow it through to BaseService.config without polluting BaseConfig.
         _UiPath_metaFolderKey.set(this, void 0);
+        // Org/tenant ids captured from the meta tags before the constructor config
+        // is merged in. The `uipath:org-name`/`uipath:tenant-name` meta tags always
+        // carry org/tenant *ids* in coded-app deployments, whereas a
+        // constructor-supplied `orgName`/`tenantName` may be actual names — so the
+        // telemetry ids must be read from the meta tags.
+        _UiPath_metaOrgId.set(this, void 0);
+        _UiPath_metaTenantId.set(this, void 0);
         // Load configuration from meta tags
         const configFromMetaTags = loadFromMetaTags();
         __classPrivateFieldSet(this, _UiPath_metaFolderKey, configFromMetaTags?.folderKey, "f");
+        __classPrivateFieldSet(this, _UiPath_metaOrgId, configFromMetaTags?.orgName, "f");
+        __classPrivateFieldSet(this, _UiPath_metaTenantId, configFromMetaTags?.tenantName, "f");
         // Merge configuration: constructor config overrides meta tags
         const mergedConfig = config ? { ...configFromMetaTags, ...config } : configFromMetaTags;
         if (mergedConfig && isCompleteConfig(mergedConfig)) {
@@ -5791,6 +6176,13 @@ let UiPath$1 = class UiPath {
     getToken() {
         return __classPrivateFieldGet(this, _UiPath_authService, "f")?.getToken();
     }
+    /**
+     * Releases resources held by this SDK instance.
+     * Cancels any in-flight token-refresh request. Call this when the coded app is unmounted.
+     */
+    destroy() {
+        __classPrivateFieldGet(this, _UiPath_authService, "f")?.getTokenManager()?.destroy();
+    }
     /**
      * Logout from the SDK, clearing all authentication state.
      * After calling this method, the user will need to re-initialize to authenticate again.
@@ -5813,7 +6205,7 @@ let UiPath$1 = class UiPath {
         __classPrivateFieldGet(this, _UiPath_authService, "f")?.updateToken(tokenInfo);
     }
 };
-_UiPath_config = new WeakMap(), _UiPath_authService = new WeakMap(), _UiPath_initialized = new WeakMap(), _UiPath_partialConfig = new WeakMap(), _UiPath_multiLogin = new WeakMap(), _UiPath_metaFolderKey = new WeakMap(), _UiPath_instances = new WeakSet(), _UiPath_initializeWithConfig = function _UiPath_initializeWithConfig(config) {
+_UiPath_config = new WeakMap(), _UiPath_authService = new WeakMap(), _UiPath_initialized = new WeakMap(), _UiPath_partialConfig = new WeakMap(), _UiPath_multiLogin = new WeakMap(), _UiPath_metaFolderKey = new WeakMap(), _UiPath_metaOrgId = new WeakMap(), _UiPath_metaTenantId = new WeakMap(), _UiPath_instances = new WeakSet(), _UiPath_initializeWithConfig = function _UiPath_initializeWithConfig(config) {
     // Validate and normalize the configuration
     validateConfig(config);
     const hasSecretAuth = hasSecretConfig(config);
@@ -5849,9 +6241,11 @@ _UiPath_config = new WeakMap(), _UiPath_authService = new WeakMap(), _UiPath_ini
         orgName: internalConfig.orgName,
         tenantName: internalConfig.tenantName
     };
-    // Initialize telemetry with SDK configuration
+    // Initialize telemetry with SDK configuration.
     telemetryClient.initialize({
         baseUrl: config.baseUrl,
+        orgId: __classPrivateFieldGet(this, _UiPath_metaOrgId, "f"),
+        tenantId: __classPrivateFieldGet(this, _UiPath_metaTenantId, "f"),
         orgName: config.orgName,
         tenantName: config.tenantName,
         clientId: hasOAuthAuth ? config.clientId : undefined,
@@ -5859,10 +6253,12 @@ _UiPath_config = new WeakMap(), _UiPath_authService = new WeakMap(), _UiPath_ini
     });
     // Track SDK initialization
     trackEvent('Sdk.Auth');
-    /** Auto-initialize for secret-based auth
-     * When viewed in Action Center, initialize tokenInfo with empty token. When an sdk call is made Action Center passes the token to sdk.
+    /** Auto-initialize for secret-based auth, Action Center, and generic host-embedded apps.
+     * When viewed in Action Center or embedded in a UiPath host frame via the UIP protocol,
+     * initialize tokenInfo with an empty token so getValidToken() can bootstrap via postMessage.
+     * When an sdk call is made, the host passes the token to the sdk.
      */
-    if (hasSecretAuth || isInActionCenter) {
+    if (hasSecretAuth || isInActionCenter || trustedEmbeddingOrigin) {
         __classPrivateFieldGet(this, _UiPath_authService, "f").authenticateWithSecret(config.secret ?? '');
         __classPrivateFieldSet(this, _UiPath_initialized, true, "f");
     }
@@ -5870,6 +6266,8 @@ _UiPath_config = new WeakMap(), _UiPath_authService = new WeakMap(), _UiPath_ini
     // Load from meta tags
     const metaConfig = loadFromMetaTags();
     __classPrivateFieldSet(this, _UiPath_metaFolderKey, metaConfig?.folderKey, "f");
+    __classPrivateFieldSet(this, _UiPath_metaOrgId, metaConfig?.orgName, "f");
+    __classPrivateFieldSet(this, _UiPath_metaTenantId, metaConfig?.tenantName, "f");
     // Merge with any partial config from constructor (constructor overrides meta tags)
     const merged = { ...metaConfig, ...__classPrivateFieldGet(this, _UiPath_partialConfig, "f") };
     if (!isCompleteConfig(merged)) {
@@ -6339,54 +6737,6 @@ function processODataArrayResponse(oDataResponse, successData) {
     };
 }
 
-/**
- * Base64 encoding/decoding
- */
-/**
- * Encodes a string to base64
- * @param str - The string to encode
- * @returns Base64 encoded string
- */
-function encodeBase64(str) {
-    // TextEncoder for UTF-8 encoding (works in both browser and Node.js)
-    const encoder = new TextEncoder();
-    const data = encoder.encode(str);
-    // Convert Uint8Array to base64
-    if (isBrowser) {
-        // Browser environment
-        // Convert Uint8Array to binary string then to base64
-        const binaryString = Array.from(data, byte => String.fromCharCode(byte)).join('');
-        return btoa(binaryString);
-    }
-    else {
-        // Node.js environment
-        return Buffer.from(data).toString('base64');
-    }
-}
-/**
- * Decodes a base64 string
- * @param base64 - The base64 string to decode
- * @returns Decoded string
- */
-function decodeBase64(base64) {
-    let bytes;
-    if (isBrowser) {
-        // Browser environment
-        const binaryString = atob(base64);
-        bytes = new Uint8Array(binaryString.length);
-        for (let i = 0; i < binaryString.length; i++) {
-            bytes[i] = binaryString.charCodeAt(i);
-        }
-    }
-    else {
-        // Node.js environment
-        bytes = new Uint8Array(Buffer.from(base64, 'base64'));
-    }
-    // TextDecoder for UTF-8 decoding (works in both browser and Node.js)
-    const decoder = new TextDecoder();
-    return decoder.decode(bytes);
-}
-
 /**
  * PaginationManager handles the conversion between uniform cursor-based pagination
  * and the specific pagination type for each service
@@ -7134,12 +7484,18 @@ class PaginationHelpers {
      * @returns Promise resolving to a paginated result
      */
     static async getAllPaginated(params) {
-        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, queryParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         const endpoint = getEndpoint(folderId);
         const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
+        // On POST, the caller's options go in the body; queryParams stays in the URL.
+        // On GET, everything is URL — queryParams merges with additionalParams.
+        const isPost = method === HTTP_METHODS.POST;
+        const requestSpec = isPost
+            ? { body: additionalParams, params: queryParams }
+            : { params: { ...additionalParams, ...queryParams } };
         const paginatedResponse = await serviceAccess.requestWithPagination(method, endpoint, paginationParams, {
             headers,
-            params: additionalParams,
+            ...requestSpec,
             pagination: {
                 paginationType: options.paginationType || PaginationType.OFFSET,
                 itemsField: options.itemsField || DEFAULT_ITEMS_FIELD,
@@ -7164,7 +7520,7 @@ class PaginationHelpers {
      * @returns Promise resolving to an object with data and totalCount
      */
     static async getAllNonPaginated(params) {
-        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, queryParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         // Set default field names
         const itemsField = options.itemsField || DEFAULT_ITEMS_FIELD;
         const totalCountField = options.totalCountField || DEFAULT_TOTAL_COUNT_FIELD;
@@ -7174,17 +7530,18 @@ class PaginationHelpers {
         // Make the API call based on method
         let response;
         if (method === HTTP_METHODS.POST) {
-            response = await serviceAccess.post(endpoint, additionalParams, { headers });
+            response = await serviceAccess.post(endpoint, additionalParams, { headers, params: queryParams });
         }
         else {
             response = await serviceAccess.get(endpoint, {
-                params: additionalParams,
+                params: { ...additionalParams, ...queryParams },
                 headers
             });
         }
         // Extract and transform items from response
-        // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N })
-        const rawItems = Array.isArray(response.data) ? response.data : response.data?.[itemsField];
+        // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N }).
+        // itemsField may be a dotted path (e.g. 'data.agents') for nested envelopes.
+        const rawItems = Array.isArray(response.data) ? response.data : resolveNestedField(response.data, itemsField);
         const rawTotalCount = Array.isArray(response.data) ? undefined : resolveNestedField(response.data, totalCountField);
         const totalCount = typeof rawTotalCount === 'number' ? rawTotalCount : undefined;
         // Parse items - automatically handle JSON string responses
@@ -7230,8 +7587,9 @@ class PaginationHelpers {
                 getEndpoint: config.getEndpoint,
                 folderId,
                 headers: config.headers,
-                paginationParams: cursor ? { cursor, pageSize } : jumpToPage ? { jumpToPage, pageSize } : { pageSize },
+                paginationParams: cursor ? { cursor, pageSize } : jumpToPage !== undefined ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
+                queryParams: config.queryParams,
                 transformFn: config.transformFn,
                 method: config.method,
                 options: {
@@ -7249,6 +7607,7 @@ class PaginationHelpers {
             folderId,
             headers: config.headers,
             additionalParams: prefixedOptions,
+            queryParams: config.queryParams,
             transformFn: config.transformFn,
             method: config.method,
             options: {
@@ -7385,18 +7744,17 @@ class BaseService {
         const params = this.validateAndPreparePaginationParams(paginationType, paginationOptions);
         // Prepare request parameters based on pagination type
         const requestParams = this.preparePaginationRequestParams(paginationType, params, options.pagination);
-        // For POST requests, merge pagination params into body and set params to undefined; for GET, use query params
+        // Route pagination state to wherever the API expects it (body for POST, URL for GET).
+        // Caller-supplied options.body / options.params are respected as-is — the api-client
+        // already handles params (URL) and body (request body) independently for every method.
         if (method.toUpperCase() === 'POST') {
             const existingBody = (options.body && typeof options.body === 'object') ? options.body : {};
             options.body = {
                 ...existingBody,
-                ...options.params,
                 ...requestParams
             };
-            options.params = undefined;
         }
         else {
-            // Merge pagination parameters with existing parameters
             options.params = {
                 ...options.params,
                 ...requestParams
@@ -7433,6 +7791,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) {
@@ -7440,7 +7800,8 @@ class BaseService {
                     }
                 }
                 else {
-                    requestParams[offsetParam] = params.pageNumber || 1;
+                    const sdkPageNumber = params.pageNumber || 1;
+                    requestParams[offsetParam] = zeroBased ? sdkPageNumber - 1 : sdkPageNumber;
                 }
                 {
                     requestParams[countParam] = true;
@@ -7469,8 +7830,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];
@@ -7553,12 +7915,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)
@@ -7572,30 +7934,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);
@@ -7606,10 +7968,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)
@@ -7806,6 +8168,14 @@ var SqlFieldType;
     SqlFieldType["MULTILINE"] = "MULTILINE";
 })(SqlFieldType || (SqlFieldType = {}));
 
+/**
+ * Numeric type IDs that pair with {@link EntityType} on reference payloads
+ * (entityType + entityTypeId travel together in `referenceEntity` /
+ * `referenceChoiceSet` bodies on cross-folder schema upserts).
+ */
+const ENTITY_TYPE_IDS = {
+    [exports.EntityType.ChoiceSet]: 1,
+};
 /**
  * Maps fields for Entities
  */
@@ -7939,6 +8309,7 @@ class EntityService extends BaseService {
      * Gets entity metadata by entity ID with attached operation methods
      *
      * @param id - UUID of the entity
+     * @param options - Optional {@link EntityGetByIdOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to entity metadata with schema information and operation methods
      *
      * @example
@@ -7948,6 +8319,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();
      *
@@ -7961,9 +8335,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
@@ -7975,7 +8349,7 @@ class EntityService extends BaseService {
      * Gets entity records by entity ID
      *
      * @param entityId - UUID of the entity
-     * @param options - Query options including expansionLevel and pagination options
+     * @param options - Query options including expansionLevel and pagination options The `folderKey` property is **experimental**.
      * @returns Promise resolving to an array of entity records or paginated response
      *
      * @example
@@ -8003,12 +8377,20 @@ class EntityService extends BaseService {
      *   cursor: paginatedResponse.nextCursor,
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * const records = await entities.getAllRecords("<entityId>", { folderKey: "<folderKey>" });
      * ```
      */
     async getAllRecords(entityId, options) {
+        // folderKey is header-only — destructure it out so PaginationHelpers doesn't serialise it
+        // into the query string as $folderKey.
+        const { folderKey, ...rest } = options ?? {};
+        const downstreamOptions = options === undefined ? undefined : rest;
         return PaginationHelpers.getAll({
             serviceAccess: this.createPaginationServiceAccess(),
             getEndpoint: () => DATA_FABRIC_ENDPOINTS.ENTITY.GET_ENTITY_RECORDS(entityId),
+            headers: createHeaders({ [FOLDER_KEY]: folderKey }),
             pagination: {
                 paginationType: PaginationType.OFFSET,
                 itemsField: ENTITY_PAGINATION.ITEMS_FIELD,
@@ -8020,14 +8402,14 @@ class EntityService extends BaseService {
                 }
             },
             excludeFromPrefix: ['expansionLevel'] // Don't add ODATA prefix to expansionLevel
-        }, options);
+        }, downstreamOptions);
     }
     /**
      * Gets a single entity record by entity ID and record ID
      *
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record
-     * @param options - Query options including expansionLevel
+     * @param options - Query options including `expansionLevel` and `folderKey` The `folderKey` property is **experimental**.
      * @returns Promise resolving to the entity record
      *
      * @example
@@ -8039,13 +8421,18 @@ class EntityService extends BaseService {
      * const record = await sdk.entities.getRecordById(<entityId>, <recordId>, {
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * const record = await sdk.entities.getRecordById(<entityId>, <recordId>, {
+     *   folderKey: "<folderKey>"
+     * });
      * ```
      */
     async getRecordById(entityId, recordId, options = {}) {
         const params = createParams({
             expansionLevel: options.expansionLevel
         });
-        const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_RECORD_BY_ID(entityId, recordId), { params });
+        const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_RECORD_BY_ID(entityId, recordId), { params, headers: createHeaders({ [FOLDER_KEY]: options.folderKey }) });
         return response.data;
     }
     /**
@@ -8053,7 +8440,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param data - Record to insert
-     * @param options - Insert options
+     * @param options - Insert options The `folderKey` property is **experimental**.
      * @returns Promise resolving to the inserted record with generated record ID
      *
      * @example
@@ -8069,6 +8456,11 @@ class EntityService extends BaseService {
      * const result = await entities.insertRecordById("<entityId>", { name: "John", age: 30 }, {
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.insertRecordById("<entityId>", { name: "John", age: 30 }, {
+     *   folderKey: "<folderKey>"
+     * });
      * ```
      */
     async insertRecordById(id, data, options = {}) {
@@ -8077,7 +8469,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;
     }
@@ -8086,7 +8478,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param data - Array of records to insert
-     * @param options - Insert options
+     * @param options - Insert options The `folderKey` property is **experimental**.
      * @returns Promise resolving to insert response
      *
      * @example
@@ -8109,6 +8501,12 @@ class EntityService extends BaseService {
      *   expansionLevel: 1,
      *   failOnFirst: true
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.insertRecordsById("<entityId>", [
+     *   { name: "John", age: 30 },
+     *   { name: "Jane", age: 25 }
+     * ], { folderKey: "<folderKey>" });
      * ```
      */
     async insertRecordsById(id, data, options = {}) {
@@ -8118,7 +8516,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;
     }
@@ -8128,7 +8526,7 @@ class EntityService extends BaseService {
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record to update
      * @param data - Key-value pairs of fields to update
-     * @param options - Update options
+     * @param options - Update options The `folderKey` property is **experimental**.
      * @returns Promise resolving to the updated record
      *
      * @example
@@ -8144,6 +8542,11 @@ class EntityService extends BaseService {
      * const result = await entities.updateRecordById("<entityId>", "<recordId>", { name: "John Updated", age: 31 }, {
      *   expansionLevel: 1
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.updateRecordById("<entityId>", "<recordId>", { name: "John Updated" }, {
+     *   folderKey: "<folderKey>"
+     * });
      * ```
      */
     async updateRecordById(entityId, recordId, data, options = {}) {
@@ -8152,7 +8555,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;
     }
@@ -8162,7 +8565,7 @@ class EntityService extends BaseService {
      * @param entityId - UUID of the entity
      * @param data - Array of records to update. Each record MUST contain the record Id,
      *               otherwise the update will fail.
-     * @param options - Update options
+     * @param options - Update options The `folderKey` property is **experimental**.
      * @returns Promise resolving to update response
      *
      * @example
@@ -8185,6 +8588,11 @@ class EntityService extends BaseService {
      *   expansionLevel: 1,
      *   failOnFirst: true
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.updateRecordsById("<entityId>", [
+     *   { Id: "123", name: "John Updated" }
+     * ], { folderKey: "<folderKey>" });
      * ```
      */
     async updateRecordsById(id, data, options = {}) {
@@ -8194,7 +8602,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;
     }
@@ -8205,7 +8613,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param recordIds - Array of record UUIDs to delete
-     * @param options - Delete options
+     * @param options - Delete options The `folderKey` property is **experimental**.
      * @returns Promise resolving to delete response
      *
      * @example
@@ -8218,6 +8626,11 @@ class EntityService extends BaseService {
      * const result = await entities.deleteRecordsById("<entityId>", [
      *   "<recordId-1>", "<recordId-2>"
      * ]);
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.deleteRecordsById("<entityId>", [
+     *   "<recordId-1>", "<recordId-2>"
+     * ], { folderKey: "<folderKey>" });
      * ```
      */
     async deleteRecordsById(id, recordIds, options = {}) {
@@ -8226,7 +8639,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;
     }
@@ -8238,6 +8651,7 @@ class EntityService extends BaseService {
      *
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record to delete
+     * @param options - Optional {@link EntityDeleteRecordByIdOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to void on success
      * @example
      * ```typescript
@@ -8246,14 +8660,23 @@ class EntityService extends BaseService {
      * const entities = new Entities(sdk);
      *
      * await entities.deleteRecordById("<entityId>", "<recordId>");
+     *
+     * // Folder-scoped: pass the entity's folder key
+     * await entities.deleteRecordById("<entityId>", "<recordId>", { folderKey: "<folderKey>" });
      * ```
      */
-    async deleteRecordById(entityId, recordId) {
-        await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE_RECORD_BY_ID(entityId, recordId));
+    async deleteRecordById(entityId, recordId, options) {
+        await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE_RECORD_BY_ID(entityId, recordId), { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
     }
     /**
-     * Gets all entities in the system
+     * Gets entities in the tenant.
      *
+     * Three call modes:
+     * - `getAll()` — default. Returns only tenant-level entities.
+     * - `getAll({ folderKey: "<uuid>" })` — preferred for folder-scoped data. Returns only entities in that folder.
+     * - `getAll({ includeFolderEntities: true })` — returns tenant-level **and** folder-level entities together. `folderKey` is preferred over `includeFolderEntities` when both are set.
+     *
+     * @param options - Optional {@link EntityGetAllOptions} (`folderKey` to list a single folder's entities — preferred when scoping to a folder; `includeFolderEntities: true` to list tenant + folder entities together) The `folderKey` property is **experimental**.
      * @returns Promise resolving to an array of entity metadata
      *
      * @example
@@ -8262,15 +8685,29 @@ class EntityService extends BaseService {
      *
      * const entities = new Entities(sdk);
      *
-     * // Get all entities
-     * const allEntities = await entities.getAll();
+     * // Tenant-only (default)
+     * const tenantEntities = await entities.getAll();
+     *
+     * // A single folder's entities (preferred when targeting a specific folder)
+     * const folderEntities = await entities.getAll({ folderKey: "<folderKey>" });
+     *
+     * // Tenant + folder entities together
+     * const allEntities = await entities.getAll({ includeFolderEntities: true });
      *
      * // Call operations on an entity
-     * const records = await allEntities[0].getAllRecords();
+     * const records = await tenantEntities[0].getAllRecords();
      * ```
      */
-    async getAll() {
-        const response = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_ALL);
+    async getAll(options) {
+        // folderKey is preferred over includeFolderEntities: when present, scope to that folder
+        // via the v1 endpoint + header. Only when no folderKey is given AND includeFolderEntities
+        // is explicitly true does the SDK switch to the v2 endpoint (returns tenant + folder
+        // entities together). Default (no options or includeFolderEntities omitted) stays on
+        // the v1 endpoint = tenant only.
+        const endpoint = !options?.folderKey && options?.includeFolderEntities
+            ? DATA_FABRIC_ENDPOINTS.ENTITY.GET_ALL_V2
+            : DATA_FABRIC_ENDPOINTS.ENTITY.GET_ALL;
+        const response = await this.get(endpoint, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         // Apply transformations
         const entities = response.data.map(entity => {
             // Transform each entity
@@ -8285,7 +8722,7 @@ class EntityService extends BaseService {
      * Queries entity records with filters, sorting, aggregates, and pagination
      *
      * @param id - UUID of the entity
-     * @param options - Query options including filterGroup, selectedFields, sortOptions, aggregates, groupBy, and pagination
+     * @param options - Query options including filterGroup, selectedFields, sortOptions, aggregates, groupBy, and pagination The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link NonPaginatedResponse} without pagination options,
      *   or {@link PaginatedResponse} when `pageSize`, `cursor`, or `jumpToPage` are provided
      *
@@ -8332,13 +8769,24 @@ class EntityService extends BaseService {
      *     { function: EntityAggregateFunction.Avg, field: "amount", alias: "avgAmount" },
      *   ],
      * });
+     *
+     * // Folder-scoped entity: pass the entity's folder key
+     * await entities.queryRecordsById("<entityId>", {
+     *   filterGroup: { queryFilters: [{ fieldName: "status", operator: QueryFilterOperator.Equals, value: "active" }] },
+     *   folderKey: "<folderKey>",
+     * });
      * ```
      */
     async queryRecordsById(id, options) {
+        // folderKey is header-only; expansionLevel must be sent as a query param by PaginationHelpers.
+        const { folderKey, expansionLevel, ...rest } = options ?? {};
+        const downstreamOptions = options === undefined ? undefined : rest;
         return PaginationHelpers.getAll({
             serviceAccess: this.createPaginationServiceAccess(),
             getEndpoint: () => DATA_FABRIC_ENDPOINTS.ENTITY.QUERY_BY_ID(id),
             method: HTTP_METHODS.POST,
+            headers: createHeaders({ [FOLDER_KEY]: folderKey }),
+            queryParams: createParams({ expansionLevel }),
             pagination: {
                 paginationType: PaginationType.OFFSET,
                 itemsField: ENTITY_PAGINATION.ITEMS_FIELD,
@@ -8349,14 +8797,15 @@ class EntityService extends BaseService {
                     countParam: ENTITY_OFFSET_PARAMS.COUNT_PARAM
                 }
             },
-            excludeFromPrefix: ['expansionLevel', 'filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
-        }, options);
+            excludeFromPrefix: ['filterGroup', 'selectedFields', 'sortOptions', 'aggregates', 'groupBy']
+        }, downstreamOptions);
     }
     /**
      * Imports records from a CSV file into an entity
      *
      * @param id - UUID of the entity
      * @param file - CSV file to import (Blob, File, or Uint8Array)
+     * @param options - Optional {@link EntityImportRecordsByIdOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to import result with record counts
      *
      * @example
@@ -8377,10 +8826,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]));
@@ -8388,7 +8839,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;
     }
     /**
@@ -8397,6 +8848,7 @@ class EntityService extends BaseService {
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record containing the attachment
      * @param fieldName - Name of the File-type field containing the attachment
+     * @param options - Optional {@link EntityDownloadAttachmentOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to Blob containing the file content
      *
      * @example
@@ -8415,11 +8867,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;
     }
@@ -8430,7 +8886,7 @@ class EntityService extends BaseService {
      * @param recordId - UUID of the record to upload the attachment to
      * @param fieldName - Name of the File-type field
      * @param file - File to upload (Blob, File, or Uint8Array)
-     * @param options - Optional {@link EntityUploadAttachmentOptions} (e.g. expansionLevel)
+     * @param options - Optional {@link EntityUploadAttachmentOptions} (e.g. `expansionLevel`, `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link EntityUploadAttachmentResponse}
      *
      * @example
@@ -8449,6 +8905,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) {
@@ -8460,7 +8919,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;
     }
     /**
@@ -8469,6 +8931,7 @@ class EntityService extends BaseService {
      * @param entityId - UUID of the entity
      * @param recordId - UUID of the record containing the attachment
      * @param fieldName - Name of the File-type field containing the attachment
+     * @param options - Optional {@link EntityDeleteAttachmentOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving to {@link EntityDeleteAttachmentResponse}
      *
      * @example
@@ -8487,10 +8950,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;
     }
     /**
@@ -8520,7 +8986,7 @@ class EntityService extends BaseService {
      * @param name - Entity name — must start with a letter and contain
      *   only letters, numbers, and underscores (e.g., `"productCatalog"`).
      * @param fields - Array of field definitions
-     * @param options - Optional entity-level settings ({@link EntityCreateOptions})
+     * @param options - Optional entity-level settings ({@link EntityCreateOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving to the ID of the created entity
      *
      * @example
@@ -8536,40 +9002,63 @@ class EntityService extends BaseService {
      *   { fieldName: "price", type: EntityFieldDataType.DECIMAL, decimalPrecision: 4, maxValue: 999999, minValue: 0 },
      *   { fieldName: "quantity", type: EntityFieldDataType.INTEGER, maxValue: 10000, minValue: 1, defaultValue: "0" },
      * ]);
+     *
+     * // Cross-folder references — link a folder-scoped entity to entities and
+     * // system choice sets that live in another folder or at the tenant level.
+     * await entities.create("orderLine", [
+     *   {
+     *     fieldName: "order",
+     *     type: EntityFieldDataType.RELATIONSHIP,
+     *     referenceEntityId: "<orderEntityId>",
+     *     referenceFieldId: "<orderEntityPkId>",
+     *     referenceFolderKey: "<otherFolderKey>",     // target lives in a different folder
+     *   },
+     *   {
+     *     fieldName: "userType",
+     *     type: EntityFieldDataType.CHOICE_SET_SINGLE,
+     *     choiceSetId: "<systemUserTypeChoiceSetId>", // tenant-level system choice set
+     *     // referenceFolderKey omitted → SDK looks up the target at tenant scope
+     *   },
+     * ], { folderKey: "<sourceFolderKey>" });
      * ```
      * @internal
      */
     async create(name, fields, options) {
         const opts = options ?? {};
+        const fieldPayloads = await this.buildFieldsWithReferenceMeta(fields);
         const payload = {
             ...(opts.description !== undefined && { description: opts.description }),
             displayName: opts.displayName ?? name,
             entityDefinition: {
                 name,
-                fields: fields.map(f => this.buildSchemaFieldPayload(f)),
+                fields: fieldPayloads,
                 folderId: opts.folderKey ?? DATA_FABRIC_TENANT_FOLDER_ID,
                 isRbacEnabled: opts.isRbacEnabled ?? false,
                 isInsightsEnabled: opts.isAnalyticsEnabled ?? false,
                 externalFields: opts.externalFields ?? [],
             },
         };
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPSERT, payload);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPSERT, payload, { headers: createHeaders({ [FOLDER_KEY]: opts.folderKey }) });
         return response.data;
     }
     /**
      * Deletes a Data Fabric entity and all its records
      *
      * @param id - UUID of the entity to delete
+     * @param options - Optional {@link EntityDeleteByIdOptions} (e.g. `folderKey` for folder-scoped entities) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the entity is deleted
      *
      * @example
      * ```typescript
      * await entities.deleteById("<entityId>");
+     *
+     * // Folder-scoped: pass the entity's folder key
+     * await entities.deleteById("<entityId>", { folderKey: "<folderKey>" });
      * ```
      * @internal
      */
-    async deleteById(id) {
-        await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE(id));
+    async deleteById(id, options) {
+        await this.delete(DATA_FABRIC_ENDPOINTS.ENTITY.DELETE(id), { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
     }
     /**
      * Updates an existing Data Fabric entity — schema and/or metadata.
@@ -8583,7 +9072,7 @@ class EntityService extends BaseService {
      * overwrite each other's changes.
      *
      * @param id - UUID of the entity to update
-     * @param options - Changes to apply ({@link EntityUpdateByIdOptions})
+     * @param options - Changes to apply ({@link EntityUpdateByIdOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the update is complete
      *
      * @example
@@ -8616,6 +9105,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
      */
@@ -8631,7 +9126,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 }) });
         }
     }
     /**
@@ -8642,7 +9137,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 ?? [])
@@ -8688,10 +9184,9 @@ class EntityService extends BaseService {
                 };
             });
         }
-        // Build and append new fields
         const newFields = [];
         if (options.addFields?.length) {
-            newFields.push(...options.addFields.map(f => this.buildSchemaFieldPayload(f)));
+            newFields.push(...await this.buildFieldsWithReferenceMeta(options.addFields));
         }
         await this.post(DATA_FABRIC_ENDPOINTS.ENTITY.UPSERT, {
             displayName: raw.displayName,
@@ -8705,7 +9200,7 @@ class EntityService extends BaseService {
                 isInsightsEnabled: raw.isInsightsEnabled ?? false,
                 externalFields: raw.externalFields ?? [],
             },
-        });
+        }, { headers: folderHeaders });
     }
     /**
      * Orchestrates all field mapping transformations
@@ -8789,8 +9284,39 @@ class EntityService extends BaseService {
             return externalSource;
         });
     }
+    async buildFieldsWithReferenceMeta(fields) {
+        const metas = await Promise.all(fields.map(f => this.buildReferenceMeta(f)));
+        return fields.map((f, i) => this.buildSchemaFieldPayload(f, metas[i]));
+    }
+    // Choice-set targets resolve server-side by NAME (the API rejects cross-folder
+    // refs with empty target name even when folderId is supplied), so the SDK
+    // fetches the name once for each cross-folder choice-set field. Relationship
+    // targets resolve by folderId — no lookup needed.
+    async buildReferenceMeta(field) {
+        if (field.referenceFolderKey === undefined)
+            return undefined;
+        if (field.referenceEntityId === undefined && field.choiceSetId === undefined)
+            return undefined;
+        const folderId = field.referenceFolderKey;
+        const meta = {};
+        if (field.referenceEntityId !== undefined) {
+            meta.referenceEntity = { id: field.referenceEntityId, folderId };
+        }
+        if (field.choiceSetId !== undefined) {
+            const lookupFolderKey = folderId === DATA_FABRIC_TENANT_FOLDER_ID ? undefined : folderId;
+            const target = await this.get(DATA_FABRIC_ENDPOINTS.ENTITY.GET_BY_ID(field.choiceSetId), { headers: createHeaders({ [FOLDER_KEY]: lookupFolderKey }) });
+            meta.referenceChoiceSet = {
+                id: field.choiceSetId,
+                name: target.data.name,
+                folderId,
+                entityType: exports.EntityType.ChoiceSet,
+                entityTypeId: ENTITY_TYPE_IDS[exports.EntityType.ChoiceSet],
+            };
+        }
+        return meta;
+    }
     /** Converts a user-facing EntityCreateFieldOptions to the raw API field payload */
-    buildSchemaFieldPayload(field) {
+    buildSchemaFieldPayload(field, refMeta) {
         const fieldType = field.type ?? exports.EntityFieldDataType.STRING;
         this.validateFieldConstraints(fieldType, field, field.fieldName);
         const isRelationship = fieldType === exports.EntityFieldDataType.RELATIONSHIP;
@@ -8801,6 +9327,10 @@ class EntityService extends BaseService {
             });
         }
         const mapping = EntitySchemaFieldTypeMap[fieldType];
+        // Prefer the resolved {id, name, folderId} body so cross-folder targets resolve
+        // server-side; fall back to a bare {id} when no meta was fetched.
+        const referenceEntityBody = refMeta?.referenceEntity ?? (field.referenceEntityId === undefined ? undefined : { id: field.referenceEntityId });
+        const referenceChoiceSetBody = refMeta?.referenceChoiceSet;
         return {
             name: field.fieldName,
             displayName: field.displayName ?? field.fieldName,
@@ -8819,7 +9349,8 @@ class EntityService extends BaseService {
             ...(field.choiceSetId !== undefined && { choiceSetId: field.choiceSetId }),
             ...((isRelationship || isFile) && { isForeignKey: true }),
             ...(isRelationship && { referenceType: exports.ReferenceType.ManyToOne }),
-            ...(field.referenceEntityId !== undefined && { referenceEntity: { id: field.referenceEntityId } }),
+            ...(referenceEntityBody !== undefined && { referenceEntity: referenceEntityBody }),
+            ...(referenceChoiceSetBody !== undefined && { referenceChoiceSet: referenceChoiceSetBody }),
             ...(field.referenceFieldId !== undefined && { referenceField: { id: field.referenceFieldId } }),
         };
     }
@@ -8982,8 +9513,14 @@ __decorate([
 
 class ChoiceSetService extends BaseService {
     /**
-     * Gets all choice sets in the system
+     * Gets choice sets in the tenant.
      *
+     * Three call modes:
+     * - `getAll()` — default. Returns only tenant-level choice sets.
+     * - `getAll({ folderKey: "<uuid>" })` — preferred for folder-scoped data. Returns only choice sets in that folder.
+     * - `getAll({ includeFolderChoiceSets: true })` — returns tenant-level **and** folder-level choice sets together. `folderKey` is preferred over `includeFolderChoiceSets` when both are set.
+     *
+     * @param options - Optional {@link ChoiceSetGetAllOptions} (`folderKey` to list a single folder's choice sets — preferred when scoping to a folder; `includeFolderChoiceSets: true` to list tenant + folder choice sets together) The `folderKey` property is **experimental**.
      * @returns Promise resolving to an array of choice set metadata
      *
      * @example
@@ -8992,18 +9529,33 @@ class ChoiceSetService extends BaseService {
      *
      * const choiceSets = new ChoiceSets(sdk);
      *
-     * // Get all choice sets
-     * const allChoiceSets = await choiceSets.getAll();
+     * // Tenant-only (default)
+     * const tenantChoiceSets = await choiceSets.getAll();
      *
-     * // Iterate through choice sets
-     * allChoiceSets.forEach(choiceSet => {
-     *   console.log(`ChoiceSet: ${choiceSet.displayName} (${choiceSet.name})`);
-     *   console.log(`Description: ${choiceSet.description}`);
-     * });
+     * // A single folder's choice sets (preferred when targeting a specific folder)
+     * const folderChoiceSets = await choiceSets.getAll({ folderKey: "<folderKey>" });
+     *
+     * // Tenant + folder choice sets together
+     * const allChoiceSets = await choiceSets.getAll({ includeFolderChoiceSets: true });
      * ```
      */
-    async getAll() {
-        const rawResponse = await this.get(DATA_FABRIC_ENDPOINTS.CHOICESETS.GET_ALL);
+    async getAll(options) {
+        return this.fetchAllChoiceSets(options);
+    }
+    /**
+     * Internal helper that performs the choice-set fetch. Kept separate from the
+     * public `getAll()` so that internal callers (e.g. `resolveChoiceSetName`)
+     * can reuse it without triggering double `@track` telemetry.
+     */
+    async fetchAllChoiceSets(options) {
+        // The choice-set endpoint returns cross-scope results when called without
+        // a folder header. To stay tenant-only by default, send the tenant-marker
+        // UUID as the folder key unless the caller explicitly opts into cross-scope
+        // via includeFolderChoiceSets: true. folderKey is preferred over
+        // includeFolderChoiceSets when both are set.
+        const folderKey = options?.folderKey
+            ?? (options?.includeFolderChoiceSets ? undefined : DATA_FABRIC_TENANT_FOLDER_ID);
+        const rawResponse = await this.get(DATA_FABRIC_ENDPOINTS.CHOICESETS.GET_ALL, { headers: createHeaders({ [FOLDER_KEY]: folderKey }) });
         // Transform field names
         const data = rawResponse.data || [];
         return data.map(choiceSet => transformData(choiceSet, EntityMap));
@@ -9016,7 +9568,7 @@ class ChoiceSetService extends BaseService {
      * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
      *
      * @param choiceSetId - UUID of the choice set
-     * @param options - Pagination options
+     * @param options - Pagination options and optional `folderKey` for folder-scoped choice sets The `folderKey` property is **experimental**.
      * @returns Promise resolving to choice set values or paginated result
      *
      * @example
@@ -9045,6 +9597,9 @@ class ChoiceSetService extends BaseService {
      * if (page1.hasNextPage) {
      *   const page2 = await choiceSets.getById(choiceSetId, { cursor: page1.nextCursor });
      * }
+     *
+     * // Folder-scoped choice set
+     * const folderValues = await choiceSets.getById(choiceSetId, { folderKey: "<folderKey>" });
      * ```
      */
     async getById(choiceSetId, options) {
@@ -9053,11 +9608,16 @@ class ChoiceSetService extends BaseService {
             const camelCased = pascalToCamelCaseKeys(item);
             return transformData(camelCased, EntityMap);
         };
+        // folderKey is header-only — destructure it out so PaginationHelpers doesn't
+        // include it in the POST body alongside pagination params.
+        const { folderKey, ...rest } = options ?? {};
+        const downstreamOptions = options === undefined ? undefined : rest;
         return PaginationHelpers.getAll({
             serviceAccess: this.createPaginationServiceAccess(),
             getEndpoint: () => DATA_FABRIC_ENDPOINTS.CHOICESETS.GET_BY_ID(choiceSetId),
             transformFn,
             method: HTTP_METHODS.POST,
+            headers: createHeaders({ [FOLDER_KEY]: folderKey }),
             pagination: {
                 paginationType: PaginationType.OFFSET,
                 itemsField: CHOICESET_VALUES_PAGINATION.ITEMS_FIELD,
@@ -9068,7 +9628,7 @@ class ChoiceSetService extends BaseService {
                     countParam: ENTITY_OFFSET_PARAMS.COUNT_PARAM
                 }
             }
-        }, options);
+        }, downstreamOptions);
     }
     /**
      * Creates a new Data Fabric choice set
@@ -9076,7 +9636,7 @@ class ChoiceSetService extends BaseService {
      * @param name - Choice set name. Must start with a
      *   letter, may contain only letters, numbers, and underscores, length
      *   3–100 characters (e.g., `"expenseTypes"`).
-     * @param options - Optional choice-set-level settings ({@link ChoiceSetCreateOptions})
+     * @param options - Optional choice-set-level settings ({@link ChoiceSetCreateOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving to the UUID of the created choice set
      *
      * @example
@@ -9107,7 +9667,7 @@ class ChoiceSetService extends BaseService {
                 folderId: opts.folderKey ?? DATA_FABRIC_TENANT_FOLDER_ID,
             },
         };
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.CREATE, payload);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.CREATE, payload, { headers: createHeaders({ [FOLDER_KEY]: opts.folderKey }) });
         return response.data;
     }
     /**
@@ -9117,7 +9677,7 @@ class ChoiceSetService extends BaseService {
      * the call throws `ValidationError` if both are omitted.
      *
      * @param choiceSetId - UUID of the choice set to update
-     * @param options - Metadata fields to change ({@link ChoiceSetUpdateOptions})
+     * @param options - Metadata fields to change ({@link ChoiceSetUpdateOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the update is complete
      *
      * @example
@@ -9142,12 +9702,13 @@ class ChoiceSetService extends BaseService {
         await this.patch(DATA_FABRIC_ENDPOINTS.CHOICESETS.UPDATE(choiceSetId), {
             ...(options.displayName !== undefined && { displayName: options.displayName }),
             ...(options.description !== undefined && { description: options.description }),
-        });
+        }, { headers: createHeaders({ [FOLDER_KEY]: options.folderKey }) });
     }
     /**
      * Deletes a Data Fabric choice set and all its values.
      *
      * @param choiceSetId - UUID of the choice set to delete
+     * @param options - Optional {@link ChoiceSetDeleteByIdOptions} (e.g. `folderKey` for folder-scoped choice sets) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the choice set is deleted
      *
      * @example
@@ -9157,18 +9718,21 @@ class ChoiceSetService extends BaseService {
      * const expenseTypes = allChoiceSets.find(cs => cs.name === 'expense_types');
      *
      * await choicesets.deleteById(expenseTypes.id);
+     *
+     * // Folder-scoped choice set
+     * await choicesets.deleteById(expenseTypes.id, { folderKey: "<folderKey>" });
      * ```
      * @internal
      */
-    async deleteById(choiceSetId) {
-        await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.DELETE(choiceSetId), {});
+    async deleteById(choiceSetId, options) {
+        await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.DELETE(choiceSetId), {}, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
     }
     /**
      * Inserts a single value into a choice set.
      *
      * @param choiceSetId - UUID of the parent choice set
      * @param name - Identifier name of the new value (e.g., `"TRAVEL"`)
-     * @param options - Optional fields ({@link ChoiceSetValueInsertOptions})
+     * @param options - Optional fields ({@link ChoiceSetValueInsertOptions}) The `folderKey` property is **experimental**.
      * @returns Promise resolving to the inserted value ({@link ChoiceSetValueInsertResponse})
      *
      * @example
@@ -9181,16 +9745,22 @@ class ChoiceSetService extends BaseService {
      *   displayName: 'Travel',
      * });
      * console.log(inserted.id);
+     *
+     * // Folder-scoped choice set: folderKey is required on the wire
+     * await choicesets.insertValueById(expenseTypes.id, 'TRAVEL', {
+     *   displayName: 'Travel',
+     *   folderKey: "<folderKey>",
+     * });
      * ```
      * @internal
      */
     async insertValueById(choiceSetId, name, options) {
-        const choiceSetName = await this.resolveChoiceSetName(choiceSetId);
+        const choiceSetName = await this.resolveChoiceSetName(choiceSetId, options?.folderKey);
         const payload = {
             Name: name,
             ...(options?.displayName !== undefined && { DisplayName: options.displayName }),
         };
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.INSERT_BY_NAME(choiceSetName), payload);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.INSERT_BY_NAME(choiceSetName), payload, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         const camelCased = pascalToCamelCaseKeys(response.data);
         return transformData(camelCased, EntityMap);
     }
@@ -9203,6 +9773,7 @@ class ChoiceSetService extends BaseService {
      * @param choiceSetId - UUID of the parent choice set
      * @param valueId - UUID of the value to update
      * @param displayName - New human-readable display name for the value
+     * @param options - Optional {@link ChoiceSetValueUpdateOptions} — pass `folderKey` for folder-scoped choice sets; omit for tenant-level. The `folderKey` property is **experimental**.
      * @returns Promise resolving to the updated value ({@link ChoiceSetValueUpdateResponse})
      *
      * @example
@@ -9214,13 +9785,18 @@ class ChoiceSetService extends BaseService {
      * const travel = values.items.find(v => v.name === 'TRAVEL');
      *
      * await choicesets.updateValueById(expenseTypes.id, travel.id, 'Business Travel');
+     *
+     * // Folder-scoped choice set: folderKey is required on the wire
+     * await choicesets.updateValueById(expenseTypes.id, travel.id, 'Business Travel', {
+     *   folderKey: "<folderKey>",
+     * });
      * ```
      * @internal
      */
-    async updateValueById(choiceSetId, valueId, displayName) {
-        const choiceSetName = await this.resolveChoiceSetName(choiceSetId);
+    async updateValueById(choiceSetId, valueId, displayName, options) {
+        const choiceSetName = await this.resolveChoiceSetName(choiceSetId, options?.folderKey);
         const payload = { DisplayName: displayName };
-        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.UPDATE_BY_NAME(choiceSetName, valueId), payload);
+        const response = await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.UPDATE_BY_NAME(choiceSetName, valueId), payload, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
         const camelCased = pascalToCamelCaseKeys(response.data);
         return transformData(camelCased, EntityMap);
     }
@@ -9229,6 +9805,7 @@ class ChoiceSetService extends BaseService {
      *
      * @param choiceSetId - UUID of the parent choice set
      * @param valueIds - Array of value UUIDs to delete
+     * @param options - Optional {@link ChoiceSetValueDeleteOptions} (e.g. `folderKey` for folder-scoped choice sets) The `folderKey` property is **experimental**.
      * @returns Promise resolving when the values are deleted
      *
      * @example
@@ -9238,14 +9815,20 @@ class ChoiceSetService extends BaseService {
      * const idsToDelete = values.items.slice(0, 2).map(v => v.id);
      *
      * await choicesets.deleteValuesById('<choiceSetId>', idsToDelete);
+     *
+     * // Folder-scoped choice set
+     * await choicesets.deleteValuesById('<choiceSetId>', idsToDelete, { folderKey: "<folderKey>" });
      * ```
      * @internal
      */
-    async deleteValuesById(choiceSetId, valueIds) {
-        await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.DELETE_BY_ID(choiceSetId), valueIds);
+    async deleteValuesById(choiceSetId, valueIds, options) {
+        await this.post(DATA_FABRIC_ENDPOINTS.CHOICESETS.DELETE_BY_ID(choiceSetId), valueIds, { headers: createHeaders({ [FOLDER_KEY]: options?.folderKey }) });
     }
-    async resolveChoiceSetName(choiceSetId) {
-        const all = await this.getAll();
+    async resolveChoiceSetName(choiceSetId, folderKey) {
+        // Use the un-tracked helper directly so we don't fire a duplicate
+        // `Choicesets.GetAll` telemetry event for every insertValueById /
+        // updateValueById call.
+        const all = await this.fetchAllChoiceSets(folderKey === undefined ? undefined : { folderKey });
         const match = all.find(cs => cs.id === choiceSetId);
         if (!match) {
             throw new NotFoundError({ message: `Choice set with id '${choiceSetId}' not found.` });
@@ -9297,6 +9880,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);
         }
     };
 }
@@ -9358,6 +9948,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
+        }
+    };
+}
 
 /**
  * Maps fields for Incident entities
@@ -9522,7 +10134,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)
@@ -9588,6 +10202,40 @@ exports.DebugMode = void 0;
     DebugMode["SingleStep"] = "SingleStep";
 })(exports.DebugMode || (exports.DebugMode = {}));
 
+/**
+ * Maestro Cases Models
+ * Model classes for Maestro cases
+ */
+/**
+ * Creates methods for a case object
+ *
+ * @param caseData - The case data (response from API)
+ * @param service - The cases service instance
+ * @returns Object containing case methods
+ */
+function createCaseMethods(caseData, service) {
+    return {
+        getElementStats(startTime, endTime, packageVersion) {
+            if (!caseData.processKey)
+                throw new Error('Process key is undefined');
+            if (!caseData.packageId)
+                throw new Error('Package ID is undefined');
+            return service.getElementStats(caseData.processKey, caseData.packageId, startTime, endTime, packageVersion);
+        }
+    };
+}
+/**
+ * Creates an actionable case by combining API case data with operational methods.
+ *
+ * @param caseData - The case data from API
+ * @param service - The cases service instance
+ * @returns A case object with added methods
+ */
+function createCaseWithMethods(caseData, service) {
+    const methods = createCaseMethods(caseData, service);
+    return Object.assign({}, caseData, methods);
+}
+
 /**
  * Case Instance Types
  * Types and interfaces for Maestro case instance management
@@ -9799,12 +10447,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 {
     /**
@@ -9885,11 +10527,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
@@ -10381,6 +11078,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')
@@ -10403,6 +11135,9 @@ __decorate([
 __decorate([
     track('MaestroProcesses.GetTopExecutionDuration')
 ], MaestroProcessesService.prototype, "getTopExecutionDuration", null);
+__decorate([
+    track('MaestroProcesses.GetElementStats')
+], MaestroProcessesService.prototype, "getElementStats", null);
 
 /**
  * Service class for Maestro Process Incidents
@@ -10458,7 +11193,7 @@ var ProcessType;
 class CasesService extends BaseService {
     /**
      * Get all case management processes with their instance statistics
-     * @returns Promise resolving to array of Case objects
+     * @returns Promise resolving to an array of {@link CaseGetAllWithMethodsResponse}
      *
      * @example
      * ```typescript
@@ -10482,10 +11217,10 @@ class CasesService extends BaseService {
         const response = await this.get(MAESTRO_ENDPOINTS.PROCESSES.GET_ALL, { params });
         // Extract processes array from response data and add name field
         const cases = response.data?.processes || [];
-        return cases.map(caseItem => ({
+        return cases.map(caseItem => createCaseWithMethods({
             ...caseItem,
             name: this.extractCaseName(caseItem.packageId)
-        }));
+        }, this));
     }
     /**
      * Get the top 5 case processes ranked by run count within a time range.
@@ -10704,6 +11439,40 @@ class CasesService extends BaseService {
         const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.TOP_PROCESSES_BY_DURATION, buildInsightsTopBody(startTime, endTime, true, options));
         return (data ?? []).map(process => ({ ...process, name: this.extractCaseName(process.packageId) }));
     }
+    /**
+     * Get element stats for case 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 case.
+     *
+     * @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 case
+     * const elements = await cases.getElementStats(
+     *   '<processKey>',
+     *   '<packageId>',
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   '1.0.1'
+     * );
+     *
+     * // Find elements with failures
+     * const failedElements = elements.filter(e => e.failCount > 0);
+     * for (const element of failedElements) {
+     *   console.log(`Failed element: ${element.elementId}, failures: ${element.failCount}`);
+     * }
+     * ```
+     */
+    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 ?? [];
+    }
     /**
      * Extract a readable case name from the packageId
      * @param packageId - The full package identifier
@@ -10741,6 +11510,9 @@ __decorate([
 __decorate([
     track('Cases.GetTopExecutionDuration')
 ], CasesService.prototype, "getTopExecutionDuration", null);
+__decorate([
+    track('Cases.GetElementStats')
+], CasesService.prototype, "getElementStats", null);
 
 /**
  * Maps fields for Case Instance entities to ensure consistent naming
@@ -10825,17 +11597,19 @@ function createTaskMethods(taskData, service) {
         async assign(options) {
             if (!taskData.id)
                 throw new Error('Task ID is undefined');
+            const criteria = options.assignmentCriteria !== undefined ? { assignmentCriteria: options.assignmentCriteria } : {};
             const assignmentOptions = 'userId' in options && options.userId !== undefined
-                ? { taskId: taskData.id, userId: options.userId }
-                : { taskId: taskData.id, userNameOrEmail: options.userNameOrEmail };
+                ? { taskId: taskData.id, userId: options.userId, ...criteria }
+                : { taskId: taskData.id, userNameOrEmail: options.userNameOrEmail, ...criteria };
             return service.assign(assignmentOptions);
         },
         async reassign(options) {
             if (!taskData.id)
                 throw new Error('Task ID is undefined');
+            const criteria = options.assignmentCriteria !== undefined ? { assignmentCriteria: options.assignmentCriteria } : {};
             const assignmentOptions = 'userId' in options && options.userId !== undefined
-                ? { taskId: taskData.id, userId: options.userId }
-                : { taskId: taskData.id, userNameOrEmail: options.userNameOrEmail };
+                ? { taskId: taskData.id, userId: options.userId, ...criteria }
+                : { taskId: taskData.id, userNameOrEmail: options.userNameOrEmail, ...criteria };
             return service.reassign(assignmentOptions);
         },
         async unassign() {
@@ -11148,6 +11922,26 @@ class TaskService extends BaseService {
      *   }
      * ]);
      * ```
+     *
+     * @example Group assignment
+     * ```typescript
+     * import { TaskAssignmentCriteria } from '@uipath/uipath-typescript/tasks';
+     *
+     * // Assign to a directory group by userId + criteria — Action Center
+     * // distributes the task across the group's members based on the criteria
+     * const result = await tasks.assign({
+     *   taskId: 123,
+     *   userId: 456, // a DirectoryGroup id from tasks.getUsers()
+     *   assignmentCriteria: TaskAssignmentCriteria.AllUsers
+     * });
+     *
+     * // ...or identify the group by name instead of id
+     * const result2 = await tasks.assign({
+     *   taskId: 123,
+     *   userNameOrEmail: "My Group",
+     *   assignmentCriteria: TaskAssignmentCriteria.AllUsers
+     * });
+     * ```
      */
     async assign(taskAssignments) {
         // Normalize input to array
@@ -11199,6 +11993,25 @@ class TaskService extends BaseService {
      *   }
      * ]);
      * ```
+     *
+     * @example Group reassignment
+     * ```typescript
+     * import { TaskAssignmentCriteria } from '@uipath/uipath-typescript/tasks';
+     *
+     * // Reassign to a directory group by userId + criteria
+     * const result = await tasks.reassign({
+     *   taskId: 123,
+     *   userId: 456, // a DirectoryGroup id from tasks.getUsers()
+     *   assignmentCriteria: TaskAssignmentCriteria.AllUsers
+     * });
+     *
+     * // ...or identify the group by name instead of id
+     * const result2 = await tasks.reassign({
+     *   taskId: 123,
+     *   userNameOrEmail: "My Group",
+     *   assignmentCriteria: TaskAssignmentCriteria.AllUsers
+     * });
+     * ```
      */
     async reassign(taskAssignments) {
         // Normalize input to array
@@ -11949,37 +12762,6 @@ function validateName(resourceType, name) {
     return trimmed;
 }
 
-/**
- * Encodes a folder path for the `X-UIPATH-FolderPath-Encoded` header.
- *
- * Orchestrator decodes this header as **base64-encoded UTF-16 LE bytes**
- * (see `HttpHeadersProviderExtensions.GetDecoded` + `OrganizationUnitProvider`
- * in the Orchestrator repo, which call `Encoding.Unicode.GetString(...)`).
- * URL-encoding is NOT what the server expects — it must be base64-of-UTF-16-LE
- * bytes.
- *
- * @param folderPath - The folder path (e.g. 'Shared/Finance')
- * @returns Base64 string suitable for the `X-UIPATH-FolderPath-Encoded` header
- */
-function encodeFolderPathHeader(folderPath) {
-    // Force little-endian regardless of host byte order. `Uint16Array` viewed
-    // as `Uint8Array` would use the host's native order — correct on LE hosts
-    // (x86/ARM-LE) but wrong on BE hosts. `DataView.setUint16(..., true)`
-    // pins LE.
-    const buf = new ArrayBuffer(folderPath.length * 2);
-    const view = new DataView(buf);
-    for (let i = 0; i < folderPath.length; i++) {
-        view.setUint16(i * 2, folderPath.charCodeAt(i), true);
-    }
-    const bytes = new Uint8Array(buf);
-    let binary = '';
-    for (let i = 0; i < bytes.byteLength; i++) {
-        binary += String.fromCharCode(bytes[i]);
-    }
-    // btoa is browser-native; Node 16+ also has it as a global
-    return btoa(binary);
-}
-
 /**
  * Resolves folder context into the appropriate Orchestrator folder headers.
  *
@@ -12127,6 +12909,26 @@ function describeFolderForError(folderId, folderKey, folderPath) {
     return '';
 }
 
+/**
+ * Enum for Asset Value Scope
+ */
+exports.AssetValueScope = void 0;
+(function (AssetValueScope) {
+    AssetValueScope["Global"] = "Global";
+    AssetValueScope["PerRobot"] = "PerRobot";
+})(exports.AssetValueScope || (exports.AssetValueScope = {}));
+/**
+ * Enum for Asset Value Type
+ */
+exports.AssetValueType = void 0;
+(function (AssetValueType) {
+    AssetValueType["Text"] = "Text";
+    AssetValueType["Bool"] = "Bool";
+    AssetValueType["Integer"] = "Integer";
+    AssetValueType["Credential"] = "Credential";
+    AssetValueType["Secret"] = "Secret";
+})(exports.AssetValueType || (exports.AssetValueType = {}));
+
 /**
  * Maps fields for Asset entities to ensure consistent naming
  */
@@ -12251,6 +13053,68 @@ class AssetService extends FolderScopedService {
     async getByName(name, options = {}) {
         return this.getByNameLookup('Asset', ASSET_ENDPOINTS.GET_BY_FOLDER, name, options, (raw) => transformData(pascalToCamelCaseKeys(raw), AssetMap));
     }
+    /**
+     * Updates the value of an existing asset by ID.
+     *
+     * Fetches the asset internally to determine its type, then updates only the value while
+     * preserving the asset's name, scope, and description.
+     *
+     * **Supported value types:** `Text`, `Integer`, and `Bool` only. Other types
+     * (`Credential`, `Secret`) throw a `ValidationError`.
+     *
+     * The `newValue` runtime type must match the asset's `valueType`:
+     * - `Text` → `string`
+     * - `Integer` → `number` (integer)
+     * - `Bool` → `boolean`
+     *
+     * @param id - Asset ID
+     * @param newValue - New value to apply (string for `Text`, number for `Integer`, boolean for `Bool`)
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`)
+     * @returns Promise resolving when the asset has been updated
+     *
+     * @example
+     * ```typescript
+     * import { Assets } from '@uipath/uipath-typescript/assets';
+     *
+     * const assets = new Assets(sdk);
+     *
+     * // Update a Text asset by folder ID
+     * await assets.updateValueById(<assetId>, 'new-value', { folderId: <folderId> });
+     *
+     * // Update an Integer asset by folder key (GUID)
+     * await assets.updateValueById(<assetId>, 42, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // Update a Bool asset by folder path
+     * await assets.updateValueById(<assetId>, true, { folderPath: 'Shared/Finance' });
+     * ```
+     */
+    async updateValueById(id, newValue, options) {
+        if (!id) {
+            throw new ValidationError({ message: 'id is required for updateValueById' });
+        }
+        if (newValue === null || newValue === undefined) {
+            throw new ValidationError({ message: 'newValue is required for updateValueById' });
+        }
+        const headers = resolveFolderHeaders({
+            folderId: options?.folderId,
+            folderKey: options?.folderKey,
+            folderPath: options?.folderPath,
+            resourceType: 'Assets.updateValueById',
+            fallbackFolderKey: this.config.folderKey,
+        });
+        const existingResponse = await this.get(ASSET_ENDPOINTS.GET_BY_ID(id), { headers });
+        const existing = existingResponse.data;
+        const valueField = resolveValueField(id, existing.ValueType, newValue);
+        const body = {
+            Id: id,
+            Name: existing.Name,
+            ValueScope: existing.ValueScope,
+            ValueType: existing.ValueType,
+            Description: existing.Description,
+            [valueField]: newValue,
+        };
+        await this.put(ASSET_ENDPOINTS.GET_BY_ID(id), body, { headers });
+    }
 }
 __decorate([
     track('Assets.GetAll')
@@ -12261,30 +13125,42 @@ __decorate([
 __decorate([
     track('Assets.GetByName')
 ], AssetService.prototype, "getByName", null);
-
-/**
- * Enum for Asset Value Scope
- */
-exports.AssetValueScope = void 0;
-(function (AssetValueScope) {
-    AssetValueScope["Global"] = "Global";
-    AssetValueScope["PerRobot"] = "PerRobot";
-})(exports.AssetValueScope || (exports.AssetValueScope = {}));
+__decorate([
+    track('Assets.UpdateValueById')
+], AssetService.prototype, "updateValueById", null);
 /**
- * Enum for Asset Value Type
+ * Maps the asset's `valueType` to the PUT body field carrying the new value, validating
+ * that the new value's runtime type matches the asset type.
  */
-exports.AssetValueType = void 0;
-(function (AssetValueType) {
-    AssetValueType["DBConnectionString"] = "DBConnectionString";
-    AssetValueType["HttpConnectionString"] = "HttpConnectionString";
-    AssetValueType["Text"] = "Text";
-    AssetValueType["Bool"] = "Bool";
-    AssetValueType["Integer"] = "Integer";
-    AssetValueType["Credential"] = "Credential";
-    AssetValueType["WindowsCredential"] = "WindowsCredential";
-    AssetValueType["KeyValueList"] = "KeyValueList";
-    AssetValueType["Secret"] = "Secret";
-})(exports.AssetValueType || (exports.AssetValueType = {}));
+function resolveValueField(id, valueType, newValue) {
+    switch (valueType) {
+        case exports.AssetValueType.Text:
+            if (typeof newValue !== 'string') {
+                throw new ValidationError({
+                    message: `Asset ${id} has valueType Text; newValue must be a string, got ${typeof newValue}`,
+                });
+            }
+            return 'StringValue';
+        case exports.AssetValueType.Integer:
+            if (typeof newValue !== 'number' || !Number.isInteger(newValue)) {
+                throw new ValidationError({
+                    message: `Asset ${id} has valueType Integer; newValue must be an integer number, got ${typeof newValue}`,
+                });
+            }
+            return 'IntValue';
+        case exports.AssetValueType.Bool:
+            if (typeof newValue !== 'boolean') {
+                throw new ValidationError({
+                    message: `Asset ${id} has valueType Bool; newValue must be a boolean, got ${typeof newValue}`,
+                });
+            }
+            return 'BoolValue';
+        default:
+            throw new ValidationError({
+                message: `updateValueById only supports Text, Integer, or Bool assets; asset ${id} has valueType ${valueType}`,
+            });
+    }
+}
 
 /**
  * Maps fields for Bucket entities to ensure consistent naming
@@ -12421,48 +13297,32 @@ class BucketService extends FolderScopedService {
             }
         }, options);
     }
-    /**
-     * Gets metadata for files in a bucket with optional filtering and pagination
-     *
-     * The method returns either:
-     * - A NonPaginatedResponse with items array (when no pagination parameters are provided)
-     * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
-     *
-     * @param bucketId - The ID of the bucket to get file metadata from
-     * @param folderId - Required folder ID for organization unit context
-     * @param options - Optional parameters for filtering, pagination and access URL generation
-     * @returns Promise resolving to the list of file metadata in the bucket or paginated result
-     *
-     * @example
-     * ```typescript
-     * import { Buckets } from '@uipath/uipath-typescript/buckets';
-     *
-     * const buckets = new Buckets(sdk);
-     *
-     * // Get metadata for all files in a bucket
-     * const fileMetadata = await buckets.getFileMetaData(123, 456);
-     *
-     * // Get file metadata with a specific prefix
-     * const fileMetadata = await buckets.getFileMetaData(123, 456, {
-     *   prefix: '/folder1'
-     * });
-     *
-     * // First page with pagination
-     * const page1 = await buckets.getFileMetaData(123, 456, { pageSize: 10 });
-     *
-     * // Navigate using cursor
-     * if (page1.hasNextPage) {
-     *   const page2 = await buckets.getFileMetaData(123, 456, { cursor: page1.nextCursor });
-     * }
-     * ```
-     */
-    async getFileMetaData(bucketId, folderId, options) {
+    async getFileMetaData(bucketId, optionsOrFolderId, legacyOptions) {
         if (!bucketId) {
             throw new ValidationError({ message: 'bucketId is required for getFileMetaData' });
         }
-        if (!folderId) {
-            throw new ValidationError({ message: 'folderId is required for getFileMetaData' });
+        // Normalize the two overload forms into a single internal shape.
+        let folderId;
+        let folderKey;
+        let folderPath;
+        let restOptions;
+        if (typeof optionsOrFolderId === 'number') {
+            // Deprecated positional form: getFileMetaData(bucketId, folderId, options?)
+            folderId = optionsOrFolderId;
+            restOptions = (legacyOptions ?? {});
+        }
+        else {
+            // Preferred form: getFileMetaData(bucketId, options?)
+            const opts = optionsOrFolderId ?? {};
+            ({ folderId, folderKey, folderPath, ...restOptions } = opts);
         }
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: 'Buckets.getFileMetaData',
+            fallbackFolderKey: this.config.folderKey,
+        });
         // Transformation function for blob items
         const transformBlobItem = (item) => transformData(item, BucketMap);
         return PaginationHelpers.getAll({
@@ -12478,93 +13338,97 @@ class BucketService extends FolderScopedService {
                     tokenParam: BUCKET_TOKEN_PARAMS.TOKEN_PARAM
                 }
             },
-            excludeFromPrefix: ['prefix'] // Bucket-specific param, not OData
-        }, { ...options, folderId });
+            excludeFromPrefix: ['prefix'], // Bucket-specific param, not OData
+            headers,
+        }, restOptions);
     }
-    /**
-     * Uploads a file to a bucket
-     *
-     * @param options - Options for file upload including bucket ID, folder ID, path, content, and optional parameters
-     * @returns Promise resolving to a response with success status and HTTP status code
-     *
-     * @example
-     * ```typescript
-     * import { Buckets } from '@uipath/uipath-typescript/buckets';
-     *
-     * const buckets = new Buckets(sdk);
-     *
-     * // Upload a file from browser
-     * const file = new File(['file content'], 'example.txt');
-     * const result = await buckets.uploadFile({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/example.txt',
-     *   content: file
-     * });
-     *
-     * // In Node env with Buffer
-     * const buffer = Buffer.from('file content');
-     * const result = await buckets.uploadFile({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/example.txt',
-     *   content: buffer
-     * });
-     * ```
-     */
-    async uploadFile(options) {
-        const { bucketId, folderId, path, content } = options;
+    async uploadFile(bucketIdOrOptions, path, content, options) {
+        // Normalize the two overload forms into a single internal shape.
+        let bucketId;
+        let resolvedPath;
+        let resolvedContent;
+        let folderId;
+        let folderKey;
+        let folderPath;
+        if (bucketIdOrOptions !== null && typeof bucketIdOrOptions === 'object') {
+            // Deprecated options-only form: uploadFile({ bucketId, path, content, ... })
+            ({ bucketId, path: resolvedPath, content: resolvedContent, folderId, folderKey, folderPath } = bucketIdOrOptions);
+        }
+        else {
+            // Preferred positional form: uploadFile(bucketId, path, content, options?)
+            bucketId = bucketIdOrOptions;
+            resolvedPath = path;
+            resolvedContent = content;
+            const opts = options ?? {};
+            ({ folderId, folderKey, folderPath } = opts);
+        }
         if (!bucketId) {
             throw new ValidationError({ message: 'bucketId is required for uploadFile' });
         }
-        if (!folderId) {
-            throw new ValidationError({ message: 'folderId is required for uploadFile' });
-        }
-        if (!path) {
+        if (!resolvedPath) {
             throw new ValidationError({ message: 'path is required for uploadFile' });
         }
-        if (!content) {
+        if (!resolvedContent) {
             throw new ValidationError({ message: 'content is required for uploadFile' });
         }
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: 'Buckets.uploadFile',
+            fallbackFolderKey: this.config.folderKey,
+        });
         const uriResponse = await this._getWriteUri({
             bucketId,
-            folderId,
-            path,
+            path: resolvedPath,
+            headers,
         });
         // Upload file to the provided URI
-        const response = await this._uploadToUri(uriResponse, content);
+        const response = await this._uploadToUri(uriResponse, resolvedContent);
         return {
             success: response.status >= 200 && response.status < 300,
             statusCode: response.status
         };
     }
-    /**
-     * Gets a direct download URL for a file in the bucket
-     *
-     * @param options - Contains bucketId, folderId, file path and optional expiry time
-     * @returns Promise resolving to blob file access information
-     *
-     * @example
-     * ```typescript
-     * import { Buckets } from '@uipath/uipath-typescript/buckets';
-     *
-     * const buckets = new Buckets(sdk);
-     *
-     * // Get download URL for a file
-     * const fileAccess = await buckets.getReadUri({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/file.pdf'
-     * });
-     * ```
-     */
-    async getReadUri(options) {
-        const { bucketId, folderId, path, expiryInMinutes, ...restOptions } = options;
+    async getReadUri(bucketIdOrOptions, path, options) {
+        // Normalize the two overload forms into a single internal shape.
+        let bucketId;
+        let resolvedPath;
+        let folderId;
+        let folderKey;
+        let folderPath;
+        let expiryInMinutes;
+        let restOptions;
+        if (bucketIdOrOptions !== null && typeof bucketIdOrOptions === 'object') {
+            // Deprecated options-only form: getReadUri({ bucketId, path, ... })
+            const { bucketId: bid, path: p, expiryInMinutes: e, folderId: fid, folderKey: fkey, folderPath: fpath, ...rest } = bucketIdOrOptions;
+            bucketId = bid;
+            resolvedPath = p;
+            expiryInMinutes = e;
+            folderId = fid;
+            folderKey = fkey;
+            folderPath = fpath;
+            restOptions = rest;
+        }
+        else {
+            // Preferred positional form: getReadUri(bucketId, path, options?)
+            bucketId = bucketIdOrOptions;
+            resolvedPath = path;
+            const opts = options ?? {};
+            ({ expiryInMinutes, folderId, folderKey, folderPath, ...restOptions } = opts);
+        }
+        const headers = resolveFolderHeaders({
+            folderId,
+            folderKey,
+            folderPath,
+            resourceType: 'Buckets.getReadUri',
+            fallbackFolderKey: this.config.folderKey,
+        });
         const queryOptions = {
             expiryInMinutes,
             ...addPrefixToKeys(restOptions, ODATA_PREFIX, Object.keys(restOptions))
         };
-        return this._getUri(BUCKET_ENDPOINTS.GET_READ_URI(bucketId), bucketId, folderId, path, queryOptions);
+        return this._getUri(BUCKET_ENDPOINTS.GET_READ_URI(bucketId), bucketId, resolvedPath, headers, queryOptions);
     }
     /**
      * Uploads content to the provided URI
@@ -12594,23 +13458,18 @@ class BucketService extends FolderScopedService {
      * Private method to handle common URI request logic
      * @param endpoint - The API endpoint to call
      * @param bucketId - The bucket ID
-     * @param folderId - The folder ID
      * @param path - The file path
+     * @param headers - Pre-built folder-context headers (built via `resolveFolderHeaders`)
      * @param queryOptions - Additional query parameters
      * @returns Promise resolving to blob file access information
      */
-    async _getUri(endpoint, bucketId, folderId, path, queryOptions = {}) {
+    async _getUri(endpoint, bucketId, path, headers, queryOptions = {}) {
         if (!bucketId) {
             throw new ValidationError({ message: 'bucketId is required for getUri' });
         }
-        if (!folderId) {
-            throw new ValidationError({ message: 'folderId is required for getUri' });
-        }
         if (!path) {
             throw new ValidationError({ message: 'path is required for getUri' });
         }
-        // Create headers with required folder ID
-        const headers = createHeaders({ [FOLDER_ID]: folderId });
         // Filter out undefined values and build query params
         const queryParams = filterUndefined({
             path,
@@ -12745,16 +13604,16 @@ class BucketService extends FolderScopedService {
     /**
      * Gets a direct upload URL for a file in the bucket
      *
-     * @param options - Contains bucketId, folderId, file path, optional expiry time
+     * @param options - Contains bucketId, file path, optional expiry time, and pre-built folder-context headers
      * @returns Promise resolving to blob file access information
      */
     async _getWriteUri(options) {
-        const { bucketId, folderId, path, expiryInMinutes, ...restOptions } = options;
+        const { bucketId, path, expiryInMinutes, headers, ...restOptions } = options;
         const queryOptions = {
             expiryInMinutes,
             ...addPrefixToKeys(restOptions, ODATA_PREFIX, Object.keys(restOptions))
         };
-        return this._getUri(BUCKET_ENDPOINTS.GET_WRITE_URI(bucketId), bucketId, folderId, path, queryOptions);
+        return this._getUri(BUCKET_ENDPOINTS.GET_WRITE_URI(bucketId), bucketId, path, headers, queryOptions);
     }
 }
 __decorate([
@@ -14201,6 +15060,57 @@ exports.FeedbackStatus = void 0;
     FeedbackStatus[FeedbackStatus["Dismissed"] = 2] = "Dismissed";
 })(exports.FeedbackStatus || (exports.FeedbackStatus = {}));
 
+/**
+ * Columns available for ordering results.
+ */
+exports.AgentListSortColumn = void 0;
+(function (AgentListSortColumn) {
+    AgentListSortColumn["AgentName"] = "AgentName";
+    AgentListSortColumn["ParentProcess"] = "ParentProcess";
+    AgentListSortColumn["LastRun"] = "LastRun";
+    AgentListSortColumn["HealthScore"] = "HealthScore";
+    AgentListSortColumn["LastIncident"] = "LastIncident";
+    AgentListSortColumn["FolderName"] = "FolderName";
+    /** Quantity of AGU (Agent Units) consumed */
+    AgentListSortColumn["QuantityAGU"] = "QuantityAGU";
+    /** Quantity of PLTU (Platform Units) consumed */
+    AgentListSortColumn["QuantityPLTU"] = "QuantityPLTU";
+    AgentListSortColumn["FolderPath"] = "FolderPath";
+})(exports.AgentListSortColumn || (exports.AgentListSortColumn = {}));
+/**
+ * Columns available for ordering / grouping the agent errors list.
+ */
+exports.AgentErrorSortColumn = void 0;
+(function (AgentErrorSortColumn) {
+    AgentErrorSortColumn["AgentId"] = "AgentId";
+    AgentErrorSortColumn["AgentName"] = "AgentName";
+    AgentErrorSortColumn["ParentProcessName"] = "ParentProcessName";
+    AgentErrorSortColumn["ErrorTitle"] = "ErrorTitle";
+    AgentErrorSortColumn["FirstSeenStartTime"] = "FirstSeenStartTime";
+    AgentErrorSortColumn["ExecutionCount"] = "ExecutionCount";
+    AgentErrorSortColumn["Type"] = "Type";
+    AgentErrorSortColumn["FirstSeenFolderName"] = "FirstSeenFolderName";
+    AgentErrorSortColumn["FirstSeenFolderPath"] = "FirstSeenFolderPath";
+    AgentErrorSortColumn["LastSeenStartTime"] = "LastSeenStartTime";
+    AgentErrorSortColumn["LastSeenFolderName"] = "LastSeenFolderName";
+    AgentErrorSortColumn["LastSeenFolderPath"] = "LastSeenFolderPath";
+})(exports.AgentErrorSortColumn || (exports.AgentErrorSortColumn = {}));
+
+/**
+ * Types for the Agent Memory metrics service.
+ */
+/**
+ * Execution kind to filter Agent Memory queries by. Omit to include both
+ * Debug and Runtime executions.
+ */
+exports.AgentMemoryExecutionType = void 0;
+(function (AgentMemoryExecutionType) {
+    /** Executions produced during agent debugging sessions. */
+    AgentMemoryExecutionType["Debug"] = "Debug";
+    /** Executions produced during production runtime. */
+    AgentMemoryExecutionType["Runtime"] = "Runtime";
+})(exports.AgentMemoryExecutionType || (exports.AgentMemoryExecutionType = {}));
+
 // Auto-generated from the OpenAPI spec — do not edit manually.
 var DocumentActionPriority;
 (function (DocumentActionPriority) {
@@ -14472,6 +15382,103 @@ var index = /*#__PURE__*/Object.freeze({
     get WordGroupType () { return WordGroupType; }
 });
 
+/**
+ * Governance Service Types
+ *
+ * Public types exposed via `@uipath/uipath-typescript/governance`.
+ */
+exports.PolicyEvaluationResult = void 0;
+(function (PolicyEvaluationResult) {
+    /** Active policy permitted the action. */
+    PolicyEvaluationResult["Allow"] = "Allow";
+    /** Active policy blocked the action. */
+    PolicyEvaluationResult["Deny"] = "Deny";
+    /** Simulated (NoOp) policy would have permitted the action. */
+    PolicyEvaluationResult["SimulatedAllow"] = "SimulatedAllow";
+    /** Simulated (NoOp) policy would have blocked the action. */
+    PolicyEvaluationResult["SimulatedDeny"] = "SimulatedDeny";
+})(exports.PolicyEvaluationResult || (exports.PolicyEvaluationResult = {}));
+
+/** Status of a span: whether it completed successfully, with an error, or was not set. */
+exports.SpanStatus = void 0;
+(function (SpanStatus) {
+    SpanStatus["Unset"] = "Unset";
+    SpanStatus["Ok"] = "Ok";
+    SpanStatus["Error"] = "Error";
+    /** Span is still in progress. */
+    SpanStatus["Running"] = "Running";
+    /** Span data is hidden from the caller due to tenant/folder permission rules. */
+    SpanStatus["Restricted"] = "Restricted";
+    /** Span was cancelled before completion. */
+    SpanStatus["Cancelled"] = "Cancelled";
+})(exports.SpanStatus || (exports.SpanStatus = {}));
+/** Platform source that produced the span. */
+exports.SpanSource = void 0;
+(function (SpanSource) {
+    SpanSource["Testing"] = "Testing";
+    SpanSource["Agents"] = "Agents";
+    SpanSource["ProcessOrchestration"] = "ProcessOrchestration";
+    SpanSource["ApiWorkflows"] = "ApiWorkflows";
+    SpanSource["Robots"] = "Robots";
+    SpanSource["ConversationalAgentsService"] = "ConversationalAgentsService";
+    SpanSource["IntegrationServiceTrigger"] = "IntegrationServiceTrigger";
+    SpanSource["Playground"] = "Playground";
+    SpanSource["Governance"] = "Governance";
+    /** Intelligent Experience Platform — unstructured and complex document processing source. */
+    SpanSource["IXPUnstructuredAndComplexDocuments"] = "IXPUnstructuredAndComplexDocuments";
+    /** Agents authored in code (as opposed to visual/no-code designers). */
+    SpanSource["CodedAgents"] = "CodedAgents";
+    /** Intelligent Experience Platform — communications mining source. */
+    SpanSource["IXPCommunicationsMining"] = "IXPCommunicationsMining";
+    /** UiPath Context Grounding — span produced by the Enterprise Context Service for RAG/knowledge-base operations. */
+    SpanSource["EnterpriseContextService"] = "EnterpriseContextService";
+    /** Model Context Protocol — span produced by an MCP server integration. */
+    SpanSource["MCP"] = "MCP";
+    /** Agent-to-Agent — span produced by an A2A protocol call between agents. */
+    SpanSource["A2A"] = "A2A";
+    /** Serverless — span produced by a serverless function execution. */
+    SpanSource["Serverless"] = "Serverless";
+})(exports.SpanSource || (exports.SpanSource = {}));
+/** Minimum severity level of events captured in the span. */
+exports.SpanVerbosityLevel = void 0;
+(function (SpanVerbosityLevel) {
+    SpanVerbosityLevel["Verbose"] = "Verbose";
+    SpanVerbosityLevel["Trace"] = "Trace";
+    SpanVerbosityLevel["Information"] = "Information";
+    SpanVerbosityLevel["Warning"] = "Warning";
+    SpanVerbosityLevel["Error"] = "Error";
+    SpanVerbosityLevel["Critical"] = "Critical";
+    SpanVerbosityLevel["Off"] = "Off";
+})(exports.SpanVerbosityLevel || (exports.SpanVerbosityLevel = {}));
+/** Whether the span was produced during a debug or production runtime. */
+exports.SpanExecutionType = void 0;
+(function (SpanExecutionType) {
+    SpanExecutionType["Debug"] = "Debug";
+    SpanExecutionType["Runtime"] = "Runtime";
+})(exports.SpanExecutionType || (exports.SpanExecutionType = {}));
+/** Whether the caller has permission to read this span's data. */
+exports.SpanPermissionStatus = void 0;
+(function (SpanPermissionStatus) {
+    SpanPermissionStatus["Allow"] = "Allow";
+    /** Some span fields are redacted due to permission constraints (e.g. attributes visible but payload hidden). */
+    SpanPermissionStatus["PartialBlock"] = "PartialBlock";
+    SpanPermissionStatus["Block"] = "Block";
+})(exports.SpanPermissionStatus || (exports.SpanPermissionStatus = {}));
+/** Storage provider that created or manages the attachment. */
+exports.SpanAttachmentProvider = void 0;
+(function (SpanAttachmentProvider) {
+    SpanAttachmentProvider["Orchestrator"] = "Orchestrator";
+    /** Span attachment stored by the observability platform. */
+    SpanAttachmentProvider["LLMOps"] = "LLMOps";
+})(exports.SpanAttachmentProvider || (exports.SpanAttachmentProvider = {}));
+/** Whether the attachment is an input, output, or neither. */
+exports.SpanAttachmentDirection = void 0;
+(function (SpanAttachmentDirection) {
+    SpanAttachmentDirection["None"] = "None";
+    SpanAttachmentDirection["In"] = "In";
+    SpanAttachmentDirection["Out"] = "Out";
+})(exports.SpanAttachmentDirection || (exports.SpanAttachmentDirection = {}));
+
 /**
  * Asset resolution utilities for UiPath Coded Apps
  *
@@ -14548,6 +15555,7 @@ function getAppBase() {
 }
 
 exports.AgentMap = AgentMap;
+exports.AgentTraceExecutionType = exports.SpanExecutionType;
 exports.AuthenticationError = AuthenticationError;
 exports.AuthorizationError = AuthorizationError;
 exports.ConversationGetAllFilterMap = ConversationGetAllFilterMap;
@@ -14571,6 +15579,7 @@ exports.UserSettingsMap = UserSettingsMap;
 exports.ValidationError = ValidationError;
 exports.createAgentWithMethods = createAgentWithMethods;
 exports.createCaseInstanceWithMethods = createCaseInstanceWithMethods;
+exports.createCaseWithMethods = createCaseWithMethods;
 exports.createConversationWithMethods = createConversationWithMethods;
 exports.createEntityWithMethods = createEntityWithMethods;
 exports.createJobWithMethods = createJobWithMethods;