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.3.2] - 2026-10-13

Fixed

• Access token refresh buffer aligned across auth strategies. Anonymous and pre-auth strategies now refresh cached tokens five minutes before JWT expiry (was 1 minute and 3 minutes respectively), matching PKCE and cc-widget isValidToken. This avoids POST …/session returning 401 with "Token will expire soon" while the SDK still considered the anonymous token valid (session create rejects tokens with less than ~290s remaining).

Added

• ACCESS_TOKEN_REFRESH_BUFFER_MS and ACCESS_TOKEN_REFRESH_BUFFER_MINUTES on AuthStrategy and re-exported from the package entry for integrators who need the same threshold.

[0.3.1] - 2026-10-09

Changed

• Chat WebSocket host comes from the agent details API when available. GET /core/aiservices/v4/aiagent/details/agent/{agentId} can now return webSocketDomain, the host of the WebSocket APIs of the deployment that answered the request. When present and non-empty, the SDK connects to wss://<webSocketDomain>, appending sessionId / externalCallId as before. Otherwise it keeps deriving wss://chat.<deploymentInfo.aiAgentDomain>. This lets a DR region, whose chat stack listens on a region-suffixed host, be reached without any change to the tenant's deployment info.

[0.3.0] - 2026-10-08

Removed

• AiAgentConfig.scopes. Hosts that need their own scope list pass initParams.scopes (comma-separated) or a full PKCEAuthConfig; everything else is SDK-managed.

Changed

• Host-supplied scopes are used exactly as given. A host PKCEAuthConfig.scopes wins over initParams.scopes, and the config is never modified (a scope-less host config is filled from initParams.scopes when present). initParams.scopes get no defaults, no agent extraScopes and no platform augmentation. addCustomAuthScopes is only called when the host supplied no scopes, seeded with the defaults.

Added

• Per-agent extraScopes — the agent details API (GET /core/aiservices/v4/aiagent/details/agent/{agentId}) can return extraScopes, configured in the admin console under Settings → Advanced. On the SDK-managed path (no host-supplied scopes) they are appended (deduplicated) after the defaults / platform list, for the anonymous client-credentials token and the PKCE config the SDK builds from deployment info. They are never applied to a host-supplied PKCE config (its scopes are already fully qualified; debug log). HookContract.getAuthScopes() returns the resolved list.
• Per-agent clientAppId — when the agent details API returns clientAppId, the built PKCE config uses it as the MSAL client id. Priority: initParams.egclientid → agentDetails.clientAppId → deployment intClientId / extClientId / clientId. The anonymous token keeps its fixed client id.
• AgentAuthDetails type export.

Changed

• Anonymous token scopes now follow the same resolution as PKCE. Previously the anonymous session token always requested the two bare defaults. After agent details load, the anonymous strategy is re-scoped (AuthenticationService.updateScopes → AnonymousAuthStrategy.updateScopes) with the resolved list: core.customermgr.read for customer agents, initParams.scopes / config.scopes when set, and the agent's extraScopes. The anonymous client is permitted every scope, so nothing that worked before fails; agents whose resolved list differs from the defaults make one extra token request at startup, cached for the session.
• Anonymous token cache key now ends with a fingerprint of the requested scope set (…:anonymous_token:<fnv1a>), so a token cached for a smaller scope set is never reused for a larger one. Entries under the old key are ignored and expire with their own TTL.

[0.2.5] - 2026-09-23

Fixed

• PlatformComponentService.getDefaultPortal() and availablePortals — when a connector auto-selects a portal via getDefaultPortal, PortalInitializer now stores the full PCS-processed portal list before continuing the pipeline. The initialized event includes availablePortals with every portal the user can switch to (not only the selected one). Fixes cc-widget contact-center hosts where the header portal edit control stayed disabled despite multiple portals.

[0.2.4] - 2026-09-XX

Added

