@egain/ai-agent-sdk 0.1.0

package/dist/core/AiAgent.d.ts

@@ -0,0 +1,1126 @@
+import { ConnectionState } from './connection/ConnectionState.js';
+import { AuthenticationInput } from './auth/AuthenticationService.js';
+import { EventEmitter } from './events/EventEmitter.js';
+import { CacheConfig, type UserDetails } from './api/ApiHelper.js';
+import { MessageProcessor } from './message/MessageProcessor.js';
+import { Message } from './message/Message.js';
+import { MessageHandlerResult } from './message/types.js';
+import { Logger } from './logging/Logger.js';
+import { LogLevel } from './logging/LogLevel.js';
+import { TranscriptConfig, TranscriptOptions, TranscriptEntry } from './message/Transcript.js';
+import type { Portal, UserProfile, AgentListItem } from './types/PortalTypes.js';
+import type { CallerInfo, CallTranscriptEntry } from './platform/HookContract.js';
+export type { UserDetails } from './api/ApiHelper.js';
+/**
+ * Configuration options for creating an AiAgent instance.
+ *
+ * @example
+ * ```typescript
+ * const config: AiAgentConfig = {
+ *   id: "123-456-789",
+ *   endpoint: "https://api.egain.com",
+ *   auth: { type: "pre-auth", accessToken: "your-access-token" },
+ *   autoConnect: true,
+ *   logLevel: LogLevel.DEBUG
+ * };
+ * ```
+ *
+ * @category Core
+ */
+export interface AiAgentConfig {
+    /**
+     * Agent ID
+     */
+    id: string;
+    /**
+     * WebSocket endpoint URL
+     */
+    endpoint: string;
+    /**
+     * Authentication configuration (optional)
+     * Can be:
+     * - AuthenticationServiceConfig: Configuration object (e.g., { type: 'pre-auth', accessToken: '...' })
+     * - AuthProvider: Custom auth provider implementing getToken()
+     * - AuthStrategy: Full authentication strategy with lifecycle
+     * - undefined: Falls back to anonymous authentication
+     */
+    auth?: AuthenticationInput;
+    /**
+     * Automatically connect after initialize() completes
+     * @default false
+     */
+    autoConnect?: boolean;
+    /**
+     * Maximum queue size
+     * @default 1000
+     */
+    maxQueueSize?: number;
+    /**
+     * Maximum reconnection attempts
+     * @default Infinity
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Base reconnection delay in milliseconds
+     * @default 1000
+     */
+    baseReconnectDelay?: number;
+    /**
+     * Maximum reconnection delay in milliseconds
+     * @default 30000
+     */
+    maxReconnectDelay?: number;
+    /**
+     * Logger instance (optional)
+     * If not provided, a new logger instance will be created
+     * @default undefined (creates new instance)
+     */
+    logger?: Logger;
+    /**
+     * Logging level for the agent
+     * @default INFO
+     */
+    logLevel?: LogLevel;
+    /**
+     * Enable console output for logs
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Transcript configuration (optional)
+     * Controls whether and how messages are stored in the transcript
+     */
+    transcriptConfig?: TranscriptConfig;
+    /**
+     * Cache configuration for API calls (optional)
+     * Controls caching of agent details, portal details, and other API responses
+     * @default { enabled: true, storageType: 'session', ttl: 300000 }
+     */
+    cache?: CacheConfig;
+    /**
+     * Custom OAuth scopes to request during authentication (optional)
+     * If not provided, default scopes will be used:
+     * - ["knowledge.portalmgr.manage", "core.aiservices.read"] for agents
+     * - ["knowledge.portalmgr.manage", "core.aiservices.read", "core.customermgr.read"] for customers
+     *
+     * You can provide additional scopes to extend the default ones, or replace them entirely.
+     * @example
+     * ```typescript
+     * // Add additional scopes
+     * scopes: ["knowledge.portalmgr.manage", "core.aiservices.read", "custom.scope"]
+     * ```
+     */
+    scopes?: string[];
+    /**
+     * Pre-provided session ID (optional)
+     * If provided, the SDK will skip fetching sessionId from the network during initialization.
+     * Useful when you already have a session ID from a previous session or external source.
+     *
+     * @default undefined (fetches from network)
+     *
+     * @example
+     * ```typescript
+     * // Use existing sessionId (skips network fetch)
+     * const agent = new AiAgent({
+     *   id: "agent-id",
+     *   endpoint: "https://api.egain.com",
+     *   sessionId: "existing-session-id"
+     * });
+     * ```
+     */
+    sessionId?: string | number;
+    /**
+     * Initialization parameters forwarded from the host application.
+     * SDK consumers pass them explicitly so the SDK remains URL-agnostic.
+     *
+     * The SDK uses specific well-known keys internally:
+     * - `agentid` — when set and Flow A (`isDefaultAgent` is not `"true"`), portals are intersected with `agentDetails.portals` (cc-widget parity)
+     * - `departmentId` — optional fallback in Flow B when `agentDetails.departmentId` is missing; prefer agent details from the default agent API (cc-widget parity)
+     * - `portalIds` — comma-separated portal IDs; when set, skips `getMyPortals` and uses minimal portal objects
+     * - `templateName` — alias for theme short URL template sent as `shortUrlTemplate` to portalmgr APIs
+     * - `authType` — signals the authentication mode ("user" | "customer")
+     * - `scopes` — comma-separated OAuth scopes to request; when non-empty after parsing, **overrides** `config.scopes` and default scopes for PKCE / token acquisition
+     * - `userid` — user identifier for portal cache keying
+     * - `isDefaultAgent` — when "true", enables Flow B (agent selection mode)
+     *
+     * All other keys are stored and accessible via `agent.getInitParams()`
+     * for use by the consuming application.
+     *
+     * @example
+     * ```typescript
+     * initParams: {
+     *   agentid: "agent-123",
+     *   userid: "user-456",
+     *   authType: "user",
+     *   isDefaultAgent: "true",
+     *   scopes: "knowledge.portalmgr.manage,core.aiservices.read"
+     * }
+     * ```
+     */
+    initParams?: Record<string, string>;
+    /**
+     * Override URL for the platform connector script.
+     * When provided, the SDK loads this URL instead of constructing one
+     * from the platform name and deployment environment.
+     * Useful for local development or custom connector deployments.
+     */
+    platformScriptUrl?: string;
+    /**
+     * Authentication scheme for the PKCE flow.
+     * - 'popup': Opens a popup window for login (default)
+     * - 'redirect': Redirects the current page to the identity provider
+     *
+     * Only applies when the SDK auto-builds PKCE config from deployment info.
+     * Ignored when a full PKCEAuthConfig is supplied via `config.auth`.
+     * @default 'popup'
+     */
+    authScheme?: 'popup' | 'redirect';
+}
+/**
+ * Agent event type identifiers
+ */
+export type AgentEventType = 'connected' | 'message' | 'agentMessage' | 'errorMessage' | 'error' | 'closed' | 'stateChanged' | 'queueFlushed' | 'heartbeat' | 'tokenExpiring' | 'transcriptUpdate' | 'callTranscriptUpdate' | 'callerInfoUpdate' | 'conversationIdUpdate' | 'userContextUpdate' | 'filterTagsUpdate' | 'initialized' | 'portalsAvailable' | 'agentsAvailable' | 'profilesAvailable';
+/**
+ * Payload map for agent events
+ */
+export interface AgentEventPayloadMap {
+    connected: Record<string, never>;
+    message: {
+        data: any;
+    };
+    agentMessage: Omit<MessageHandlerResult, 'timestamp' | 'sessionId' | 'agentId'>;
+    errorMessage: {
+        message: Message;
+        error: Error;
+    };
+    error: {
+        error: Error;
+    };
+    closed: {
+        code?: number;
+        reason?: string;
+    };
+    stateChanged: {
+        state: ConnectionState;
+        previousState: ConnectionState;
+    };
+    queueFlushed: {
+        count: number;
+    };
+    heartbeat: Omit<MessageHandlerResult, 'timestamp' | 'sessionId' | 'agentId'>;
+    tokenExpiring: {
+        reason: 'expiring' | 'transport_request';
+        expiresAt?: number;
+    };
+    transcriptUpdate: {
+        entry: TranscriptEntry;
+    };
+    callTranscriptUpdate: {
+        entry: CallTranscriptEntry;
+    };
+    callerInfoUpdate: {
+        callerInfo: CallerInfo;
+    };
+    conversationIdUpdate: {
+        conversationId: string;
+    };
+    userContextUpdate: {
+        userContext: Record<string, unknown>;
+    };
+    filterTagsUpdate: {
+        filterTags: Record<string, string[]>;
+    };
+    /** Always includes at least agent (agentId, name). When CC pipeline completes: portal, portalDetails?, agent?, profile, availableProfiles, availablePortals. */
+    initialized: {
+        portal?: Portal;
+        portalDetails?: any;
+        agent?: AgentListItem | Record<string, unknown>;
+        profile?: UserProfile;
+        availableProfiles?: UserProfile[];
+        availablePortals?: Portal[];
+    };
+    portalsAvailable: {
+        portals: Portal[];
+    };
+    agentsAvailable: {
+        agents: AgentListItem[];
+    };
+    profilesAvailable: {
+        profiles: UserProfile[];
+        selectedPortal: Portal;
+    };
+}
+/**
+ * Wrapped agent event structure
+ */
+export interface AgentEvent<T extends AgentEventType = AgentEventType> {
+    /**
+     * Event type identifier
+     */
+    type: T;
+    /**
+     * Timestamp when the event occurred (milliseconds since epoch)
+     */
+    timestamp: number;
+    /**
+     * Session ID associated with the event
+     */
+    sessionId?: string | number;
+    /**
+     * Agent ID associated with the event
+     */
+    agentId?: string | number;
+    /**
+     * Event-specific payload data
+     * Type varies based on the event type
+     */
+    payload: AgentEventPayloadMap[T];
+}
+/**
+ * Agent event map
+ */
+export interface AgentEvents {
+    /**
+     * Emitted when connection is established
+     */
+    connected: AgentEvent<'connected'>;
+    /**
+     * Emitted when a message is received
+     */
+    message: AgentEvent<'message'>;
+    /**
+     * Emitted when an agent message is received
+     */
+    agentMessage: AgentEvent<'agentMessage'>;
+    /**
+     * Emitted when an error message is received
+     */
+    errorMessage: AgentEvent<'errorMessage'>;
+    /**
+     * Emitted when an error occurs
+     */
+    error: AgentEvent<'error'>;
+    /**
+     * Emitted when connection is closed
+     */
+    closed: AgentEvent<'closed'>;
+    /**
+     * Emitted when connection state changes
+     */
+    stateChanged: AgentEvent<'stateChanged'>;
+    /**
+     * Emitted when queue is flushed
+     */
+    queueFlushed: AgentEvent<'queueFlushed'>;
+    /**
+     * Emitted when a heartbeat message is received
+     * Indicates the agent is processing/typing - UI can show a loader
+     */
+    heartbeat: AgentEvent<'heartbeat'>;
+    /**
+     * Emitted when the access token is about to expire or needs refresh
+     * Triggered by JWT expiration detection (with 3-min buffer) or transport layer request
+     */
+    tokenExpiring: AgentEvent<'tokenExpiring'>;
+    /**
+     * Emitted when the transcript is updated (message sent or received)
+     * Contains the new transcript entry with message and direction
+     */
+    transcriptUpdate: AgentEvent<'transcriptUpdate'>;
+    /**
+     * Emitted when the platform connector pushes a call transcript entry
+     * via HookContract.addToTranscript(). Entries arrive incrementally during a call.
+     */
+    callTranscriptUpdate: AgentEvent<'callTranscriptUpdate'>;
+    /**
+     * Emitted when the platform connector sets caller information
+     * via HookContract.setCallerInfo().
+     */
+    callerInfoUpdate: AgentEvent<'callerInfoUpdate'>;
+    /**
+     * Emitted when the platform connector sets the conversation/interaction ID
+     * via HookContract.setConversationId().
+     */
+    conversationIdUpdate: AgentEvent<'conversationIdUpdate'>;
+    /**
+     * Emitted when the platform connector appends to user context
+     * via HookContract.setUserContext(). Payload contains the merged context.
+     */
+    userContextUpdate: AgentEvent<'userContextUpdate'>;
+    /**
+     * Emitted when the platform connector sets filter tags
+     * via HookContract.setUserFilterTags().
+     */
+    filterTagsUpdate: AgentEvent<'filterTagsUpdate'>;
+    /**
+     * Emitted when the pipeline (or direct flow) is fully complete.
+     * Safe to call connect(). Consumer is responsible for calling connect() after this.
+     * Payload is never empty in practice: always at least agent (agentId, name). When the CC pipeline
+     * completed, also includes portal, optional portalDetails, optional agent, profile, availableProfiles, availablePortals.
+     */
+    initialized: AgentEvent<'initialized'>;
+    /**
+     * Emitted when multiple portals are available.
+     * Consumer must call selectPortal(portal) to continue.
+     */
+    portalsAvailable: AgentEvent<'portalsAvailable'>;
+    /**
+     * Emitted when multiple agents are available (Flow B only).
+     * Consumer must call selectAgent(agent) to continue.
+     */
+    agentsAvailable: AgentEvent<'agentsAvailable'>;
+    /**
+     * Emitted when multiple user profiles exist and neither last-used nor default profile is found.
+     * Payload includes profiles and selectedPortal. Consumer must call selectUserProfile(profile) to continue.
+     */
+    profilesAvailable: AgentEvent<'profilesAvailable'>;
+}
+/**
+ * Main class for interacting with the eGain AI Agent platform.
+ *
+ * The AiAgent class provides:
+ * - WebSocket connection management with automatic reconnection
+ * - Message queuing when offline
+ * - Event-driven communication
+ * - Transcript management
+ * - Context persistence
+ *
+ * **Initialization flows**
+ *
+ * After authentication, one of two paths runs:
+ *
+ * - **Direct flow** (non–contact-center agents): fetches session, creates the WebSocket connection,
+ *   emits `initialized`. With {@link AiAgentConfig.autoConnect}, `connect()` runs automatically.
+ * - **Contact Center (CC) flow** (contact-center agents, per API `agentType` / authenticated agents
+ *   with legacy empty type): runs a REST-only portal → (optional agent) → profile pipeline, then
+ *   emits `initialized`. The WebSocket is created when you call `connect()` (or automatically if
+ *   `autoConnect` is true after the pipeline completes).
+ *
+ * **Flow A (specific agent)** — Use the target agent ID in {@link AiAgentConfig.id}. CC pipeline:
+ * portal selection → profile selection.
+ *
+ * **Flow B (default agent / agent selection)** — Set `initParams: { isDefaultAgent: "true" }`.
+ * CC pipeline: portal → agent → profile. The selected agent becomes the chat identity
+ * (`resolvedAgentId`); subsequent session and chat use that ID, not the bootstrap `config.id`.
+ *
+ * When the CC pipeline has multiple options at a step, it emits `portalsAvailable`,
+ * `agentsAvailable`, or `profilesAvailable`. Call {@link AiAgent.selectPortal},
+ * {@link AiAgent.selectAgent}, or {@link AiAgent.selectUserProfile} to continue. After the
+ * `initialized` event, call {@link AiAgent.connect} unless `autoConnect` already connected you.
+ *
+ * @example Direct flow (typical non–Contact Center agent)
+ * ```typescript
+ * import { AiAgent } from "@eGain/ai-agent-sdk";
+ *
+ * const agent = new AiAgent({
+ *   id: "agent-id",
+ *   endpoint: "https://api.egain.com",
+ *   auth: { type: "pre-auth", accessToken: "your-access-token" },
+ *   autoConnect: true,
+ * });
+ *
+ * agent.on("agentMessage", (event) => {
+ *   console.log("Agent:", event.payload.message?.content);
+ * });
+ *
+ * await agent.initialize();
+ * await agent.send("Hello!");
+ * ```
+ *
+ * @example Contact Center flow (register handlers before `initialize`)
+ * ```typescript
+ * const agent = new AiAgent({
+ *   id: "agent-id",
+ *   endpoint: "https://api.egain.com",
+ *   auth: { type: "pkce", config: { ... } },
+ *   initParams: { userid: "user-123" },
+ * });
+ *
+ * agent.on("portalsAvailable", (e) => agent.selectPortal(e.payload.portals[0]));
+ * agent.on("agentsAvailable", (e) => agent.selectAgent(e.payload.agents[0]));
+ * agent.on("profilesAvailable", (e) => agent.selectUserProfile(e.payload.profiles[0]));
+ * agent.on("initialized", async () => {
+ *   await agent.connect();
+ * });
+ * await agent.initialize();
+ * ```
+ *
+ * @example With context
+ * ```typescript
+ * import { AiAgent, createContextMessage } from "@eGain/ai-agent-sdk";
+ *
+ * await agent.send(createContextMessage({
+ *   context: { userId: "123", accountType: "premium" },
+ * }));
+ * ```
+ *
+ * @category Core
+ * @see {@link AiAgentConfig} for configuration options
+ * @see {@link AgentEvents} for available events
+ */
+export declare class AiAgent extends EventEmitter<AgentEvents> {
+    private connection?;
+    private messageQueue;
+    private messageProcessor;
+    private authService;
+    private config;
+    private isInitialized;
+    private isFlushingQueue;
+    private deploymentInfo;
+    private apiHelper?;
+    private agentDetails?;
+    private sessionId?;
+    private transcript;
+    private contextCacheAdapter;
+    logger: Logger;
+    private resolvedAgentId;
+    private portalInitializer?;
+    private isAgentSelectionMode;
+    private initParams;
+    /** Cached profiles for restart (user-associated; portal details and agents are not cached). */
+    private cachedProfiles?;
+    /** True when the agent completed the portal initialization pipeline (needed for restart guard). */
+    private completedPortalPipeline;
+    /** Last selected portal from pipeline (needed for updateUserProfile). */
+    private lastSelectedPortal?;
+    private callerInfo;
+    private userContext;
+    private platformToken;
+    private isPlatformAuthenticated;
+    private conversationId;
+    private filterTags;
+    private callTranscript;
+    private hookContract?;
+    private platformComponentService?;
+    private userDetails;
+    /** True after `addCustomAuthScopes` merged scopes into `config.scopes` (PKCE/hooks must use that list). */
+    private authScopesAugmentedByPlatform;
+    constructor(config: AiAgentConfig);
+    /**
+     * Setup TokenRefreshHandler with callbacks for automatic token refresh
+     * Replaces the default handler with one that can actually perform token refresh
+     */
+    private setupTokenRefreshHandler;
+    private parseQueryScopes;
+    /**
+     * Base OAuth resource scopes before platform augmentation: comma-separated `initParams.scopes`
+     * overrides `config.scopes` and defaults. Used to seed `addCustomAuthScopes`. For PKCE and hooks
+     * after the platform merges scopes, use {@link getAuthScopesForFlow}.
+     */
+    private resolveEffectiveAuthScopes;
+    /**
+     * Scopes used for PKCE, AuthenticationService.initialize, and HookContract.getAuthScopes.
+     * After the platform connector augments scopes into `config.scopes`, that merged list wins.
+     */
+    private getAuthScopesForFlow;
+    /**
+     * Initialize the agent. Must be called after construction and awaited before use.
+     *
+     * Authenticates (falls back to {@link AnonymousAuthStrategy} if no auth is configured), then:
+     *
+     * - **Direct flow:** fetches session, creates the WebSocket connection, emits `initialized`.
+     *   With `autoConnect`, opens the WebSocket automatically.
+     * - **Contact Center flow:** runs portal / agent / profile selection over REST only (no WebSocket
+     *   yet). May emit `portalsAvailable`, `agentsAvailable`, or `profilesAvailable` — call the
+     *   corresponding `select*` method. Then emits `initialized`. Call {@link AiAgent.connect}
+     *   afterward (or rely on `autoConnect` after the pipeline completes).
+     *
+     * @example
+     * ```typescript
+     * const agent = new AiAgent({ id: 'agent-id', endpoint: 'https://...' });
+     * await agent.initialize();
+     * // Direct flow: often already connected if autoConnect. CC flow: connect after `initialized`.
+     * await agent.connect();
+     * ```
+     */
+    initialize(): Promise<void>;
+    /**
+     * Build the HookContract by closing over `this`.
+     * All getters return live state (not stale snapshots).
+     */
+    private buildHookContract;
+    /**
+     * Load the platform connector script and wire up the HookContract.
+     * Called from initialize() when a non-standalone platform is detected.
+     */
+    private loadAndInitializePlatform;
+    /**
+     * Whether to run the portal-based initializer (portals → optional agents → profiles) vs direct session setup.
+     * True when portal-related init params or agent configuration indicate a portal-trained / contact-center flow.
+     */
+    private shouldRunPortalInitializationPipeline;
+    /**
+     * Session + connection + `initialized` for the non-portal path after auth.
+     */
+    private runDirectInitializationAfterAuth;
+    private runPortalInitializerPipeline;
+    /**
+     * Post-authentication callback. Runs the portal initializer when
+     * {@link shouldRunPortalInitializationPipeline} is true; otherwise session + connection (direct flow).
+     * @param accessToken - The access token to use for authentication
+     */
+    private readonly onAuthComplete;
+    /**
+     * Fetch user or customer details after authentication.
+     * Determination: if userType is 'customer', fetches customer details; otherwise fetches user details.
+     * Best-effort — logs a warning on failure but does not throw.
+     */
+    private fetchUserOrCustomerDetails;
+    /**
+     * Fetch agent details from API
+     * @param accessToken - The access token to use for authentication
+     * @returns The agent details
+     */
+    private fetchAgentDetails;
+    /**
+     * Ensures agent details have agentId from the request context when API omits it.
+     *
+     * @param details - The agent details to backfill the agentId for
+     * @returns The agent details with the agentId backfilled
+     */
+    private backfillAgentDetailsId;
+    /**
+     * Get the agent details
+     * Returns cached agent details if available, otherwise fetches from network.
+     * If called before initialize(), performs minimal initialization to fetch agent details only
+     * (gets deployment info, fetches anonymous token, fetches agent details - without getting session ID or creating connection).
+     * @returns Promise resolving to the agent details
+     */
+    getAgentDetails(): Promise<any>;
+    /**
+     * Get the deployment information
+     * Returns cached deployment info if available, otherwise fetches from network.
+     * Does not require initialization - only needs the endpoint URL.
+     * @returns Promise resolving to the deployment information
+     */
+    getDeploymentInfo(): Promise<any>;
+    /**
+     * Get the agent name from cached agent details
+     * @returns The agent name
+     */
+    private getAgentName;
+    /**
+     * Get session ID
+     * @param accessToken - The access token to use for authentication
+     * @returns The session ID
+     */
+    private getSessionId;
+    /**
+     * Get WebSocket endpoint
+     * @param sessionId - The session ID
+     * @returns The WebSocket endpoint
+     */
+    private getWsEndpoint;
+    /**
+     * Create the connection after authentication is complete
+     * This is called by the postAuthentication callback
+     */
+    private createConnection;
+    /**
+     * Whether the agent has completed initialization.
+     * Becomes `true` after the init pipeline completes (e.g. after the `initialized` event).
+     *
+     * @returns `true` if initialized, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * if (agent.getIsInitialized()) {
+     *   await agent.connect();
+     * } else {
+     *   agent.once('initialized', () => agent.connect());
+     * }
+     * ```
+     */
+    getIsInitialized(): boolean;
+    /**
+     * Get current connection state.
+     *
+     * @returns The current connection state
+     * @throws Error if agent is not initialized
+     *
+     * @example
+     * ```typescript
+     * const state = agent.getState();
+     * if (state === ConnectionState.CONNECTED) {
+     *   console.log("Ready to send messages");
+     * }
+     * ```
+     *
+     * @see {@link ConnectionState} for available states
+     */
+    getState(): ConnectionState;
+    /**
+     * Check if the agent is currently connected.
+     *
+     * @returns `true` if connected, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * if (agent.isConnected()) {
+     *   await agent.send("Hello!");
+     * } else {
+     *   console.log("Waiting for connection...");
+     * }
+     * ```
+     */
+    isConnected(): boolean;
+    /**
+     * Connect to the agent endpoint.
+     *
+     * Establishes a WebSocket connection to the AI Agent server. Must call {@link initialize} first.
+     *
+     * For Contact Center agents, the connection object is created lazily on this call (session fetch
+     * uses the resolved agent ID, including Flow B after agent selection).
+     *
+     * @throws Error if agent is not initialized
+     *
+     * @example
+     * ```typescript
+     * await agent.initialize();
+     * await agent.connect();
+     * console.log("Connected!");
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the agent endpoint.
+     *
+     * By default, sends a graceful disconnect message before closing the connection.
+     * Use `skipGracefulDisconnect: true` for immediate disconnection.
+     *
+     * @param options - Disconnect options
+     * @param options.skipGracefulDisconnect - If true, skip sending graceful disconnect message
+     *
+     * @example Graceful disconnect
+     * ```typescript
+     * await agent.disconnect();
+     * ```
+     *
+     * @example Immediate disconnect
+     * ```typescript
+     * await agent.disconnect({ skipGracefulDisconnect: true });
+     * ```
+     */
+    disconnect(options?: {
+        skipGracefulDisconnect?: boolean;
+    }): Promise<void>;
+    /**
+     * Select a portal (CC flow). Call when portalsAvailable event is emitted and user has chosen.
+     *
+     * @param portal - The selected portal
+     * @throws Error if portal initializer is not active
+     *
+     * @example
+     * ```typescript
+     * agent.on('portalsAvailable', (e) => {
+     *   const portal = showPortalPicker(e.payload.portals);
+     *   agent.selectPortal(portal);
+     * });
+     * ```
+     */
+    selectPortal(portal: Portal): void;
+    /**
+     * Select an agent (Flow B only — `initParams.isDefaultAgent === "true"`).
+     * Call when `agentsAvailable` is emitted and the user has chosen.
+     *
+     * @param agent - The selected agent
+     * @throws Error if portal initializer is not active
+     *
+     * @example
+     * ```typescript
+     * agent.on('agentsAvailable', (e) => {
+     *   const selected = showAgentPicker(e.payload.agents);
+     *   agent.selectAgent(selected);
+     * });
+     * ```
+     */
+    selectAgent(agent: AgentListItem): void;
+    /**
+     * Select a user profile (CC flow). Call when profilesAvailable event is emitted and user has chosen.
+     *
+     * @param profile - The selected profile
+     * @throws Error if portal initializer is not active
+     *
+     * @example
+     * ```typescript
+     * agent.on('profilesAvailable', (e) => {
+     *   const profile = showProfilePicker(e.payload.profiles);
+     *   agent.selectUserProfile(profile);
+     * });
+     * ```
+     */
+    selectUserProfile(profile: UserProfile): void;
+    /**
+     * Get the stored initialization parameters from config.
+     *
+     * @returns The init params object (empty object if none provided)
+     *
+     * @example
+     * ```typescript
+     * const initParams = agent.getInitParams();
+     * const userId = initParams.userid;
+     * ```
+     */
+    getInitParams(): Record<string, string>;
+    /**
+     * Restart the CC widget initialization pipeline from scratch.
+     *
+     * This method tears down the current initialization state and re-runs the
+     * full pipeline (portal selection → agent selection → profile selection),
+     * allowing the consumer to make new selections. After completion, the
+     * `initialized` event fires again and the consumer should call `connect()`.
+     *
+     * **What it does:**
+     * 1. Checks `completedPortalPipeline`: if false (non-CC agent), delegates to `restartConnection()` and returns
+     * 2. Destroys the current `PortalInitializer` instance (rejects any pending gating promises)
+     * 3. Disconnects the current WebSocket connection (if any) and clears session, queue, transcript
+     * 4. Resets `resolvedAgentId` to `config.id` and `isInitialized` to false
+     * 5. Re-obtains an auth token and calls `onAuthComplete` to restart the pipeline (or direct flow)
+     *
+     * **Important:** For agents that completed the CC initialization pipeline
+     * (portal → agent → profile selection), this re-runs the full pipeline.
+     * For agents that did not complete it (e.g. direct flow from the start, or
+     * contact-center agents that fell back to direct flow because they have no
+     * portals), this method delegates to `restartConnection()` so the consumer
+     * can call it for any restart without branching. The consumer must
+     * re-register or still have active event listeners for `portalsAvailable`,
+     * `agentsAvailable`, `profilesAvailable`, and `initialized` before calling
+     * this method (CC pipeline path only).
+     *
+     * @throws Error if authentication token cannot be obtained (CC path) or for restart (direct path)
+     *
+     * @example
+     * ```typescript
+     * // User wants to switch portals — restart the pipeline
+     * agent.on('portalsAvailable', (e) => {
+     *   showPortalPicker(e.payload.portals, (p) => agent.selectPortal(p));
+     * });
+     *
+     * agent.on('initialized', async () => {
+     *   await agent.connect();
+     * });
+     *
+     * await agent.restartPortalInitializer();
+     * ```
+     */
+    restartPortalInitializer(): Promise<void>;
+    /**
+     * @deprecated Use {@link restartPortalInitializer} instead.
+     */
+    restartCcWidgetInitializer(): Promise<void>;
+    /**
+     * Update the active user profile after initialization.
+     *
+     * Use this when the consumer wants to switch profiles without re-running the
+     * full portal/agent selection pipeline. This method:
+     * 1. Persists the new profile selection via the `selectUserProfile` API
+     *    (if the profile is not already the last-used profile)
+     * 2. Disconnects the current WebSocket connection (if any)
+     * 3. Clears the message queue and transcript
+     * 4. Fetches a new session ID and reconnects
+     * 5. Emits `initialized` with the updated profile in the payload
+     *
+     * This is the equivalent of the cc-widget's profile dropdown behavior:
+     * change the profile → restart session → re-send user context.
+     *
+     * **Important:** This method is only valid after the CC initialization
+     * pipeline has completed. Calling it on a non-CC agent or before
+     * initialization throws an error.
+     *
+     * @param profile - The new user profile to activate
+     * @throws Error if agent is not initialized
+     * @throws Error if agent did not go through the CC initialization flow
+     * @throws Error if no portal is currently selected
+     *
+     * @example
+     * ```typescript
+     * // User picks a different profile from a dropdown
+     * const profiles = cachedProfiles; // from the profilesAvailable event
+     * agent.on("initialized", async () => {
+     *   await agent.connect();
+     * });
+     * await agent.updateUserProfile(profiles[2]);
+     * ```
+     */
+    updateUserProfile(profile: UserProfile): Promise<void>;
+    /**
+     * Restart the connection with a fresh session.
+     *
+     * This method:
+     * 1. Gracefully disconnects from the current session
+     * 2. Clears all queued messages and transcript
+     * 3. Obtains a new session ID (or uses provided one)
+     * 4. Reconnects to the new session
+     * 5. Sends any stored context to the new session
+     *
+     * **Note:** All queued messages will be lost during restart.
+     *
+     * @param options - Optional restart options
+     * @param options.sessionId - Optional session ID to use for restart. If provided, skips fetching from network.
+     * @throws Error if agent is not initialized
+     *
+     * @example
+     * ```typescript
+     * // Start a fresh conversation (fetches new sessionId)
+     * await agent.restartConnection();
+     *
+     * // Restart with a specific sessionId
+     * await agent.restartConnection({ sessionId: 'existing-session-id' });
+     *
+     * // Context is automatically restored
+     * await agent.send("Hello again!");
+     * ```
+     */
+    restartConnection(options?: {
+        sessionId?: string | number;
+    }): Promise<void>;
+    /**
+     * Normalize input data to a Message instance
+     * @private
+     */
+    private normalizeToMessage;
+    /**
+     * Send a message to the agent
+     * Messages are queued if offline and automatically sent when connected
+     * Context messages are automatically stored in cache for use on reconnection
+     * @param data - Message data (can be a Message instance, plain object, or string)
+     * @param options - Optional message options
+     * @param options.id - Optional message ID
+     * @param options.from - Optional sender identifier (agent ID, customer ID, etc.)
+     * @param options.to - Optional recipient identifier (agent ID, etc.)
+     * @returns Message ID
+     */
+    send(data: any, options?: {
+        id?: string;
+        from?: string;
+        to?: string;
+    }): Promise<string>;
+    /**
+     * Get the current queue size
+     */
+    getQueueSize(): number;
+    /**
+     * Clear the message queue
+     */
+    clearQueue(): void;
+    /**
+     * Get transcript entries
+     * @param options - Optional filtering options
+     * @returns Array of transcript entries with Message objects
+     */
+    getTranscript(options?: TranscriptOptions): TranscriptEntry[];
+    /**
+     * Get transcript entries as plain objects (JSON-serializable)
+     * @param options - Optional filtering options
+     * @returns Array of plain objects representing transcript entries
+     */
+    getTranscriptAsJSON(options?: TranscriptOptions): any[];
+    /**
+     * Get the number of entries in the transcript
+     * @returns Number of transcript entries
+     */
+    getTranscriptSize(): number;
+    /**
+     * Clear all transcript entries
+     */
+    clearTranscript(): void;
+    /**
+     * Get the call transcript — the live customer-agent conversation from the
+     * telephony platform (Genesys, Amazon Connect, etc.), pushed by the platform
+     * connector via the HookContract.
+     *
+     * This is distinct from {@link getTranscript}, which returns the AI Agent
+     * chat transcript (WebSocket messages).
+     *
+     * @returns A shallow copy of the call transcript entries
+     */
+    getCallTranscript(): CallTranscriptEntry[];
+    /**
+     * Get the caller information set by the platform connector via
+     * HookContract.setCallerInfo(). Available after the platform connector
+     * has initialized (typically before the `initialized` event fires).
+     *
+     * @returns The caller info object, or null if not yet set
+     */
+    getCallerInfo(): CallerInfo | null;
+    /**
+     * Returns the authenticated user's or customer's details fetched after authentication.
+     * Available after the `initialized` event fires. Returns null if details could not be fetched.
+     */
+    getUserDetails(): UserDetails | null;
+    getConversationId(): string | null;
+    /**
+     * Clear all call transcript entries.
+     */
+    clearCallTranscript(): void;
+    /**
+     * Get the context cache key for this agent
+     * @returns The cache key for storing context
+     */
+    private getContextCacheKey;
+    /**
+     * Cache key for persisted profile list (pipeline restart).
+     * Includes portalId so switching portals doesn't serve stale profiles.
+     */
+    private getPipelineProfilesCacheKey;
+    /**
+     * Check if a message is a context message
+     * @param data - The message data to check
+     * @returns True if this is a context message
+     */
+    private isContextMessage;
+    /**
+     * Extract context data from a context message
+     * @param data - The message data to extract context from
+     * @returns The context object or null if not a context message
+     */
+    private extractContextFromMessage;
+    /**
+     * Store context in cache
+     * @param context - The context object to store
+     */
+    private storeContext;
+    /**
+     * Get the stored context for this agent
+     * Returns the context object that was previously sent via a context message
+     * @returns The stored context object or null if no context is stored
+     */
+    getContext(): object | null;
+    /**
+     * Remove the stored context for this agent
+     * Clears any previously stored context from the cache
+     */
+    removeContext(): void;
+    /**
+     * Set context for this agent
+     * Stores the context in cache and optionally sends it to the agent immediately
+     * @param context - The context object to set
+     * @param options - Optional settings
+     * @param options.sendImmediately - If true, sends the context to the agent right away (default: false)
+     * @returns Promise that resolves when context is set (and sent if sendImmediately is true)
+     *
+     * @example Set context without sending
+     * ```typescript
+     * agent.setContext({ userId: "123", plan: "premium" });
+     * ```
+     *
+     * @example Set and send context immediately
+     * ```typescript
+     * await agent.setContext({ userId: "123", plan: "premium" }, { sendImmediately: true });
+     * ```
+     */
+    setContext(context: object, options?: {
+        sendImmediately?: boolean;
+    }): Promise<void>;
+    /**
+     * Reset (clear) the context for this agent
+     * Removes any stored context from the cache
+     * This is an alias for removeContext() with additional logging
+     *
+     * @example
+     * ```typescript
+     * agent.resetContext();
+     * ```
+     */
+    resetContext(): void;
+    /**
+     * Send stored context to the agent
+     * This is called internally after reconnection to restore context
+     * @returns Promise that resolves when context is sent (or immediately if no context)
+     */
+    private sendStoredContext;
+    /**
+     * Setup connection event forwarding
+     */
+    private setupConnectionEvents;
+    /**
+     * Send authentication token to agent if authentication is required
+     * This is called immediately after connection is established
+     */
+    private sendAuthTokenIfRequired;
+    /**
+     * Queue a message for later sending
+     */
+    private queueMessage;
+    /**
+     * Flush queued messages when connected
+     */
+    private flushQueue;
+    /**
+     * Create an AgentEvent object with automatic timestamp, sessionId, and agentId
+     * @param type - The event type
+     * @param payload - The event-specific payload data
+     * @param options - Optional overrides for timestamp, sessionId, or agentId
+     * @returns A properly formatted AgentEvent object
+     */
+    private createAgentEventResponse;
+    /**
+     * Generate a unique message ID
+     */
+    private generateMessageId;
+    /**
+     * Delay utility
+     */
+    private delay;
+    /**
+     * Get the message processor instance
+     * Allows adding custom handlers
+     */
+    getMessageProcessor(): MessageProcessor;
+    /**
+     * Get the current access token from the authentication strategy
+     * Returns the access token that the agent is currently using for authentication
+     * @returns Promise resolving to the access token string, or null if no token is available
+     *
+     * @example
+     * ```typescript
+     * const token = await agent.getAccessToken();
+     * if (token) {
+     *   // Use the token for external API calls
+     *   fetch('https://api.example.com/data', {
+     *     headers: { Authorization: `Bearer ${token}` }
+     *   });
+     * }
+     * ```
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Update the access token at runtime
+     * Use this method when you receive a tokenExpiring event to provide a new token
+     * @param token - The new access token
+     * @throws Error if the authentication strategy doesn't support token updates
+     *
+     * @example
+     * ```typescript
+     * agent.on('tokenExpiring', async (event) => {
+     *   const newToken = await fetchNewTokenFromServer();
+     *   await agent.updateAccessToken(newToken);
+     * });
+     * ```
+     */
+    updateAccessToken(token: string): Promise<void>;
+    /**
+     * Set or update the session ID at runtime
+     * Updates the sessionId property, which will be used for future connections and logging.
+     *
+     * **Note:** If the agent is currently connected, changing the sessionId will not automatically
+     * switch the connection to the new session. You should either:
+     * - Disconnect and reconnect with the new sessionId
+     * - Use `restartConnection({ sessionId: newSessionId })` to restart with the new session
+     *
+     * @param sessionId - The new session ID to set
+     *
+     * @example
+     * ```typescript
+     * // Update sessionId after initialization
+     * agent.setSessionId('new-session-id');
+     *
+     * // If connected, restart with the new sessionId
+     * if (agent.isConnected()) {
+     *   await agent.restartConnection({ sessionId: 'new-session-id' });
+     * }
+     * ```
+     */
+    setSessionId(sessionId: string | number): void;
+}
+//# sourceMappingURL=AiAgent.d.ts.map