Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.2.3] - 2026-09-XX

Fixed

• PKCE popup authentication — PKCEAuthStrategy omits nextRoute and OAuth state when authScheme is popup, matching legacy cc-widget auth.ts behavior. Prevents auth-redirect.html from bouncing the MSAL popup to the app URL and triggering MSAL block_nested_popups during cc-widget bootstrap. Redirect flow is unchanged (state still carries the return URL).
• Auth token propagation — new finishAuthentication callback syncs the access token from the active auth strategy via AuthenticationService.getToken() before onAuthComplete, fixing cases where strategy callbacks supplied tokens that were not cached in AuthenticationService (e.g. anonymous → PKCE switch, anonymous agents, and restartPortalInitializer())

Changed

• HookContract.getMsalAccessToken() — returns only the cached token synchronously; removed fire-and-forget getToken() side effect (use getAccessToken() when a fresh token is required)

[0.2.2] - 2026-08-21

Added

• Session creation with context — ApiHelper.getAiAgentSession() uses POST .../session with an optional { context } body (falls back to GET on 403/404/405); AiAgent passes stored context when creating or restarting sessions, including egain_portal_id from the last selected portal when present
• contextValidation agent event — emitted when the platform returns a non-terminal system message for rejected context attributes (without ending the session)
• ContextValidationHandler and exported type ContextValidationIssue for custom message pipelines
• MessageData.escalationData — optional liveDomain and entrypointUrl on inbound escalation payloads (Advisor Desktop chat transfer)

Changed

• setContext() — merges into cached context; sendImmediately sends only attribute values that changed since the last stored context
• restartConnection() — new sessions receive context via the session POST; WebSocket sendStoredContext() runs only when the caller supplies an existing sessionId (compatibility path)
• cache.enabled: false — disables deployment-info static cache, portal pipeline profile cache (pipelineCache), and uses a memory-only context adapter (no session/local persistence)

Fixed

• pipelineCache and getDeploymentInfo now honor cache.enabled: false instead of still reading or writing cached deployment info and profile lists
• Customer getPortals failures — portal-trained self-service agents (userType: customer with configured portals) now reject initialize() with InitializationPipelineError (PORTAL_FETCH_FAILED) when the portalmgr API fails, matching the getMyPortals path so hosts can surface errors instead of staying in a loading state
• Session ID validation — getSessionId(), getWsEndpoint(), and ApiHelper.getAiAgentSession() reject placeholder or missing session ids (undefined, null, blank strings) before constructing the chat WebSocket URL; the query parameter is set via URLSearchParams instead of string interpolation

[0.2.1] - 2026-07-30

Fixed

• Profile auto-select on recovery — when multiple profiles are available, egain_personalization_profile_id in initialization context now wins over isLastUsedInPortal on the profile list
• Stale profile list caches — ApiHelper.selectUserProfile invalidates cached getUserProfiles responses after a successful PUT; AiAgent.updateUserProfile clears the portal pipeline profile cache (eg_profiles_*) and invalidates getUserProfiles so the next pipeline run refetches fresh isLastUsedInPortal flags

Documentation

• Portal initialization, context management, and caching guides: profile auto-select priority and profile-list cache invalidation on select / updateUserProfile

[0.2.0] - 2026-07-29

Added

• AiAgent.initialize(options?) — optional { context } merged with AiAgentConfig.context; stored via setContext for reconnect
• Portal/profile auto-select during PortalInitializer when initialization context includes egain_portal_id and/or egain_personalization_profile_id (eGain attribute { value } or plain string values)
• Exported type AiAgentInitializeOptions
• ApiHelper.getPortals() — customer self-service portal list (GET .../portalmgr/v3/portals) with Flow A intersection against agentDetails.portals (replaces synthetic-only customer portal lists)
• Data masking — when agentDetails.enableDataMasking is true and the deployment version supports it, loads chat masking patterns during init and masks outbound customer / human messages in send(); AiAgent.maskContent() for UI/escalation
• semver dependency for platform version gating (cc-widget parity)

