@nextpa/chat-core 0.1.0

package/dist/core/widget-controller.js

@@ -0,0 +1,533 @@
+import { isDemoMode } from '../constants/defaults';
+import { logger } from '../utils/logger';
+import { primeAudioOnGesture } from '../utils/audio-context';
+import { playConnectChime } from '../utils/connect-chime';
+import { playEndCallSound, playMuteSound, playUnmuteSound } from '../utils/ui-sounds';
+import { initExtensionBridge, refreshExtensionContext } from '../services/page-interaction/extension-bridge';
+import { ConnectionManager } from './connection-manager';
+import { EventEmitter } from './event-emitter';
+import { WidgetCore } from './widget-core';
+import { VoiceStateManager } from './voice-state-manager';
+import { TextModeManager } from './text-mode-manager';
+import { ConnectionRetryHandler } from './connection-retry-handler';
+import { SessionBeacon } from './session-beacon';
+const LOG_PREFIX = '[WidgetController]';
+const DEMO_MESSAGE_DELAY_MS = 1000;
+const TEXT_STOP_DELAY_MS = 3000;
+const RECONNECT_DELAY_MS = 1500;
+const MAX_VOICE_RECOVERY_ATTEMPTS = 2;
+export class WidgetController extends EventEmitter {
+    core;
+    voiceConnectionManager;
+    voiceState;
+    textMode;
+    retryHandler;
+    sessionBeacon;
+    currentMode = 'voice';
+    pendingConnectMode = null;
+    isReconnecting = false;
+    showReconnecting = false;
+    voiceRecoveryAttempts = 0;
+    greetingOverride;
+    // UI feedback sounds (connect chime, mute/unmute, end-call) are a chat-app
+    // surface affordance; the embedded customer widget stays silent — shipping
+    // new sounds to customer sites is a product decision, not a refactor side-effect.
+    get uiSoundsEnabled() {
+        return this.core.source === 'chat-app';
+    }
+    constructor(options) {
+        super();
+        const notify = () => this.notifyStateChanged();
+        this.core = new WidgetCore(options, notify, (getDoc, getWin) => this.updateDocumentProviders(getDoc, getWin), () => this.connect(), LOG_PREFIX);
+        this.voiceConnectionManager = new ConnectionManager(this.core.apiClient);
+        this.voiceState = new VoiceStateManager(notify);
+        this.textMode = new TextModeManager(this.core.apiClient, notify);
+        this.retryHandler = new ConnectionRetryHandler();
+        this.sessionBeacon = new SessionBeacon();
+        this.voiceState.setupEventHandlers({
+            connectionManager: this.voiceConnectionManager,
+            apiClient: this.core.apiClient,
+            chatManager: this.core.chatManager,
+            persistence: this.core.persistence,
+            navigationManager: this.core.navigationManager,
+            onStopConversation: () => this.handleVoiceStopConversation(),
+            logPrefix: LOG_PREFIX,
+        });
+        this.voiceConnectionManager.on('unexpectedDisconnect', () => this.handleUnexpectedDisconnect());
+        this.voiceConnectionManager.on('voiceUnhealthy', (reason) => this.handleVoiceUnhealthy(reason));
+        this.voiceConnectionManager.on('voiceHealthy', () => { this.voiceRecoveryAttempts = 0; });
+        this.setupExtensionBridge();
+    }
+    async initialize() {
+        await this.core.initialize();
+    }
+    async connect(options) {
+        this.greetingOverride = options?.greeting;
+        if (this.currentMode === 'text') {
+            await this.connectText(false, options?.waitForGreeting ?? true);
+        }
+        else {
+            await this.connectVoice();
+        }
+    }
+    // The greeting is on when this connect's `greeting` override says so, otherwise per the
+    // per-assistant config.greetingEnabled. The chat-app / prior-conversation guards apply on top.
+    greetingEnabled(config) {
+        return this.greetingOverride ?? config.greetingEnabled !== false;
+    }
+    // Skip the spoken greeting when the greeting is off (override or config), on Chat-App surfaces
+    // (the operator is testing — the first user input is the opener), or when a prior conversation
+    // is already on screen (reconnect/resume must not re-greet).
+    shouldSkipVoiceGreeting(config) {
+        return !this.greetingEnabled(config)
+            || this.core.source === 'chat-app'
+            || this.core.chatManager.getMessages().length > 0;
+    }
+    async connectVoice() {
+        // Unlock audio while we still hold the user gesture, before any await —
+        // guarantees the later voice playback context can run on iOS.
+        primeAudioOnGesture();
+        const config = this.core.configManager.getConfig();
+        if (!config)
+            return;
+        if (!this.core.requireConsentOrConnect(config)) {
+            this.pendingConnectMode = 'voice';
+            return;
+        }
+        // Tear down the other channel before opening voice. Both managers
+        // open their own SignalR hub connection registered under the same
+        // ClientId — leaving the text hub up while voice opens its own
+        // produces two parallel registrations and the server kicks one of
+        // them, surfacing as an unexpected mid-call disconnect.
+        await this.textMode.disconnect();
+        this.currentMode = 'voice';
+        this.core.isConnecting = true;
+        this.core.hasError = false;
+        this.voiceRecoveryAttempts = 0;
+        this.voiceState.setLanguage(config.language);
+        this.voiceState.prepareForConnection();
+        this.notifyStateChanged();
+        const refreshedContext = await refreshExtensionContext();
+        if (refreshedContext) {
+            this.core.pageUrl = refreshedContext.url;
+            this.core.pageTitle = refreshedContext.title;
+        }
+        const connected = await this.retryHandler.retryAsync({
+            connectFn: async () => {
+                // Only rehydrate from storage if the panel is empty.
+                // initialize() already loaded history; clearing and reloading
+                // here would visibly blink the panel during the connect step.
+                if (this.core.chatManager.getMessages().length === 0) {
+                    await this.core.persistence.loadHistory(this.core.chatManager);
+                }
+                await this.voiceConnectionManager.connect(config, this.core.pageUrl, this.core.pageTitle, this.shouldSkipVoiceGreeting(config));
+            },
+            cleanupFn: () => this.voiceConnectionManager.disconnect(),
+            label: 'voice',
+            logPrefix: LOG_PREFIX,
+            onMicrophoneDenied: () => {
+                this.core.isConnecting = false;
+                this.notifyStateChanged();
+            },
+        });
+        this.handleRetryResult(connected);
+        if (connected && this.uiSoundsEnabled) {
+            // Short two-note chime once the realtime channel is up — same
+            // 'session-ready' cue as Skype/Discord, without shipping an asset.
+            playConnectChime();
+        }
+        if (connected && isDemoMode) {
+            this.core.showDemoWelcome(config);
+        }
+    }
+    async connectText(skipGreeting = false, waitForGreeting = true) {
+        const config = this.core.configManager.getConfig();
+        if (!config)
+            return;
+        this.textMode.setWaitForGreeting(waitForGreeting);
+        if (!this.core.requireConsentOrConnect(config)) {
+            this.pendingConnectMode = 'text';
+            return;
+        }
+        // Tear down the other channel — see connectVoice for the reason.
+        await this.voiceConnectionManager.disconnect();
+        this.voiceState.resetState();
+        this.currentMode = 'text';
+        this.core.isConnecting = true;
+        this.core.hasError = false;
+        this.textMode.setLanguage(config.language);
+        this.textMode.resetStreamState();
+        this.notifyStateChanged();
+        const connected = await this.retryHandler.retryAsync({
+            connectFn: async () => {
+                const textMgr = await this.textMode.ensureConnection();
+                this.textMode.setupEventHandlers({
+                    chatManager: this.core.chatManager,
+                    persistence: this.core.persistence,
+                    navigationManager: this.core.navigationManager,
+                    onError: () => { this.core.hasError = true; },
+                    onStopConversation: () => this.handleTextStopConversation(),
+                    logPrefix: LOG_PREFIX,
+                });
+                // Only rehydrate from storage if the panel is empty.
+                // initialize() already loaded history; clearing and reloading
+                // here would visibly blink the panel during the connect step.
+                if (this.core.chatManager.getMessages().length === 0) {
+                    await this.core.persistence.loadHistory(this.core.chatManager);
+                }
+                await textMgr.connect();
+            },
+            cleanupFn: () => this.textMode.disconnect(),
+            label: 'text',
+            logPrefix: LOG_PREFIX,
+        });
+        this.handleRetryResult(connected);
+        if (!connected)
+            return;
+        if (isDemoMode) {
+            this.core.showDemoWelcome(config);
+            return;
+        }
+        // Chat-App surfaces never want a greeting — see connectVoice. The greeting is otherwise on
+        // per the connect `greeting` override or config.greetingEnabled.
+        const suppressGreeting = skipGreeting || this.core.source === 'chat-app' || !this.greetingEnabled(config);
+        if (!suppressGreeting && this.core.chatManager.getMessages().length === 0) {
+            this.textMode.requestGreeting(this.core.pageUrl, this.core.pageTitle);
+        }
+    }
+    async disconnect(trimFarewell = false) {
+        this.isReconnecting = false;
+        this.showReconnecting = false;
+        this.sessionBeacon.unregister();
+        this.core.persistence.saveToLocalStorage(this.core.chatManager);
+        this.core.persistence.endSession(trimFarewell);
+        await this.disconnectCurrentMode();
+        this.notifyStateChanged();
+    }
+    async endCall() {
+        if (this.uiSoundsEnabled) {
+            playEndCallSound();
+        }
+        await this.disconnect();
+    }
+    async resetConversation() {
+        logger.debug(`${LOG_PREFIX} Resetting conversation...`);
+        await this.disconnectCurrentMode();
+        this.core.chatManager.clearMessages();
+        await this.core.persistence.resetMemory();
+        this.notifyStateChanged();
+        // 'Neuer Chat' always coming back in TEXT mode is a chat-app surface
+        // affordance (a reset mid-voice, or after a hang-up that left
+        // currentMode='voice', must not silently reopen the mic there; the
+        // greeting is skipped — the assistant greets with the first message).
+        // The embedded customer widget resets back into the CURRENT mode: a
+        // visitor who resets during a voice call expects to stay in voice.
+        if (this.core.source === 'chat-app') {
+            await this.connectText(true);
+            return;
+        }
+        await this.connect();
+    }
+    submitSessionFeedback(rating) {
+        this.core.apiClient.submitSessionFeedback(rating).catch((err) => {
+            logger.debug(`${LOG_PREFIX} Failed to submit session feedback:`, err);
+        });
+    }
+    submitFeedback(messageId, rating) {
+        if (rating == null) {
+            this.core.chatManager.setFeedback(messageId, undefined);
+            this.notifyStateChanged();
+            return;
+        }
+        this.core.chatManager.setFeedback(messageId, rating);
+        this.notifyStateChanged();
+        this.core.apiClient.submitFeedback(messageId, rating).catch((err) => {
+            logger.debug(`${LOG_PREFIX} Failed to submit feedback:`, err);
+        });
+    }
+    async sendMessage(text) {
+        if (!text.trim())
+            return;
+        if (isDemoMode) {
+            this.core.chatManager.addUserMessage(text);
+            setTimeout(() => {
+                this.core.chatManager.addAssistantMessage(`Dies ist eine Demo-Antwort auf: "${text}"\n\nIm Produktivbetrieb würde hier die KI-Antwort erscheinen.`);
+            }, DEMO_MESSAGE_DELAY_MS);
+            return;
+        }
+        const refreshedContext = await refreshExtensionContext();
+        if (refreshedContext) {
+            this.core.pageUrl = refreshedContext.url;
+            this.core.pageTitle = refreshedContext.title;
+        }
+        if (this.currentMode === 'text') {
+            try {
+                await this.textMode.sendMessage(text, this.core.pageUrl, this.core.pageTitle);
+            }
+            catch (err) {
+                logger.debug(`${LOG_PREFIX} Failed to send text message:`, err);
+                this.core.hasError = true;
+                this.notifyStateChanged();
+            }
+        }
+        else {
+            this.core.chatManager.addUserMessage(text);
+            this.core.persistence.persistMessage('User', text, this.voiceState.language, undefined, undefined, undefined, 'Typed');
+            this.notifyStateChanged();
+            await this.voiceConnectionManager.sendText(text);
+        }
+    }
+    toggleMute() {
+        const wasMuted = this.voiceState.isMuted;
+        this.voiceState.toggleMute();
+        if (!this.uiSoundsEnabled)
+            return;
+        if (wasMuted) {
+            playUnmuteSound();
+        }
+        else {
+            playMuteSound();
+        }
+    }
+    stopVoiceResponse() {
+        if (this.currentMode !== 'voice')
+            return;
+        this.voiceState.stop();
+    }
+    transcribe(audio, signal) {
+        return this.core.apiClient.transcribeAudio(audio, signal);
+    }
+    toggleMinimized() {
+        this.core.toggleMinimized();
+    }
+    setMinimized(minimized) {
+        this.core.setMinimized(minimized);
+    }
+    acceptTerms() {
+        this.core.acceptTerms(() => {
+            const mode = this.pendingConnectMode ?? this.currentMode;
+            this.pendingConnectMode = null;
+            if (mode === 'text') {
+                this.connectText();
+            }
+            else {
+                this.connectVoice();
+            }
+        });
+    }
+    declineTerms() {
+        this.core.declineTerms();
+    }
+    dismissBlockedUrl() {
+        this.core.dismissBlockedUrl();
+    }
+    openBlockedUrl() {
+        this.core.openBlockedUrl();
+    }
+    dismissPopover() {
+        this.core.dismissPopover();
+    }
+    getState() {
+        return {
+            config: this.core.configManager.getConfig(),
+            resolvedTheme: this.core.themeManager.resolvedTheme,
+            isLoading: this.core.isLoading,
+            initFailed: this.core.initFailed,
+            hasError: this.core.hasError,
+            isMicrophoneBlocked: this.voiceState.isMicrophoneBlocked,
+            isMinimized: this.core.isMinimized,
+            isConnecting: this.core.isConnecting,
+            connectionState: this.getActiveConnectionState(),
+            currentMode: this.currentMode,
+            isMuted: this.voiceState.isMuted,
+            isMicrophoneReady: this.voiceState.isMicrophoneReady,
+            isUserSpeaking: this.voiceState.isUserSpeaking,
+            audioLevel: this.voiceState.audioLevel,
+            isAiThinking: this.voiceState.isAiThinking,
+            isStreaming: this.currentMode === 'text' ? this.textMode.isStreaming : this.voiceState.isStreaming,
+            isAssistantSpeaking: this.currentMode === 'text' ? false : this.voiceState.isAssistantSpeaking,
+            streamingContent: this.currentMode === 'text' ? this.textMode.streamContent : this.voiceState.streamContent,
+            isTranscribing: this.voiceState.isTranscribing,
+            transcribingContent: this.voiceState.transcribingContent,
+            messages: this.core.chatManager.getMessages(),
+            agentStatus: this.currentMode === 'text' ? this.textMode.agentStatus : this.voiceState.agentStatus,
+            showTermsModal: this.core.consentManager.showTermsModal,
+            hasConsented: this.core.consentManager.hasConsented,
+            blockedUrl: this.core.navigationManager.blockedUrl,
+            showPopover: this.core.popoverManager.showPopover,
+        };
+    }
+    dispose() {
+        this.voiceConnectionManager.dispose();
+        this.textMode.dispose();
+        this.core.dispose();
+        this.removeAllListeners();
+    }
+    notifyStateChanged() {
+        this.emit('stateChanged', this.getState());
+    }
+    getActiveConnectionState() {
+        if (this.showReconnecting)
+            return 'reconnecting';
+        if (this.isReconnecting)
+            return 'connecting';
+        if (this.currentMode === 'text') {
+            return this.textMode.getConnectionState();
+        }
+        return this.voiceConnectionManager.getConnectionState();
+    }
+    handleRetryResult(connected) {
+        if (connected) {
+            // A failed attempt earlier in the retry loop will have flipped
+            // hasError on; reset it so the surface doesn't keep showing the
+            // banner after a successful reconnect.
+            this.core.hasError = false;
+            const config = this.core.configManager.getConfig();
+            if (config) {
+                this.core.persistence.setAssistantId(config.assistantId);
+                const clientId = this.core.apiClient.getClientId();
+                if (clientId) {
+                    this.sessionBeacon.register(this.core.apiClient.getBaseUrl(), clientId, config.assistantId, () => this.handleSessionResumed());
+                }
+                this.core.persistence.startNewSession();
+            }
+        }
+        else {
+            this.core.hasError = true;
+        }
+        this.core.isConnecting = false;
+        this.notifyStateChanged();
+    }
+    handleSessionResumed() {
+        this.core.persistence.startNewSession();
+    }
+    async disconnectCurrentMode() {
+        if (this.currentMode === 'text') {
+            await this.textMode.disconnect();
+            return;
+        }
+        await this.voiceConnectionManager.disconnect();
+        this.voiceState.resetState();
+    }
+    async handleUnexpectedDisconnect() {
+        if (this.currentMode !== 'voice' || this.isReconnecting)
+            return;
+        const config = this.core.configManager.getConfig();
+        if (!config)
+            return;
+        logger.warn(`${LOG_PREFIX} Unexpected voice disconnect, attempting reconnect...`);
+        this.isReconnecting = true;
+        this.showReconnecting = true;
+        this.core.isConnecting = true;
+        this.voiceState.resetState();
+        this.voiceState.prepareForConnection();
+        this.notifyStateChanged();
+        await new Promise((resolve) => setTimeout(resolve, RECONNECT_DELAY_MS));
+        if (!this.isReconnecting)
+            return;
+        const connected = await this.retryHandler.retryAsync({
+            connectFn: async () => {
+                await this.voiceConnectionManager.connect(config, this.core.pageUrl, this.core.pageTitle, this.shouldSkipVoiceGreeting(config));
+            },
+            cleanupFn: () => this.voiceConnectionManager.disconnect(),
+            label: 'voice-reconnect',
+            logPrefix: LOG_PREFIX,
+        });
+        this.isReconnecting = false;
+        this.showReconnecting = false;
+        if (connected) {
+            logger.debug(`${LOG_PREFIX} Voice reconnect successful`);
+        }
+        else {
+            logger.error(`${LOG_PREFIX} Voice reconnect failed`);
+            this.core.hasError = true;
+        }
+        this.core.isConnecting = false;
+        this.notifyStateChanged();
+    }
+    // The watchdog reports a "connected but dead" voice session (no setup or the
+    // greeting never responds) where no disconnect event fires. Recover by
+    // tearing the dead session down and reconnecting — exactly what a manual
+    // reset does. First attempt is silent; from the second it shows the
+    // reconnecting indicator. Capped so a persistently broken backend surfaces
+    // an error instead of looping.
+    async handleVoiceUnhealthy(reason) {
+        if (this.currentMode !== 'voice' || this.isReconnecting)
+            return;
+        const config = this.core.configManager.getConfig();
+        if (!config)
+            return;
+        this.voiceRecoveryAttempts++;
+        if (this.voiceRecoveryAttempts > MAX_VOICE_RECOVERY_ATTEMPTS) {
+            logger.error(`${LOG_PREFIX} Voice unhealthy (${reason}) — recovery exhausted after ${MAX_VOICE_RECOVERY_ATTEMPTS} attempts`);
+            await this.voiceConnectionManager.disconnect();
+            this.core.hasError = true;
+            this.core.isConnecting = false;
+            this.notifyStateChanged();
+            return;
+        }
+        const visible = this.voiceRecoveryAttempts >= 2;
+        logger.warn(`${LOG_PREFIX} Voice unhealthy (${reason}), recovery attempt ${this.voiceRecoveryAttempts}${visible ? ' (visible)' : ' (silent)'}`);
+        this.isReconnecting = true;
+        this.showReconnecting = visible;
+        // Mark connecting so the chooser (DisconnectedView) shows its spinner with
+        // disabled buttons during recovery instead of clickable Voice/Text buttons.
+        this.core.isConnecting = true;
+        if (visible) {
+            this.voiceState.resetState();
+            this.voiceState.prepareForConnection();
+        }
+        this.notifyStateChanged();
+        await this.voiceConnectionManager.disconnect();
+        await new Promise((resolve) => setTimeout(resolve, RECONNECT_DELAY_MS));
+        if (!this.isReconnecting)
+            return;
+        const connected = await this.retryHandler.retryAsync({
+            connectFn: async () => {
+                await this.voiceConnectionManager.connect(config, this.core.pageUrl, this.core.pageTitle, this.shouldSkipVoiceGreeting(config));
+            },
+            cleanupFn: () => this.voiceConnectionManager.disconnect(),
+            label: 'voice-health-recovery',
+            logPrefix: LOG_PREFIX,
+        });
+        this.isReconnecting = false;
+        this.showReconnecting = false;
+        if (connected) {
+            logger.debug(`${LOG_PREFIX} Voice recovery reconnect successful`);
+        }
+        else {
+            logger.error(`${LOG_PREFIX} Voice recovery reconnect failed`);
+            this.core.hasError = true;
+        }
+        this.core.isConnecting = false;
+        this.notifyStateChanged();
+    }
+    async handleVoiceStopConversation() {
+        logger.debug(`${LOG_PREFIX} Voice StopConversation received`);
+        await this.disconnect(true);
+        this.core.isMinimized = true;
+        this.notifyStateChanged();
+    }
+    async handleTextStopConversation() {
+        logger.debug(`${LOG_PREFIX} Text StopConversation received, closing after delay`);
+        this.textMode.isSessionEnding = true;
+        await new Promise((resolve) => setTimeout(resolve, TEXT_STOP_DELAY_MS));
+        await this.disconnect(true);
+        this.core.isMinimized = true;
+        this.textMode.isSessionEnding = false;
+        this.notifyStateChanged();
+    }
+    updateDocumentProviders(getDoc, getWin) {
+        this.voiceConnectionManager.setDocumentProvider(getDoc, getWin);
+        this.textMode.setDocumentProvider(getDoc, getWin);
+    }
+    setupExtensionBridge() {
+        initExtensionBridge([
+            (executor) => this.voiceConnectionManager.setExternalExecutor(executor),
+            (executor) => this.textMode.setExternalExecutor(executor),
+        ], (ctx) => {
+            this.core.pageUrl = ctx.url;
+            this.core.pageTitle = ctx.title;
+        });
+    }
+}

