@uipath/uipath-typescript 1.3.6 → 1.3.8

package/dist/conversational-agent/index.cjs

@@ -51,7 +51,7 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
 // Connection string placeholder that will be replaced during build
 const CONNECTION_STRING = "InstrumentationKey=a6efa11d-1feb-4508-9738-e13e12dcae5e;IngestionEndpoint=https://westeurope-5.in.applicationinsights.azure.com/;LiveEndpoint=https://westeurope.livediagnostics.monitor.azure.com/;ApplicationId=7c58eb1c-9581-4ba6-839e-11725848a037";
 // SDK Version placeholder 
-const SDK_VERSION = "1.3.6";
+const SDK_VERSION = "1.3.8";
 const VERSION = "Version";
 const SERVICE = "Service";
 const CLOUD_ORGANIZATION_NAME = "CloudOrganizationName";
@@ -805,6 +805,21 @@ const RESPONSE_TYPES = {
  * in Conversational Agents Service)
  */
 const EXTERNAL_USER_ID = 'x-uipath-external-user-id';
+/**
+ * Optional identifier used in UiPath logs to identify the implementing service
+ * of requests. External consumers do not need to set it; the server logs
+ * missing values as "unknown".
+ *
+ * @internal
+ */
+const CONVERSATIONAL_SURFACE_NAME = 'x-uipath-conversational-surfacename';
+/**
+ * Optional version of the implementing service of requests. Paired with
+ * `surfaceName` for internal telemetry.
+ *
+ * @internal
+ */
+const CONVERSATIONAL_SURFACE_VERSION = 'x-uipath-conversational-surfaceversion';
 /**
  * Query parameter keys sent during WebSocket connection
  */