Changed

• Customer agents with configured KB portals use tenant portal catalog + bot intersection (same rules as CC Flow A) instead of placeholder portal names only

Documentation

• Portal initialization and context management guides: initialization context and auto-select behavior
• Message flow guide: data masking (maskContent, outbound send() behavior)

[0.1.5] - 2026-07-27

Added

• InitializationPipelineError and InitializationPipelineErrorCode (AUTH_TOKEN_REQUIRED, NO_PORTALS, PORTAL_FETCH_FAILED, PORTAL_DETAILS_FAILED, PROFILE_FETCH_FAILED, PROFILE_PERSIST_FAILED, NO_AGENTS_FOR_PORTAL, DEPARTMENT_ID_REQUIRED, INVALID_SELECTION) — thrown when the CC portal pipeline fails; catch via instanceof InitializationPipelineError and branch on pipelineCode / error.code
• InitializationPipelineStage on thrown errors (stage property) plus optional portal / agent context

Fixed

• CC pipeline failures after start() or after selectPortal() / selectAgent() / selectUserProfile() were logged internally but not surfaced to consumers; hosts can await those calls and catch InitializationPipelineError instead of staying in a loading state

Changed

• selectPortal(), selectAgent(), and selectUserProfile() return Promise<void> and reject with InitializationPipelineError on pipeline failure
• AiAgent awaits portalInitializer.start() during CC init so auto-select failures reject initialize() when the pipeline fails before the first user gate
• getPortalDetails API failures throw PORTAL_DETAILS_FAILED instead of being swallowed

[0.1.4] - 2026-07-20

Added

• HookContract.getAccessToken() — async method that returns a fresh token, refreshing if expired. Connectors that need a guaranteed valid token for API calls should prefer this over the sync getMsalAccessToken()

Changed

• Platform connector script loads for any set initParams.platform when agentType is contact-center, including standalone and test (cc-widget parity). test resolves to the standalone connector URL
• HookContract.getMsalAccessToken() is synchronous and returns the cached auth token (AuthenticationService.getCachedToken()), matching cc-widget connectors that do not await
• HookContract.getUserId() returns the authenticated user/customer details id (from getUserDetails / getCustomerDetails), not initParams.userid

Fixed

• Skip fetching user/customer details when the agent is not authenticated (agentDetails.isAuthenticated is false), avoiding unnecessary getUserDetails / getCustomerDetails API calls

[0.1.3] - 2026-07-14

Added

• HookContract.getQueryParams() — legacy alias for getInitParams(), restoring compatibility with platform connectors (e.g. Genesys) that still call getQueryParams() after the queryParam → initParam rename

[0.1.2] - 2026-06-04

Documentation

• Added instructions for generating an access token (PKCE flow) as a prerequisite for the pre-auth authentication option, including required OAuth scopes (core.aiservices.read, knowledge.portalmgr.manage, core.customermgr.read)
• Updated README, Quick Start guide, and Authentication guide

[0.1.0] - 2026-04-30 & [0.1.1] - 2026-05-01

First beta release of the AI Agent SDK

[0.0.13] & [0.0.14] - 2026-04-XX

Changed

• README documentation links

[0.0.12] - 2026-04-XX

Added

• Contact center (CC) portal initialization flow: chained REST pipeline (portals → optional agents → user profiles) before WebSocket connect, aligned with cc-widget behavior
• Platform script loading for CC connectors (e.g. Genesys, Amazon Connect): loads connector script and wires PlatformComponentService / HookContract
• New AiAgent methods: selectPortal(), selectAgent(), selectUserProfile(), getInitParams(), getIsInitialized(), restartPortalInitializer(), updateUserProfile(), getUserDetails(), getCallTranscript(), getCallerInfo(), getConversationId(), clearCallTranscript()
• New ApiHelper methods: getMyPortals(), getAgentsByPortal(), getUserProfiles(), selectUserProfile(), getUserDetails(), getCustomerDetails()
• getToken callback on ApiHelperConfig so API calls can omit per-method authToken when a token provider is configured
• New AiAgentConfig options: initParams, scopes, platformScriptUrl, authScheme (popup | redirect for auto-built PKCE)
• New events: initialized (expanded payload), portalsAvailable, agentsAvailable, profilesAvailable, callTranscriptUpdate, callerInfoUpdate, conversationIdUpdate, userContextUpdate, filterTagsUpdate
• Exported types for CC and connectors: Portal, UserProfile, AgentListItem, UserDetails, HookContract, CallerInfo, CallTranscriptEntry, PlatformComponentService, and new Get* / Select* API option types

