@nextpa/chat-core 0.1.0

package/dist/core/navigation-manager.js

@@ -0,0 +1,132 @@
+import { logger } from '../utils/logger';
+import { IframeNavigationManager } from '../services/page-interaction/iframe-navigation-manager';
+import { resolveSameOriginTarget } from '../core/link-target';
+const RECONNECT_MAX_AGE_MS = 30_000;
+const RECONNECT_STORAGE_KEY = 'nextpa-widget-reconnect';
+export class NavigationManager {
+    _blockedUrl = null;
+    iframeNavManager;
+    onStateChanged;
+    onDocumentProviderChanged;
+    getPageHost;
+    get blockedUrl() {
+        return this._blockedUrl;
+    }
+    constructor(onStateChanged, onDocumentProviderChanged, getPageHost) {
+        this.iframeNavManager = new IframeNavigationManager();
+        this.onStateChanged = onStateChanged;
+        this.onDocumentProviderChanged = onDocumentProviderChanged;
+        this.getPageHost = getPageHost;
+    }
+    resolveTargetForUrl(url) {
+        return resolveSameOriginTarget(url, this.getPageHost());
+    }
+    checkForReconnect() {
+        try {
+            const raw = sessionStorage.getItem(RECONNECT_STORAGE_KEY);
+            if (!raw)
+                return false;
+            sessionStorage.removeItem(RECONNECT_STORAGE_KEY);
+            const data = JSON.parse(raw);
+            const age = Date.now() - data.timestamp;
+            if (age > RECONNECT_MAX_AGE_MS)
+                return false;
+            logger.debug('[NavigationManager] Fast reconnect after navigation fallback');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    openUrl(url) {
+        const target = this.resolveTargetForUrl(url);
+        logger.debug('[NavigationManager] Opening URL:', url, '| target:', target);
+        if (target === '_self') {
+            this.navigateSameTab(url);
+            return;
+        }
+        this.openInNewTab(url);
+    }
+    dismissBlockedUrl() {
+        this._blockedUrl = null;
+        this.onStateChanged();
+    }
+    openBlockedUrl() {
+        if (!this._blockedUrl)
+            return;
+        const url = this._blockedUrl;
+        this._blockedUrl = null;
+        this.onStateChanged();
+        if (this.resolveTargetForUrl(url) === '_self') {
+            this.navigateSameTab(url);
+        }
+        else {
+            this.openInNewTab(url);
+        }
+    }
+    dispose() {
+        this.iframeNavManager.close();
+    }
+    navigateSameTab(url) {
+        const event = new CustomEvent('nextpa:navigate', {
+            detail: { url },
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+        });
+        // Customer widget: the host listens on the <nextpa-widget> element. In-page hosts
+        // (the in-shell assistant) have no such element, so fall back to dispatching on the
+        // document — a host listener can preventDefault to take over navigation (e.g. a Blazor
+        // SPA route change) instead of the iframe-overlay / full-reload fallback.
+        const target = document.querySelector('nextpa-widget') ?? document;
+        const handled = !target.dispatchEvent(event);
+        if (handled)
+            return;
+        this.navigateViaIframeWithFallback(url);
+    }
+    navigateViaIframeWithFallback(url) {
+        const wasAlreadyActive = this.iframeNavManager.isActive();
+        this.iframeNavManager.navigateTo(url).then((result) => {
+            if (result.status === 'iframe-loaded') {
+                logger.debug('[NavigationManager] Navigation loaded in iframe:', url);
+                const getDoc = () => this.iframeNavManager.getTargetDocument();
+                const getWin = () => this.iframeNavManager.getTargetWindow();
+                this.onDocumentProviderChanged(getDoc, getWin);
+                if (!wasAlreadyActive) {
+                    this.iframeNavManager.onClose(() => {
+                        this.onDocumentProviderChanged(() => document, () => globalThis);
+                    });
+                }
+                return;
+            }
+            logger.debug('[NavigationManager] Iframe blocked, falling back to full navigation:', result.reason);
+            this.saveStateForReconnect();
+            globalThis.location.href = url;
+        });
+    }
+    openInNewTab(url) {
+        try {
+            const win = globalThis.open(url, '_blank');
+            if (win !== null)
+                return;
+            logger.warn('[NavigationManager] Popup blocked:', url);
+            this.showBlockedUrl(url);
+        }
+        catch {
+            logger.warn('[NavigationManager] Failed to open:', url);
+            this.showBlockedUrl(url);
+        }
+    }
+    showBlockedUrl(url) {
+        this._blockedUrl = url;
+        this.onStateChanged();
+    }
+    saveStateForReconnect() {
+        try {
+            sessionStorage.setItem(RECONNECT_STORAGE_KEY, JSON.stringify({
+                timestamp: Date.now(),
+            }));
+        }
+        catch { /* private browsing or storage full */ }
+    }
+}

package/dist/core/popover-manager.d.ts

@@ -0,0 +1,14 @@
+import type { WidgetConfig } from '../types';
+type StateChangeCallback = () => void;
+export declare class PopoverManager {
+    private _showPopover;
+    private timerId;
+    private readonly onStateChanged;
+    get showPopover(): boolean;
+    constructor(onStateChanged: StateChangeCallback);
+    initialize(config: WidgetConfig): void;
+    dismiss(): void;
+    dispose(): void;
+    private clearTimer;
+}
+export {};

package/dist/core/popover-manager.js

@@ -0,0 +1,36 @@
+const DEFAULT_AUTO_CLOSE_SECONDS = 5;
+const MS_PER_SECOND = 1000;
+export class PopoverManager {
+    _showPopover = false;
+    timerId = null;
+    onStateChanged;
+    get showPopover() {
+        return this._showPopover;
+    }
+    constructor(onStateChanged) {
+        this.onStateChanged = onStateChanged;
+    }
+    initialize(config) {
+        if (!config.popoverEnabled || !config.popoverText)
+            return;
+        this._showPopover = true;
+        const autoCloseSeconds = config.popoverAutoCloseSeconds ?? DEFAULT_AUTO_CLOSE_SECONDS;
+        this.timerId = setTimeout(() => this.dismiss(), autoCloseSeconds * MS_PER_SECOND);
+    }
+    dismiss() {
+        if (!this._showPopover)
+            return;
+        this._showPopover = false;
+        this.clearTimer();
+        this.onStateChanged();
+    }
+    dispose() {
+        this.clearTimer();
+    }
+    clearTimer() {
+        if (!this.timerId)
+            return;
+        clearTimeout(this.timerId);
+        this.timerId = null;
+    }
+}

package/dist/core/session-beacon.d.ts

@@ -0,0 +1,11 @@
+export declare class SessionBeacon {
+    private beaconUrl;
+    private beaconPayload;
+    private registered;
+    private sent;
+    private onSessionResumed;
+    private readonly handleVisibilityChange;
+    register(baseUrl: string, clientId: string, assistantId: string, onSessionResumed: () => void): void;
+    unregister(): void;
+    private sendBeacon;
+}

package/dist/core/session-beacon.js

@@ -0,0 +1,60 @@
+import { logger } from '../utils/logger';
+const LOG_PREFIX = '[SessionBeacon]';
+export class SessionBeacon {
+    beaconUrl = null;
+    beaconPayload = null;
+    registered = false;
+    sent = false;
+    onSessionResumed = null;
+    handleVisibilityChange = () => {
+        if (document.visibilityState === 'hidden') {
+            this.sendBeacon();
+            return;
+        }
+        if (this.sent) {
+            this.sent = false;
+            logger.debug(`${LOG_PREFIX} Tab returned after beacon, resuming session`);
+            this.onSessionResumed?.();
+        }
+    };
+    register(baseUrl, clientId, assistantId, onSessionResumed) {
+        if (this.registered)
+            return;
+        this.beaconUrl = `${baseUrl}/api/widget/conversation/end-beacon`;
+        // tenantId is no longer sent — the server derives it from the Assistant aggregate.
+        this.beaconPayload = JSON.stringify({ clientId, assistantId });
+        this.onSessionResumed = onSessionResumed;
+        this.registered = true;
+        this.sent = false;
+        document.addEventListener('visibilitychange', this.handleVisibilityChange);
+        logger.debug(`${LOG_PREFIX} Registered beacon`);
+    }
+    unregister() {
+        if (!this.registered)
+            return;
+        document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+        this.beaconUrl = null;
+        this.beaconPayload = null;
+        this.onSessionResumed = null;
+        this.registered = false;
+        this.sent = false;
+        logger.debug(`${LOG_PREFIX} Unregistered beacon`);
+    }
+    sendBeacon() {
+        if (!this.beaconUrl || !this.beaconPayload || this.sent)
+            return;
+        this.sent = true;
+        fetch(this.beaconUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: this.beaconPayload,
+            keepalive: true,
+        }).catch(() => {
+            if (this.beaconUrl && this.beaconPayload) {
+                const blob = new Blob([this.beaconPayload], { type: 'application/json' });
+                navigator.sendBeacon(this.beaconUrl, blob);
+            }
+        });
+        logger.debug(`${LOG_PREFIX} Beacon sent`);
+    }
+}

package/dist/core/text-connection-manager.d.ts

@@ -0,0 +1,58 @@
+import type { ConnectionState } from '../types';
+import type { WidgetApiClient } from '../services/api';
+import { type DocumentProvider, type WindowProvider, type ExternalExecutor } from '../services/page-interaction/page-interaction-handler';
+import { EventEmitter } from './event-emitter';
+interface TextStreamDelta {
+    readonly delta: string;
+    readonly messageId: string;
+}
+interface TextStreamCompleted {
+    readonly fullText: string;
+    readonly messageId: string;
+}
+interface TextToolCall {
+    readonly toolName: string;
+    readonly status: string;
+    readonly result?: string;
+    readonly agentLabel?: string;
+}
+interface TextConnectionEvents {
+    connectionStateChanged: (state: ConnectionState) => void;
+    streamDelta: (data: TextStreamDelta) => void;
+    streamCompleted: (data: TextStreamCompleted) => void;
+    toolCall: (data: TextToolCall) => void;
+    error: (error: string) => void;
+    stopConversation: () => void;
+    openUrl: (url: string) => void;
+    openFile: (url: string) => void;
+}
+export declare class TextConnectionManager extends EventEmitter<TextConnectionEvents> {
+    private signalRService;
+    private pageInteractionHandler;
+    private readonly apiClient;
+    private connectionState;
+    private serviceInitialized;
+    private pendingExternalExecutor;
+    private pendingDocumentProvider;
+    private greetingActive;
+    private pendingSends;
+    private greetingHoldTimer;
+    constructor(apiClient: WidgetApiClient);
+    private initializeService;
+    private setupEventHandlers;
+    connect(): Promise<void>;
+    private setupTextChatHandlers;
+    private setupPageInteractionHandler;
+    private simulateDemoConnection;
+    sendMessage(text: string, pageUrl?: string, pageTitle?: string, isGreeting?: boolean): Promise<void>;
+    sendGreeting(pageUrl?: string, pageTitle?: string): Promise<void>;
+    private beginGreetingHold;
+    private releaseGreetingHold;
+    disconnect(): Promise<void>;
+    setDocumentProvider(getDoc: DocumentProvider, getWin: WindowProvider): void;
+    setExternalExecutor(executor: ExternalExecutor | null): void;
+    getConnectionState(): ConnectionState;
+    isConnected(): boolean;
+    dispose(): void;
+}
+export {};

package/dist/core/text-connection-manager.js

@@ -0,0 +1,200 @@
+import { PageInteractionHandler } from '../services/page-interaction/page-interaction-handler';
+import { isDemoMode } from '../constants/defaults';
+import { logger } from '../utils/logger';
+import { EventEmitter } from './event-emitter';
+const DEMO_CONNECTION_DELAY_MS = 300;
+// Safety cap: if a greeting never streams (error / no response), release held user messages anyway.
+const GREETING_HOLD_TIMEOUT_MS = 15_000;
+export class TextConnectionManager extends EventEmitter {
+    signalRService = null;
+    pageInteractionHandler = null;
+    apiClient;
+    connectionState = 'disconnected';
+    serviceInitialized = false;
+    pendingExternalExecutor = null;
+    pendingDocumentProvider = null;
+    // While the greeting streams, user messages are held (like voice keeps the mic muted until the
+    // greeting audio ends) and flushed once the greeting completes.
+    greetingActive = false;
+    pendingSends = [];
+    greetingHoldTimer = null;
+    constructor(apiClient) {
+        super();
+        this.apiClient = apiClient;
+    }
+    async initializeService() {
+        if (this.serviceInitialized) {
+            return;
+        }
+        logger.debug('[TextConnectionManager] Lazy loading SignalR service...');
+        const { SignalRService } = await import('../services/signalr');
+        this.signalRService = new SignalRService();
+        this.setupEventHandlers();
+        this.serviceInitialized = true;
+        logger.debug('[TextConnectionManager] Service initialized');
+    }
+    setupEventHandlers() {
+        if (!this.signalRService) {
+            return;
+        }
+        this.signalRService.setEventHandlers({
+            onStopConversation: () => this.emit('stopConversation'),
+            onOpenUrl: (url) => this.emit('openUrl', url),
+            onOpenFile: (url) => this.emit('openFile', url),
+            onError: (title, message) => this.emit('error', `${title}: ${message}`),
+        });
+    }
+    async connect() {
+        if (isDemoMode) {
+            await this.simulateDemoConnection();
+            return;
+        }
+        await this.initializeService();
+        if (!this.signalRService) {
+            throw new Error('SignalR service not initialized');
+        }
+        try {
+            this.connectionState = 'connecting';
+            this.emit('connectionStateChanged', 'connecting');
+            const bearerToken = this.apiClient.getBearerToken();
+            if (!bearerToken) {
+                throw new Error('Not authenticated');
+            }
+            const claims = this.apiClient.getTokenClaims();
+            this.signalRService.setRegistrationInfo(this.apiClient.getClientId(), claims.tenantId ?? '00000000-0000-0000-0000-000000000000', claims.userId ?? '00000000-0000-0000-0000-000000000000');
+            this.setupTextChatHandlers(this.signalRService);
+            this.setupPageInteractionHandler(this.signalRService);
+            await this.signalRService.connect(this.apiClient.getBaseUrl(), bearerToken);
+            this.connectionState = 'connected';
+            this.emit('connectionStateChanged', 'connected');
+            logger.debug('[TextConnectionManager] Connected successfully');
+        }
+        catch (err) {
+            this.connectionState = 'disconnected';
+            const message = err instanceof Error ? err.message : 'Connection failed';
+            logger.error('[TextConnectionManager] Connection failed:', message);
+            throw err;
+        }
+    }
+    setupTextChatHandlers(signalR) {
+        signalR.setTextChatHandlers({
+            onStreamDelta: (delta, messageId) => {
+                this.emit('streamDelta', { delta, messageId });
+            },
+            onStreamCompleted: (fullText, messageId) => {
+                // Release the transport hold BEFORE notifying, so a controller replaying a held
+                // message from its own streamCompleted handler sends it straight through.
+                this.releaseGreetingHold();
+                this.emit('streamCompleted', { fullText, messageId });
+            },
+            onToolCall: (toolName, status, result, agentLabel) => {
+                this.emit('toolCall', { toolName, status, result, agentLabel });
+            },
+        });
+    }
+    setupPageInteractionHandler(signalR) {
+        this.pageInteractionHandler = new PageInteractionHandler(() => signalR.getConnection() ?? null);
+        if (this.pendingExternalExecutor) {
+            this.pageInteractionHandler.setExternalExecutor(this.pendingExternalExecutor);
+        }
+        if (this.pendingDocumentProvider) {
+            this.pageInteractionHandler.setDocumentProvider(this.pendingDocumentProvider.getDoc, this.pendingDocumentProvider.getWin);
+        }
+        signalR.setPageInteractionHandlers({
+            onPageInteractionRequest: (requestJson) => {
+                this.pageInteractionHandler?.handleRequest(requestJson);
+            },
+        });
+    }
+    async simulateDemoConnection() {
+        await new Promise((resolve) => setTimeout(resolve, DEMO_CONNECTION_DELAY_MS));
+        this.connectionState = 'connected';
+        this.emit('connectionStateChanged', 'connected');
+    }
+    async sendMessage(text, pageUrl, pageTitle, isGreeting = false) {
+        if (isDemoMode) {
+            return;
+        }
+        // Hold user messages until the greeting has finished streaming (mirrors voice, where the mic
+        // stays muted until the greeting audio ends). The greeting itself is never held.
+        if (!isGreeting && this.greetingActive) {
+            this.pendingSends.push({ text, pageUrl, pageTitle });
+            return;
+        }
+        await this.apiClient.sendChatMessage(text, pageUrl, pageTitle, isGreeting);
+    }
+    // The greeting is an empty message flagged as a greeting: the backend primes the LLM to speak
+    // first and its empty-message guard only lets the message through when this flag is set. Callers
+    // must use this rather than sendMessage('') so the flag can never be forgotten.
+    async sendGreeting(pageUrl, pageTitle) {
+        this.beginGreetingHold();
+        try {
+            await this.sendMessage('', pageUrl, pageTitle, true);
+        }
+        catch (err) {
+            // The greeting will never stream, so don't strand held user messages.
+            this.releaseGreetingHold();
+            throw err;
+        }
+    }
+    beginGreetingHold() {
+        this.greetingActive = true;
+        if (this.greetingHoldTimer) {
+            clearTimeout(this.greetingHoldTimer);
+        }
+        this.greetingHoldTimer = setTimeout(() => this.releaseGreetingHold(), GREETING_HOLD_TIMEOUT_MS);
+    }
+    releaseGreetingHold() {
+        if (this.greetingHoldTimer) {
+            clearTimeout(this.greetingHoldTimer);
+            this.greetingHoldTimer = null;
+        }
+        if (!this.greetingActive) {
+            return;
+        }
+        this.greetingActive = false;
+        const queued = this.pendingSends;
+        this.pendingSends = [];
+        for (const send of queued) {
+            void this.sendMessage(send.text, send.pageUrl, send.pageTitle);
+        }
+    }
+    async disconnect() {
+        this.greetingActive = false;
+        this.pendingSends = [];
+        if (this.greetingHoldTimer) {
+            clearTimeout(this.greetingHoldTimer);
+            this.greetingHoldTimer = null;
+        }
+        if (isDemoMode) {
+            this.connectionState = 'disconnected';
+            this.emit('connectionStateChanged', 'disconnected');
+            return;
+        }
+        this.signalRService?.clearTextChatHandlers();
+        this.signalRService?.clearPageInteractionHandlers();
+        await this.signalRService?.disconnect();
+        this.pageInteractionHandler = null;
+        this.connectionState = 'disconnected';
+        this.emit('connectionStateChanged', 'disconnected');
+        logger.debug('[TextConnectionManager] Disconnected');
+    }
+    setDocumentProvider(getDoc, getWin) {
+        this.pendingDocumentProvider = { getDoc, getWin };
+        this.pageInteractionHandler?.setDocumentProvider(getDoc, getWin);
+    }
+    setExternalExecutor(executor) {
+        this.pendingExternalExecutor = executor;
+        this.pageInteractionHandler?.setExternalExecutor(executor);
+    }
+    getConnectionState() {
+        return this.connectionState;
+    }
+    isConnected() {
+        return this.connectionState === 'connected';
+    }
+    dispose() {
+        this.signalRService?.disconnect();
+        this.removeAllListeners();
+    }
+}

package/dist/core/text-mode-manager.d.ts

@@ -0,0 +1,50 @@
+import type { WidgetApiClient } from '../services/api';
+import type { ConnectionState } from '../types';
+import type { DocumentProvider, WindowProvider, ExternalExecutor } from '../services/page-interaction/page-interaction-handler';
+import type { TextConnectionManager } from './text-connection-manager';
+import type { ChatManager } from './chat-manager';
+import type { ConversationPersistence } from './conversation-persistence';
+import type { NavigationManager } from './navigation-manager';
+type StateChangeCallback = () => void;
+type TextEventDeps = {
+    chatManager: ChatManager;
+    persistence: ConversationPersistence;
+    navigationManager: NavigationManager;
+    onError: () => void;
+    onStopConversation: () => Promise<void>;
+    logPrefix: string;
+};
+export declare class TextModeManager {
+    isStreaming: boolean;
+    streamContent: string;
+    agentStatus: string | null;
+    isSessionEnding: boolean;
+    private isDelegationActive;
+    private language?;
+    private connectionManager;
+    private chatManager;
+    private persistence;
+    private logPrefix;
+    private currentStreamMessageId;
+    private pendingStreamingUpdate;
+    private readonly apiClient;
+    private readonly onStateChanged;
+    private pendingExternalExecutor;
+    private readonly greetingGate;
+    constructor(apiClient: WidgetApiClient, onStateChanged: StateChangeCallback);
+    setLanguage(language?: string): void;
+    setWaitForGreeting(waitForGreeting: boolean): void;
+    ensureConnection(): Promise<TextConnectionManager>;
+    setupEventHandlers(deps: TextEventDeps): void;
+    sendMessage(text: string, pageUrl?: string, pageTitle?: string): Promise<void>;
+    requestGreeting(pageUrl?: string, pageTitle?: string): void;
+    disconnect(): Promise<void>;
+    getConnectionState(): ConnectionState;
+    setDocumentProvider(getDoc: DocumentProvider, getWin: WindowProvider): void;
+    setExternalExecutor(executor: ExternalExecutor | null): void;
+    resetStreamState(): void;
+    dispose(): void;
+    private handleStreamDelta;
+    private scheduleStreamingUpdate;
+}
+export {};