@@ -812,6 +827,8 @@ const WEBSOCKET_QUERY_PARAMS = {
     ORGANIZATION_ID: 'x-uipath-internal-accountid',
     TENANT_ID: 'x-uipath-internal-tenantid',
     EXTERNAL_USER_ID,
+    CONVERSATIONAL_SURFACE_NAME,
+    CONVERSATIONAL_SURFACE_VERSION,
 };
 
 class ApiClient {
@@ -939,6 +956,27 @@ var PaginationType;
 /**
  * Collection of utility functions for working with objects
  */
+/**
+ * Resolves a field value from an object, supporting both direct keys (e.g., '@odata.count')
+ * and dot-separated nested paths (e.g., 'pagination.totalCount').
+ * Direct key match takes priority over nested traversal.
+ */
+function resolveNestedField(data, fieldPath) {
+    if (!data) {
+        return undefined;
+    }
+    if (fieldPath in data) {
+        return data[fieldPath];
+    }
+    if (!fieldPath.includes('.')) {
+        return undefined;
+    }
+    let value = data;
+    for (const part of fieldPath.split('.')) {
+        value = value?.[part];
+    }
+    return value;
+}
 /**
  * Filters out undefined values from an object
  * @param obj The source object
@@ -1188,6 +1226,10 @@ const CONVERSATIONAL_TOKEN_PARAMS = {
     TOKEN_PARAM: 'cursor'
 };
 
+/**
+ * Converts a UTC timestamp string (e.g., "5/8/2026 11:20:17 AM") to ISO 8601 UTC format.
+ * Returns the original value if parsing fails.
+ */
 /**
  * Transforms data by mapping fields according to the provided field mapping
  * @param data The source data to transform
@@ -1557,7 +1599,8 @@ class PaginationHelpers {
         // Extract and transform items from response
         // Handle both plain array responses and envelope responses ({ value: [...], totalRecordCount: N })
         const rawItems = Array.isArray(response.data) ? response.data : response.data?.[itemsField];
-        const totalCount = Array.isArray(response.data) ? undefined : response.data?.[totalCountField];
+        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
         const parsedItems = typeof rawItems === 'string' ? JSON.parse(rawItems) : (rawItems || []);
         const items = transformFn ? parsedItems.map(transformFn) : parsedItems;
@@ -1733,8 +1776,9 @@ class BaseService {
     constructor(instance, headers) {
         // Private field - not visible via Object.keys() or any reflection
         _BaseService_apiClient.set(this, void 0);
-        const { config, context, tokenManager } = SDKInternalsRegistry.get(instance);
+        const { config, context, tokenManager, folderKey } = SDKInternalsRegistry.get(instance);
         __classPrivateFieldSet(this, _BaseService_apiClient, new ApiClient(config, context, tokenManager, headers ? { headers } : {}), "f");
+        this.config = { folderKey };
     }
     /**
      * Gets a valid authentication token, refreshing if necessary.
@@ -1853,9 +1897,17 @@ class BaseService {
                 const pageSizeParam = paginationParams?.pageSizeParam || ODATA_OFFSET_PARAMS.PAGE_SIZE_PARAM;
                 const offsetParam = paginationParams?.offsetParam || ODATA_OFFSET_PARAMS.OFFSET_PARAM;
                 const countParam = paginationParams?.countParam || ODATA_OFFSET_PARAMS.COUNT_PARAM;
+                // 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;
                 requestParams[pageSizeParam] = limitedPageSize;
-                if (params.pageNumber && params.pageNumber > 1) {
-                    requestParams[offsetParam] = (params.pageNumber - 1) * limitedPageSize;
+                if (convertToSkip) {
+                    if (params.pageNumber && params.pageNumber > 1) {
+                        requestParams[offsetParam] = (params.pageNumber - 1) * limitedPageSize;
+                    }
+                }
+                else {
+                    requestParams[offsetParam] = params.pageNumber || 1;
                 }
                 {
                     requestParams[countParam] = true;
@@ -1886,7 +1938,8 @@ class BaseService {
         // 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] || []);
-        const totalCount = Array.isArray(response.data) ? undefined : response.data[totalCountField];
+        const rawTotalCount = Array.isArray(response.data) ? undefined : resolveNestedField(response.data, totalCountField);
+        const totalCount = typeof rawTotalCount === 'number' ? rawTotalCount : undefined;
         const continuationToken = response.data[continuationTokenField];
         // Determine if there are more pages
         const hasMore = this.determineHasMorePages(paginationType, {
@@ -2180,7 +2233,7 @@ const AgentMap = {
 };
 
 /**
- * Constants for User Service
+ * Constants for User Settings Service
  */
 /**
  * Maps fields for User Settings entities to ensure consistent SDK naming
@@ -2950,6 +3003,7 @@ class ToolCallEventHelper extends ConversationEventHelperBase {
         this.toolCallId = toolCallId;
         this.startEventMaybe = startEventMaybe;
         this._endHandlers = new Array();
+        this._confirmHandlers = new Array();
         this.addStartEventTimestamp(startEventMaybe);
     }
     /**
@@ -3011,6 +3065,29 @@ class ToolCallEventHelper extends ConversationEventHelperBase {
     onEndToolCall(cb) {
         this.onToolCallEnd(cb);
     }
+    /**
+     * Registers a handler for tool call confirmation events. Fired when the
+     * peer responds to a tool call that was emitted with `requireConfirmation`.
+     * @returns Cleanup function to remove the handler.
+     */
+    onToolCallConfirm(callback) {
+        this._confirmHandlers.push(callback);
+        return () => {
+            const index = this._confirmHandlers.indexOf(callback);
+            if (index >= 0)
+                this._confirmHandlers.splice(index, 1);
+        };
+    }
+    /**
+     * Sends a tool call confirmation (approve/reject) for a tool call that was
+     * emitted with `requireConfirmation: true`. Replaces the legacy
+     * `sendInterruptEnd` flow for tool call confirmation.
+     * @throws Error if tool call has already ended.
+     */
+    sendToolCallConfirm(confirmToolCall) {
+        this.assertNotEnded();
+        this.emit({ confirmToolCall });
+    }
     /**
      * Sends an error start event for this tool call.
      */
@@ -3086,6 +3163,10 @@ class ToolCallEventHelperImpl extends ToolCallEventHelper {
         if (toolCallEvent.toolCallError?.endError) {
             this.dispatchErrorEnd(toolCallEvent.toolCallError.errorId, toolCallEvent.toolCallError.endError);
         }
+        if (toolCallEvent.confirmToolCall) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            this._confirmHandlers.forEach(cb => cb(toolCallEvent.confirmToolCall));
+        }
         if (toolCallEvent.endToolCall) {
             this.setEnded();
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -3129,6 +3210,7 @@ class MessageEventHelper extends ConversationEventHelperBase {
         this._toolCallMap = new Map();
         this._interruptStartHandlers = new Array();
         this._interruptEndHandlers = new Array();
+        this._toolCallConfirmHandlers = new Array();
         this.addStartEventTimestamp(startEventMaybe);
     }
     /**
@@ -3367,6 +3449,25 @@ class MessageEventHelper extends ConversationEventHelperBase {
                 this._interruptEndHandlers.splice(index, 1);
         };
     }
+    /**
+     * Registers a handler for tool-call confirmation events. Fired when a peer
+     * responds to a tool call that was emitted with `requireConfirmation: true`.
+     *
+     * Fires at the message level before the event is delegated to the per-tool-call
+     * helper, so this handler runs even when no `ToolCallEventHelper` exists for the
+     * confirmed tool call (e.g. on the agent side after the originating helper has
+     * been cleaned up, or on the client side if no `onToolCallStart` is registered).
+     *
+     * @returns Cleanup function to remove the handler.
+     */
+    onToolCallConfirm(callback) {
+        this._toolCallConfirmHandlers.push(callback);
+        return () => {
+            const index = this._toolCallConfirmHandlers.indexOf(callback);
+            if (index >= 0)
+                this._toolCallConfirmHandlers.splice(index, 1);
+        };
+    }
     /**
      * Sends an interrupt start event.
      */
@@ -3494,6 +3595,16 @@ class MessageEventHelperImpl extends MessageEventHelper {
                 contentPartHelper.dispatch(messageEvent.contentPart);
         }
         if (messageEvent.toolCall) {
+            // Dispatch confirmToolCall at the message level (flat dispatch) before delegating
+            // to the per-tool-call helper. Needed because the tool-call helper may not exist
+            // for this id on the receiving side.
+            if (messageEvent.toolCall.confirmToolCall) {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                this._toolCallConfirmHandlers.forEach(cb => cb({
+                    toolCallId: messageEvent.toolCall.toolCallId,
+                    confirmEvent: messageEvent.toolCall.confirmToolCall
+                }));
+            }
             let toolCallHelper = this._toolCallMap.get(messageEvent.toolCall.toolCallId);
             if (!toolCallHelper && this._toolCallStartHandlers.length > 0) {
                 toolCallHelper = new ToolCallEventHelperImpl(this, messageEvent.toolCall.toolCallId, messageEvent.toolCall.startToolCall);
@@ -4994,6 +5105,27 @@ function transformMessage(message) {
     };
 }
 
+/**
+ * Header builder for Conversational Agent Services
+ *
+ * Builds the default request headers shared across the Conversational Agent
+ * service constructors (`ConversationalAgentService`, `ConversationService`,
+ * `ExchangeService`, `MessageService`) from a single set of options.
+ */
+/**
+ * Builds the default request headers for Conversational Agent service calls
+ * from the provided options. Returns `undefined` when no headers apply, so
+ * the SDK does not pass an empty `headers` bag down to the HTTP layer.
+ */
+function buildConversationalAgentHeaders(options) {
+    const headers = createHeaders({
+        [EXTERNAL_USER_ID]: options?.externalUserId,
+        [CONVERSATIONAL_SURFACE_NAME]: options?.surfaceName,
+        [CONVERSATIONAL_SURFACE_VERSION]: options?.surfaceVersion,
+    });
+    return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
 /**
  * ExchangeService - Exchange operations for Conversations
  *
@@ -5033,7 +5165,7 @@ class ExchangeService extends BaseService {
      * @param options - Optional configuration (e.g. externalUserId for external app auth)
      */
     constructor(instance, options) {
-        super(instance, options?.externalUserId ? { [EXTERNAL_USER_ID]: options.externalUserId } : undefined);
+        super(instance, buildConversationalAgentHeaders(options));
     }
     /**
      * Gets all exchanges for a conversation with optional filtering and pagination
@@ -5696,6 +5828,8 @@ class WebSocketSession extends BaseWebSocket {
             logLevel: options?.logLevel
         }, context, tokenManager, WEBSOCKET_LOGGER_PREFIX);
         this._externalUserId = options?.externalUserId;
+        this._surfaceName = options?.surfaceName;
+        this._surfaceVersion = options?.surfaceVersion;
     }
     /**
      * Connects to WebSocket with organization and tenant headers
@@ -5714,6 +5848,12 @@ class WebSocketSession extends BaseWebSocket {
         if (this._externalUserId) {
             query[WEBSOCKET_QUERY_PARAMS.EXTERNAL_USER_ID] = this._externalUserId;
         }
+        if (this._surfaceName) {
+            query[WEBSOCKET_QUERY_PARAMS.CONVERSATIONAL_SURFACE_NAME] = this._surfaceName;
+        }
+        if (this._surfaceVersion) {
+            query[WEBSOCKET_QUERY_PARAMS.CONVERSATIONAL_SURFACE_VERSION] = this._surfaceVersion;
+        }
         this.connectWithOptions({ query });
     }
     /**
@@ -6010,7 +6150,7 @@ class ConversationService extends BaseService {
      * @param options - Optional configuration (e.g. externalUserId for external app auth)
      */
     constructor(instance, options) {
-        super(instance, options?.externalUserId ? { [EXTERNAL_USER_ID]: options.externalUserId } : undefined);
+        super(instance, buildConversationalAgentHeaders(options));
         /** Event helper for conversation events */
         this._eventHelper = null;
         this._sessionManager = new SessionManager(instance, options);
@@ -6421,7 +6561,7 @@ class MessageService extends BaseService {
      * @param options - Optional configuration (e.g. externalUserId for external app auth)
      */
     constructor(instance, options) {
-        super(instance, options?.externalUserId ? { [EXTERNAL_USER_ID]: options.externalUserId } : undefined);
+        super(instance, buildConversationalAgentHeaders(options));
     }
     /**
      * Gets a message by ID
@@ -6482,6 +6622,87 @@ __decorate([
     track('ConversationalAgent.Messages.GetContentPartById')
 ], MessageService.prototype, "getContentPartById", null);
 
+/**
+ * UserSettingsService - Service for managing user profile and context settings
+ */
+/**
+ * Service for reading and updating the current user's profile and context settings.
+ *
+ * User settings are user-supplied profile fields (name, email, role, department, company,
+ * country, timezone) that the SDK passes to a UiPath Conversational Agent on every conversation
+ * so the agent can personalize its responses.
+ */
+class UserSettingsService extends BaseService {
+    /**
+     * Creates an instance of the UserSettingsService.
+     *
+     * @param instance - UiPath SDK instance providing authentication and configuration
+     * @param options - Optional configuration (e.g. externalUserId for external app auth)
+     */
+    constructor(instance, options) {
+        super(instance, options?.externalUserId ? { [EXTERNAL_USER_ID]: options.externalUserId } : undefined);
+    }
+    /**
+     * Gets the current user's profile and context settings.
+     *
+     * Returns the full user settings record — profile fields the agent uses for personalization
+     * (name, email, role, department, company, country, timezone) plus identifiers and timestamps.
+     * Fields the user has not set are returned as `null`.
+     *
+     * @returns Promise resolving to the current user's settings
+     * {@link UserSettingsGetResponse}
+     *
+     * @example
+     * ```typescript
+     * const settings = await conversationalAgent.user.getSettings();
+     * console.log(settings.name);      // e.g. 'John Doe' or null
+     * console.log(settings.email);     // e.g. 'john@example.com' or null
+     * console.log(settings.timezone);  // e.g. 'America/New_York' or null
+     * ```
+     */
+    async getSettings() {
+        const response = await this.get(USER_ENDPOINTS.SETTINGS);
+        return transformData(response.data, UserSettingsMap);
+    }
+    /**
+     * Updates the current user's profile and context settings.
+     *
+     * Accepts a partial payload — only fields included in `options` are changed. Pass `null` to
+     * explicitly clear a field. Omitting a field leaves it unchanged. Returns the full updated
+     * settings record.
+     *
+     * @param options - Fields to update; omit fields to leave them unchanged, set to `null` to clear
+     * @returns Promise resolving to the updated user settings
+     * {@link UserSettingsUpdateResponse}
+     *
+     * @example Partial update
+     * ```typescript
+     * const updated = await conversationalAgent.user.updateSettings({
+     *   name: 'John Doe',
+     *   timezone: 'America/New_York'
+     * });
+     * ```
+     *
+     * @example Clear fields by setting to null
+     * ```typescript
+     * await conversationalAgent.user.updateSettings({
+     *   role: null,
+     *   department: null
+     * });
+     * ```
+     */
+    async updateSettings(options) {
+        const response = await this.patch(USER_ENDPOINTS.SETTINGS, options);
+        return transformData(response.data, UserSettingsMap);
+    }
+}
+__decorate([
+    track('ConversationalAgent.UserSettings.GetSettings')
+], UserSettingsService.prototype, "getSettings", null);
+__decorate([
+    track('ConversationalAgent.UserSettings.UpdateSettings')
+], UserSettingsService.prototype, "updateSettings", null);
+
 /**
  * ConversationalAgentService - Main entry point for Conversational Agent functionality
  */
@@ -6496,9 +6717,10 @@ class ConversationalAgentService extends BaseService {
      * @param options - Optional configuration (e.g. externalUserId for external app auth)
      */
     constructor(instance, options) {
-        super(instance, options?.externalUserId ? { [EXTERNAL_USER_ID]: options.externalUserId } : undefined);
+        super(instance, buildConversationalAgentHeaders(options));
         // Create conversation service with WebSocket support
         this.conversations = new ConversationService(instance, options);
+        this.user = new UserSettingsService(instance, options);
     }
     /**
      * Registers a handler that is called whenever the WebSocket connection status changes.
@@ -6584,78 +6806,6 @@ __decorate([
     track('ConversationalAgent.GetById')
 ], ConversationalAgentService.prototype, "getById", null);
 
-/**
- * UserService - Service for managing user profile and context settings
- */
-/**
- * Service for managing user profile and context settings
- *
- * User settings are passed to the agent for all conversations
- * to provide user context (name, email, role, timezone, etc.).
- *
- * @internal
- */
-class UserService extends BaseService {
-    /**
-     * Gets the current user's profile and context settings
-     *
-     * @returns Promise resolving to user settings object containing profile information
-     *
-     * @example
-     * ```typescript
-     * const userSettings = await userService.getSettings();
-     * console.log(userSettings.name);      // User's name
-     * console.log(userSettings.email);     // User's email
-     * console.log(userSettings.timezone);  // User's timezone
-     * ```
-     */
-    async getSettings() {
-        const response = await this.get(USER_ENDPOINTS.SETTINGS);
-        return transformData(response.data, UserSettingsMap);
-    }
-    /**
-     * Updates the current user's profile and context settings
-     *
-     * All fields are optional - only send the fields you want to change.
-     * Set fields to `null` to explicitly clear them.
-     * Omitting fields means no change.
-     *
-     * @param options - Fields to update
-     * @returns Promise resolving to updated user settings object
-     *
-     * @example
-     * ```typescript
-     * // Update specific fields
-     * const updatedUserSettings = await userService.updateSettings({
-     *   name: 'John Doe',
-     *   email: 'john@example.com',
-     *   timezone: 'America/New_York'
-     * });
-     *
-     * // Partial update - only change timezone
-     * await userService.updateSettings({
-     *   timezone: 'Europe/London'
-     * });
-     *
-     * // Clear fields by setting to null
-     * await userService.updateSettings({
-     *   role: null,
-     *   department: null
-     * });
-     * ```
-     */
-    async updateSettings(options) {
-        const response = await this.patch(USER_ENDPOINTS.SETTINGS, options);
-        return transformData(response.data, UserSettingsMap);
-    }
-}
-__decorate([
-    track('ConversationalAgent.User.GetSettings')
-], UserService.prototype, "getSettings", null);
-__decorate([
-    track('ConversationalAgent.User.UpdateSettings')
-], UserService.prototype, "updateSettings", null);
-
 exports.AgentMap = AgentMap;
 exports.AsyncInputStreamEventHelper = AsyncInputStreamEventHelper;
 exports.AsyncInputStreamEventHelperImpl = AsyncInputStreamEventHelperImpl;
@@ -6686,9 +6836,9 @@ exports.SessionEventHelper = SessionEventHelper;
 exports.SessionEventHelperImpl = SessionEventHelperImpl;
 exports.ToolCallEventHelper = ToolCallEventHelper;
 exports.ToolCallEventHelperImpl = ToolCallEventHelperImpl;
-exports.User = UserService;
-exports.UserService = UserService;
+exports.UserSettings = UserSettingsService;
 exports.UserSettingsMap = UserSettingsMap;
+exports.UserSettingsService = UserSettingsService;
 exports.assertCitationSourceMedia = assertCitationSourceMedia;
 exports.assertCitationSourceUrl = assertCitationSourceUrl;
 exports.assertExternalValue = assertExternalValue;