package/dist/core/widget-core.d.ts

@@ -0,0 +1,51 @@
+import { WidgetApiClient } from '../services/api';
+import type { DocumentProvider, WindowProvider } from '../services/page-interaction/page-interaction-handler';
+import { ConfigManager } from './config-manager';
+import { ChatManager } from './chat-manager';
+import { ThemeManager } from './theme-manager';
+import { ConsentManager } from './consent-manager';
+import { PopoverManager } from './popover-manager';
+import { NavigationManager } from './navigation-manager';
+import { ConversationPersistence } from './conversation-persistence';
+import type { WidgetConfig } from '../types';
+import type { WidgetControllerOptions } from './types';
+type StateChangeCallback = () => void;
+type DocumentProviderCallback = (getDoc: DocumentProvider, getWin: WindowProvider) => void;
+type ConnectCallback = () => void;
+export declare class WidgetCore {
+    readonly apiClient: WidgetApiClient;
+    readonly configManager: ConfigManager;
+    readonly chatManager: ChatManager;
+    readonly themeManager: ThemeManager;
+    readonly consentManager: ConsentManager;
+    readonly popoverManager: PopoverManager;
+    readonly navigationManager: NavigationManager;
+    readonly persistence: ConversationPersistence;
+    isMinimized: boolean;
+    isConnecting: boolean;
+    hasError: boolean;
+    isLoading: boolean;
+    initFailed: boolean;
+    pageUrl?: string;
+    pageTitle?: string;
+    private readonly onStateChanged;
+    private readonly onConnect;
+    private readonly logPrefix;
+    readonly source: string | undefined;
+    constructor(options: WidgetControllerOptions, onStateChanged: StateChangeCallback, onDocumentProviders: DocumentProviderCallback, onConnect: ConnectCallback, logPrefix: string);
+    initialize(): Promise<void>;
+    toggleMinimized(): void;
+    setMinimized(minimized: boolean): void;
+    dismissPopover(): void;
+    acceptTerms(onAccepted: () => void): void;
+    declineTerms(): void;
+    dismissBlockedUrl(): void;
+    openBlockedUrl(): void;
+    requireConsentOrConnect(config: WidgetConfig): boolean;
+    showDemoWelcome(config: WidgetConfig): void;
+    dispose(): void;
+    private detectPageContext;
+    private resolvePageHost;
+    private checkForReconnect;
+}
+export {};