Changed

• PKCE: localLogin on PKCEAuthConfig, improved redirect/popup behavior, domain_hint / localLogin extra query parameters, and MSAL options aligned with CC flows
• Several ApiHelper option types now allow optional authToken when getToken is set on ApiHelperConfig

Deprecated

• restartCcWidgetInitializer() — use restartPortalInitializer() instead

[0.0.11] - 2025-01-XX

Added

• Browser UMD build support with ./browser export
• Browser build script (build:browser) for standalone browser bundle
• MSAL copy script for browser compatibility
• Comprehensive build pipeline with build:all command
• Documentation generation scripts (docs:api, docs:build, docs:dev)
• Publishing scripts for GitHub Packages

Changed

• Updated build process to include browser bundle generation
• Enhanced package exports to support both Node.js and browser environments
• Improved build scripts organization

[0.0.10] - 2025-01-XX

Added

• Browser build configuration
• Rollup bundler integration for browser builds
• Browser-specific exports in package.json

Changed

• Build process now generates both Node.js and browser bundles

[0.0.9] - 2025-01-09

Added

• transcriptUpdate event - emitted whenever the transcript is updated (message sent or received)
  • Provides TranscriptEntry with message, direction, timestamp, sessionId, and agentId
  • Useful for tracking all message activity in real-time
• GitHub Actions workflow for automated SDK documentation deployment

Changed

• Improved VitePress documentation site structure
• Moved docs folder for better organization

[0.0.8] - 2025-01-08

Changed

• Removed empty content attribute from message payload
• Added 5ms delay in queue flushing for improved reliability
• Cached anonymous token for better performance
• Added partial initialization when agent details are fetched before init

Fixed

• Fixed test browser UMD build

[0.0.7] - 2025-01-08

Added

• VitePress documentation site
• Enhanced JSDoc comments throughout the codebase
• TypeDoc configuration for API reference generation
• Context persistence with automatic restoration on reconnect
• Custom cache adapter support
• tokenExpiring event for proactive token refresh
• updateAccessToken() method for runtime token updates

Changed

• Improved error messages for better debugging
• Enhanced TypeScript type definitions
• Updated documentation to use pre-auth instead of deprecated token auth type

Fixed

• Various bug fixes and stability improvements

[0.0.6] - 2025-01-06

Added

• restartConnection() method for fresh sessions
• Automatic context caching and restoration
• getContext() and removeContext() methods
• Transcript filtering options

Changed

• Improved reconnection logic with exponential backoff

[0.0.5] - 2025-01-03

Added

• ApiHelper class for REST API interactions
• Caching for API responses
• getAgentDetails() and getDeploymentInfo() methods

Changed

• Refactored authentication to use AuthenticationService

[0.0.4] - 2024-12-20

Added

• Multiple authentication strategies (Anonymous, PKCE, Pre-Auth, Client Credentials)
• Message type helpers (createContextMessage, createFeedbackMessage, etc.)
• Transcript management with filtering

[0.0.3] - 2024-12-15

Added

• Message queuing when offline
• Automatic queue flushing on reconnect
• queueFlushed event

[0.0.2] - 2024-12-10

Added

• WebSocket connection management
• Automatic reconnection with exponential backoff
• Event-driven architecture
• TypeScript type definitions

[0.0.1] - 2024-12-01

Added

• Initial release
• Basic WebSocket communication
• Pre-auth token authentication
• Message sending and receiving