@nextpa/chat-core 0.1.0

package/dist/core/connection-retry-handler.js

@@ -0,0 +1,33 @@
+import { logger } from '../utils/logger';
+const MAX_CONNECT_ATTEMPTS = 3;
+const RETRY_DELAYS_MS = [1000, 3000];
+const FALLBACK_RETRY_DELAY_MS = 3000;
+export class ConnectionRetryHandler {
+    async retryAsync({ connectFn, cleanupFn, label, logPrefix, onMicrophoneDenied }) {
+        for (let attempt = 1; attempt <= MAX_CONNECT_ATTEMPTS; attempt++) {
+            try {
+                await connectFn();
+                return true;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (message === 'Microphone permission denied') {
+                    onMicrophoneDenied?.();
+                    return false;
+                }
+                if (attempt >= MAX_CONNECT_ATTEMPTS) {
+                    logger.error(`${logPrefix} ${label} connection failed after ${attempt} attempts: ${message}`);
+                    return false;
+                }
+                const delay = RETRY_DELAYS_MS[attempt - 1] ?? FALLBACK_RETRY_DELAY_MS;
+                logger.debug(`${logPrefix} ${label} connection attempt ${attempt}/${MAX_CONNECT_ATTEMPTS} failed: ${message}. Retrying in ${delay}ms...`);
+                try {
+                    await cleanupFn();
+                }
+                catch { /* ignore cleanup errors */ }
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        return false;
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { WidgetConfig } from '../types';
+type StateChangeCallback = () => void;
+export declare class ConsentManager {
+    private _hasConsented;
+    private _showTermsModal;
+    private readonly onStateChanged;
+    get hasConsented(): boolean;
+    get showTermsModal(): boolean;
+    constructor(onStateChanged: StateChangeCallback);
+    check(assistantId: string, showTermsAndConditions: boolean, autoAccept?: boolean): void;
+    requireConsentOrProceed(config: WidgetConfig): boolean;
+    accept(assistantId: string): void;
+    decline(): void;
+}
+export {};

package/dist/core/consent-manager.js

@@ -0,0 +1,40 @@
+import { hasUserConsented, setUserConsent } from '../utils/consent';
+import { logger } from '../utils/logger';
+export class ConsentManager {
+    _hasConsented = false;
+    _showTermsModal = false;
+    onStateChanged;
+    get hasConsented() {
+        return this._hasConsented;
+    }
+    get showTermsModal() {
+        return this._showTermsModal;
+    }
+    constructor(onStateChanged) {
+        this.onStateChanged = onStateChanged;
+    }
+    check(assistantId, showTermsAndConditions, autoAccept = false) {
+        if (!showTermsAndConditions || autoAccept) {
+            this._hasConsented = true;
+            return;
+        }
+        this._hasConsented = hasUserConsented(assistantId);
+        logger.debug('[ConsentManager] Consent status:', this._hasConsented);
+    }
+    requireConsentOrProceed(config) {
+        if (!config.showTermsAndConditions || this._hasConsented)
+            return true;
+        this._showTermsModal = true;
+        this.onStateChanged();
+        return false;
+    }
+    accept(assistantId) {
+        setUserConsent(assistantId, true);
+        this._hasConsented = true;
+        this._showTermsModal = false;
+        this.onStateChanged();
+    }
+    decline() {
+        this._showTermsModal = false;
+    }
+}

package/dist/core/conversation-persistence.d.ts

@@ -0,0 +1,23 @@
+import type { VoiceUsage } from '../types';
+import type { WidgetApiClient } from '../services/api';
+import type { ChatManager } from './chat-manager';
+export declare class ConversationPersistence {
+    private readonly apiClient;
+    private readonly logPrefix;
+    private readonly localStorage;
+    private assistantId;
+    constructor(apiClient: WidgetApiClient, logPrefix: string);
+    setAssistantId(assistantId: string): void;
+    loadHistory(chatManager: ChatManager): Promise<number>;
+    private loadFromLocalStorage;
+    private loadFromApi;
+    startNewSession(): void;
+    endSession(trimFarewell?: boolean): void;
+    persistMessage(role: string, content: string, language?: string, usage?: VoiceUsage, toolCalls?: Array<{
+        name: string;
+        durationMs: number;
+        succeeded: boolean;
+    }>, responseLatencyMs?: number, inputSource?: 'Spoken' | 'Typed'): void;
+    saveToLocalStorage(chatManager: ChatManager): void;
+    resetMemory(): Promise<void>;
+}

package/dist/core/conversation-persistence.js

@@ -0,0 +1,109 @@
+import { isDemoMode } from '../constants/defaults';
+import { logger } from '../utils/logger';
+import { LocalStoragePersistence } from './local-storage-persistence';
+export class ConversationPersistence {
+    apiClient;
+    logPrefix;
+    localStorage;
+    assistantId = null;
+    constructor(apiClient, logPrefix) {
+        this.apiClient = apiClient;
+        this.logPrefix = logPrefix;
+        this.localStorage = new LocalStoragePersistence();
+    }
+    setAssistantId(assistantId) {
+        this.assistantId = assistantId;
+    }
+    async loadHistory(chatManager) {
+        if (isDemoMode)
+            return 0;
+        const cachedCount = this.loadFromLocalStorage(chatManager);
+        if (cachedCount > 0)
+            return cachedCount;
+        return this.loadFromApi(chatManager);
+    }
+    loadFromLocalStorage(chatManager) {
+        if (!this.assistantId)
+            return 0;
+        const cached = this.localStorage.load(this.assistantId);
+        for (const msg of cached) {
+            const added = msg.role === 'user'
+                ? chatManager.addUserMessage(msg.content, msg.id)
+                : chatManager.addAssistantMessage(msg.content, msg.id);
+            if (msg.feedback != null) {
+                chatManager.setFeedback(added.id, msg.feedback);
+            }
+        }
+        if (cached.length > 0) {
+            logger.debug(`${this.logPrefix} Loaded ${cached.length} messages from localStorage`);
+        }
+        return cached.length;
+    }
+    async loadFromApi(chatManager) {
+        try {
+            const entries = await this.apiClient.getConversationHistory();
+            for (const entry of entries) {
+                const isUser = entry.role.toLowerCase() === 'user';
+                const msg = isUser
+                    ? chatManager.addUserMessage(entry.content, entry.id)
+                    : chatManager.addAssistantMessage(entry.content, entry.id);
+                if (entry.feedback?.rating != null) {
+                    chatManager.setFeedback(msg.id, entry.feedback.rating);
+                }
+            }
+            if (entries.length > 0) {
+                logger.debug(`${this.logPrefix} Loaded`, entries.length, 'entries from API');
+                this.saveToLocalStorage(chatManager);
+            }
+            return entries.length;
+        }
+        catch (err) {
+            logger.debug(`${this.logPrefix} Failed to load conversation history:`, err);
+            return 0;
+        }
+    }
+    startNewSession() {
+        if (isDemoMode)
+            return;
+        this.apiClient.startSession().catch((err) => {
+            logger.debug(`${this.logPrefix} Failed to start new session:`, err);
+        });
+    }
+    endSession(trimFarewell = false) {
+        if (isDemoMode)
+            return;
+        // Do NOT clear localStorage — keep messages for next visit
+        this.apiClient.endConversationSession(undefined, trimFarewell).catch((err) => {
+            logger.debug(`${this.logPrefix} Failed to end conversation session:`, err);
+        });
+    }
+    persistMessage(role, content, language, usage, toolCalls, responseLatencyMs, inputSource) {
+        if (isDemoMode)
+            return;
+        this.apiClient.addConversationMessage({ role, content, language, usage, toolCalls, responseLatencyMs, inputSource }).catch((err) => {
+            logger.debug(`${this.logPrefix} Failed to persist message:`, err);
+        });
+    }
+    saveToLocalStorage(chatManager) {
+        if (!this.assistantId)
+            return;
+        this.localStorage.save(this.assistantId, chatManager.getMessages());
+    }
+    async resetMemory() {
+        if (isDemoMode)
+            return;
+        if (this.assistantId) {
+            this.localStorage.clear(this.assistantId);
+        }
+        try {
+            await this.apiClient.resetConversation();
+            logger.debug(`${this.logPrefix} Conversation memory cleared`);
+        }
+        catch (err) {
+            logger.debug(`${this.logPrefix} Failed to reset conversation:`, err);
+        }
+        // Start the next conversation under a fresh clientId so an in-flight write from the previous
+        // turn (processed asynchronously) can't resurrect the just-cleared memory under the same id.
+        this.apiClient.rotateClientId();
+    }
+}

package/dist/core/event-emitter.d.ts

@@ -0,0 +1,7 @@
+export declare class EventEmitter<TEvents = Record<string, (...args: any[]) => void>> {
+    private readonly listeners;
+    on<K extends keyof TEvents>(event: K, callback: TEvents[K]): () => void;
+    off<K extends keyof TEvents>(event: K, callback: TEvents[K]): void;
+    protected emit<K extends keyof TEvents>(event: K, ...args: TEvents[K] extends (...args: infer P) => void ? P : never): void;
+    removeAllListeners(): void;
+}

package/dist/core/event-emitter.js

@@ -0,0 +1,27 @@
+import { logger } from '../utils/logger';
+export class EventEmitter {
+    listeners = new Map();
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(callback);
+        return () => this.off(event, callback);
+    }
+    off(event, callback) {
+        this.listeners.get(event)?.delete(callback);
+    }
+    emit(event, ...args) {
+        this.listeners.get(event)?.forEach((callback) => {
+            try {
+                callback(...args);
+            }
+            catch (err) {
+                logger.error(`Error in event handler for ${String(event)}:`, err);
+            }
+        });
+    }
+    removeAllListeners() {
+        this.listeners.clear();
+    }
+}

package/dist/core/greeting-gate.d.ts

@@ -0,0 +1,16 @@
+export declare class GreetingGate {
+    private readonly replay;
+    waitForGreeting: boolean;
+    private greetingInFlight;
+    private held;
+    private timer;
+    /** `replay` re-runs a held message through the normal send path once the greeting is done. */
+    constructor(replay: (text: string) => void);
+    beginGreeting(): void;
+    /** True while a user message must be fully withheld (neither displayed nor sent yet). */
+    shouldHold(): boolean;
+    enqueue(text: string): void;
+    /** Call when the greeting finishes (or on the safety timeout): replays every withheld message. */
+    release(): void;
+    reset(): void;
+}

package/dist/core/greeting-gate.js

@@ -0,0 +1,53 @@
+// Holds the first user message — both its display and its send — until the greeting has finished
+// streaming, so the greeting always lands before the user's first turn (mirrors voice, where the
+// mic stays muted until the greeting audio ends). Opt out with waitForGreeting = false. Shared by
+// the text-only controller and the combined controller so both greeting paths behave identically.
+const GREETING_HOLD_TIMEOUT_MS = 15_000;
+export class GreetingGate {
+    replay;
+    waitForGreeting = true;
+    greetingInFlight = false;
+    held = [];
+    timer = null;
+    /** `replay` re-runs a held message through the normal send path once the greeting is done. */
+    constructor(replay) {
+        this.replay = replay;
+    }
+    beginGreeting() {
+        this.greetingInFlight = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+        }
+        this.timer = setTimeout(() => this.release(), GREETING_HOLD_TIMEOUT_MS);
+    }
+    /** True while a user message must be fully withheld (neither displayed nor sent yet). */
+    shouldHold() {
+        return this.waitForGreeting && this.greetingInFlight;
+    }
+    enqueue(text) {
+        this.held.push(text);
+    }
+    /** Call when the greeting finishes (or on the safety timeout): replays every withheld message. */
+    release() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (!this.greetingInFlight) {
+            return;
+        }
+        this.greetingInFlight = false;
+        const queued = this.held.splice(0);
+        for (const text of queued) {
+            this.replay(text);
+        }
+    }
+    reset() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.greetingInFlight = false;
+        this.held = [];
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,9 @@
+export { WidgetController } from './widget-controller';
+export { TextWidgetController } from './text-widget-controller';
+export { ConfigManager } from './config-manager';
+export { ChatManager } from './chat-manager';
+export { ConnectionManager } from './connection-manager';
+export { TextConnectionManager } from './text-connection-manager';
+export { EventEmitter } from './event-emitter';
+export type { WidgetState, WidgetControllerOptions, WidgetEvents } from './types';
+export type { TextWidgetState } from './text-types';

package/dist/core/index.js

@@ -0,0 +1,7 @@
+export { WidgetController } from './widget-controller';
+export { TextWidgetController } from './text-widget-controller';
+export { ConfigManager } from './config-manager';
+export { ChatManager } from './chat-manager';
+export { ConnectionManager } from './connection-manager';
+export { TextConnectionManager } from './text-connection-manager';
+export { EventEmitter } from './event-emitter';

package/dist/core/link-target.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Decides whether a link clicked through the widget should open in the same
+ * tab (`_self`) or a new tab (`_blank`).
+ *
+ * Rule:
+ *   - Same domain as the host page → `_self`. `www.` is treated as same domain.
+ *     Port and protocol differences are ignored — the user-perceived "domain"
+ *     is the host without `www.`.
+ *   - Different domain or sub-domain → `_blank`.
+ *   - Non-http(s) URLs (`mailto:`, `tel:`, relative paths, anchors) → `_self`,
+ *     because the browser invokes a native handler (mail client, dialer) or
+ *     stays on the page; the current tab content is not lost.
+ *   - Unparseable input → `_blank` (safer default).
+ */
+export declare function resolveSameOriginTarget(url: string | null | undefined, pageHost: string | null | undefined): '_self' | '_blank';

package/dist/core/link-target.js

@@ -0,0 +1,64 @@
+/**
+ * Decides whether a link clicked through the widget should open in the same
+ * tab (`_self`) or a new tab (`_blank`).
+ *
+ * Rule:
+ *   - Same domain as the host page → `_self`. `www.` is treated as same domain.
+ *     Port and protocol differences are ignored — the user-perceived "domain"
+ *     is the host without `www.`.
+ *   - Different domain or sub-domain → `_blank`.
+ *   - Non-http(s) URLs (`mailto:`, `tel:`, relative paths, anchors) → `_self`,
+ *     because the browser invokes a native handler (mail client, dialer) or
+ *     stays on the page; the current tab content is not lost.
+ *   - Unparseable input → `_blank` (safer default).
+ */
+export function resolveSameOriginTarget(url, pageHost) {
+    if (!url)
+        return '_blank';
+    const trimmed = url.trim();
+    if (trimmed.length === 0)
+        return '_blank';
+    if (isNonHttpScheme(trimmed) || isRelativeOrAnchor(trimmed)) {
+        return '_self';
+    }
+    const linkHost = extractHostname(trimmed);
+    if (linkHost === null)
+        return '_blank';
+    const normalizedLink = stripWww(linkHost);
+    const normalizedPage = stripWww(stripPort(pageHost ?? ''));
+    if (normalizedPage.length === 0)
+        return '_blank';
+    return normalizedLink === normalizedPage ? '_self' : '_blank';
+}
+function isNonHttpScheme(url) {
+    const lower = url.toLowerCase();
+    return lower.startsWith('mailto:')
+        || lower.startsWith('tel:')
+        || lower.startsWith('sms:')
+        || lower.startsWith('geo:')
+        || lower.startsWith('callto:');
+}
+function isRelativeOrAnchor(url) {
+    if (url.startsWith('#') || url.startsWith('?'))
+        return true;
+    if (url.startsWith('//'))
+        return false;
+    return !/^[a-z][a-z0-9+.-]*:/i.test(url);
+}
+function extractHostname(url) {
+    try {
+        const absolute = url.startsWith('//') ? `https:${url}` : url;
+        return new URL(absolute).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function stripWww(host) {
+    const lower = host.toLowerCase();
+    return lower.startsWith('www.') ? lower.slice(4) : lower;
+}
+function stripPort(host) {
+    const colonIndex = host.indexOf(':');
+    return colonIndex === -1 ? host : host.slice(0, colonIndex);
+}

package/dist/core/local-storage-persistence.d.ts

@@ -0,0 +1,11 @@
+import type { ChatMessage } from '../types';
+export declare class LocalStoragePersistence {
+    private readonly available;
+    private readonly ttlMs;
+    constructor(ttlHours?: number);
+    save(assistantId: string, messages: ChatMessage[]): void;
+    load(assistantId: string): ChatMessage[];
+    clear(assistantId: string): void;
+    private cleanupExpired;
+    private getKey;
+}

package/dist/core/local-storage-persistence.js

@@ -0,0 +1,111 @@
+import { logger } from '../utils/logger';
+const LOG_PREFIX = '[LocalStoragePersistence]';
+const KEY_PREFIX = 'nextpa_widget_conv_';
+const DEFAULT_TTL_HOURS = 4;
+function isLocalStorageAvailable() {
+    try {
+        const testKey = '__nextpa_test__';
+        localStorage.setItem(testKey, '1');
+        localStorage.removeItem(testKey);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export class LocalStoragePersistence {
+    available;
+    ttlMs;
+    constructor(ttlHours = DEFAULT_TTL_HOURS) {
+        this.available = isLocalStorageAvailable();
+        this.ttlMs = ttlHours * 60 * 60 * 1000;
+        if (this.available) {
+            this.cleanupExpired();
+        }
+    }
+    save(assistantId, messages) {
+        if (!this.available || messages.length === 0)
+            return;
+        try {
+            const key = this.getKey(assistantId);
+            const data = {
+                messages: messages.map(m => ({
+                    ...m,
+                    timestamp: m.timestamp instanceof Date ? m.timestamp : new Date(m.timestamp),
+                })),
+                expiresAt: Date.now() + this.ttlMs,
+            };
+            localStorage.setItem(key, JSON.stringify(data));
+        }
+        catch (err) {
+            logger.debug(`${LOG_PREFIX} Failed to save:`, err);
+        }
+    }
+    load(assistantId) {
+        if (!this.available)
+            return [];
+        try {
+            const key = this.getKey(assistantId);
+            const raw = localStorage.getItem(key);
+            if (!raw)
+                return [];
+            const data = JSON.parse(raw);
+            if (Date.now() > data.expiresAt) {
+                localStorage.removeItem(key);
+                return [];
+            }
+            return data.messages.map(m => ({
+                ...m,
+                timestamp: new Date(m.timestamp),
+            }));
+        }
+        catch (err) {
+            logger.debug(`${LOG_PREFIX} Failed to load:`, err);
+            return [];
+        }
+    }
+    clear(assistantId) {
+        if (!this.available)
+            return;
+        try {
+            localStorage.removeItem(this.getKey(assistantId));
+        }
+        catch {
+            // Ignore
+        }
+    }
+    cleanupExpired() {
+        try {
+            const keysToRemove = [];
+            for (let i = 0; i < localStorage.length; i++) {
+                const key = localStorage.key(i);
+                if (!key?.startsWith(KEY_PREFIX))
+                    continue;
+                const raw = localStorage.getItem(key);
+                if (!raw)
+                    continue;
+                try {
+                    const data = JSON.parse(raw);
+                    if (Date.now() > data.expiresAt) {
+                        keysToRemove.push(key);
+                    }
+                }
+                catch {
+                    keysToRemove.push(key);
+                }
+            }
+            for (const key of keysToRemove) {
+                localStorage.removeItem(key);
+            }
+            if (keysToRemove.length > 0) {
+                logger.debug(`${LOG_PREFIX} Cleaned up ${keysToRemove.length} expired entries`);
+            }
+        }
+        catch {
+            // Ignore
+        }
+    }
+    getKey(assistantId) {
+        return `${KEY_PREFIX}${assistantId}`;
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { DocumentProvider, WindowProvider } from '../services/page-interaction/page-interaction-handler';
+type StateChangeCallback = () => void;
+type DocumentProviderCallback = (getDoc: DocumentProvider, getWin: WindowProvider) => void;
+export declare class NavigationManager {
+    private _blockedUrl;
+    private readonly iframeNavManager;
+    private readonly onStateChanged;
+    private readonly onDocumentProviderChanged;
+    private readonly getPageHost;
+    get blockedUrl(): string | null;
+    constructor(onStateChanged: StateChangeCallback, onDocumentProviderChanged: DocumentProviderCallback, getPageHost: () => string | null);
+    private resolveTargetForUrl;
+    checkForReconnect(): boolean;
+    openUrl(url: string): void;
+    dismissBlockedUrl(): void;
+    openBlockedUrl(): void;
+    dispose(): void;
+    private navigateSameTab;
+    private navigateViaIframeWithFallback;
+    private openInNewTab;
+    private showBlockedUrl;
+    private saveStateForReconnect;
+}
+export {};