• PKCE MSAL logout — AiAgent.logout() disconnects chat, then AuthenticationService.logout() / PKCEAuthStrategy.logout(). No caller LogoutOptions: the strategy matches login authScheme (logoutPopup / logoutRedirect). Popup omits OAuth state and sets postLogoutRedirectUri to redirectUri?logout=true so auth-redirect.html can close the window. Redirect passes hash-stripped nextRoute (else window.location.href) as state and uses redirectUri as-is. idTokenHint comes from the active account. end_session_endpoint is read from the OAuth metadata URL at PKCE config build and constructed only when absent. If MSAL throws, logout falls back to the access-token JWT logout claim, then that endpoint. MSAL clears its own cache; the strategy does not call clearCache / removeAccount. Anonymous and other strategies without logout() no-op at AuthenticationService (cached token is dropped). Host UI state is not cleared.
• Session-stored profile selection — PortalInitializer reads v2_{rigelPrefix}selectedProfile-{portalId} from sessionStorage as the first auto-select rule when multiple profiles are available (cc-widget parity). Rigel prefix comes from deploymentInfo.tenant_identifier, with fallback to the first path segment of AiAgent’s endpoint URL.
• Session profile persistence — after auto-select or selectUserProfile(), the SDK writes the selected profile to the same session key (name, id, isLastUsedInPortal, portalId).

Changed

• Profile auto-select priority (multiple profiles) — session storage → egain_personalization_profile_id → isLastUsedInPortal → portal default → profilesAvailable

Documentation

• Authentication guide: PKCE IdP logout (AiAgent.logout()), popup vs redirect, fallbacks, and host-owned UI teardown

[0.2.3] - 2026-09-11

Added

• externalCallId on chat WebSocket — when a platform connector sets conversationId, getWsEndpoint() appends it as the externalCallId query parameter on the chat WebSocket URL (cc-widget parity for call-linked sessions)
• egtemplate init param — portal initializer resolves the short URL template from initParams.egtemplate when templateName and shortUrlTemplate are absent (priority: templateName → shortUrlTemplate → egtemplate)
• jwt-decode dependency — used by PKCEAuthStrategy for cached access-token expiry checks

Fixed

• PKCE silent token errors — PKCEAuthStrategy.getToken() and refreshToken() match cc-widget auth.ts on silent SSO failure: InteractionRequiredAuthError falls back to authenticate() (popup) or acquireTokenRedirect (redirect); monitor_window_timeout falls back to acquireTokenPopup. authenticate() always runs interactive login (loginPopup / loginRedirect); AiAgent skips it when initialize already restored a session. Previously those errors were rethrown or a stale token was returned, which aborted portal init in embedded hosts such as Genesys.
• 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).
• PKCE cached token validation — PKCEAuthStrategy.getToken() validates the cached access token with a 5-minute expiry buffer before silent acquisition; expired tokens are refreshed instead of returned
• PKCE hash_empty_error — MSAL browser-compatibility failures map to AuthError with an actionable refresh message instead of surfacing the raw MSAL error
• 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())
• API language from agent details — AiAgent syncs agentDetails.languageCode onto ApiHelper after fetching agent details, so portal and masking APIs use the bot-configured locale instead of defaulting to en-us
• HookContract.setUserFilterTags() — merges user_filter_tags into userContext and stored agent context instead of only updating in-memory filter tags; existing context keys are preserved
• initPlatform timing — PlatformComponentService.initPlatform() runs in onAuthComplete after data-masking patterns are loaded and before the portal pipeline, so connectors can rely on masking being available during platform init
• Anonymous token reuse on remount — AnonymousAuthStrategy.cleanup() is a no-op so sessionStorage token and metadata survive widget remounts and anonymous → PKCE strategy switches; use clearTokenCache() / clearMetadataCache() to force a refresh
• WebSocket reconnection on normal close — Connection no longer schedules reconnect when the close code is 1000 or 1005 (normal or no-status closure)

Changed

• ApiHelper.setLanguage() — updates the instance language used by portal and masking APIs ($lang and Accept-Language); per-call language options are not supported; Accept-Language header mapping follows cc-widget rules (e.g. en-GB → en-us)
• ApiHelper.getPortals() caching — responses are cached when cache.enabled is true, keyed by language and departmentId (aligned with getMyPortals; previously always fetched fresh)
• HookContract.getMsalAccessToken() — returns only the cached token synchronously; removed fire-and-forget getToken() side effect (use getAccessToken() when a fresh token is required)
• HookContract.getEnvironment() — documents "non-prod" as a valid value (stage / eustage builds)
• Platform environment derivation — deriveEnvironment() uses only the env init param (dev, qa, non-prod, prod); API-domain parsing and legacy env aliases (stage, euprod, etc.) removed — unrecognized values default to prod
• MSAL browser bundling — PKCE loads the vendored msal-browser.js via msal-loader module import instead of relying on a global window.msal; the browser bundle no longer exposes window.msal

[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 (CC and SS), 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