@astermind/cybernetic-chatbot-client 2.2.36 → 2.2.48

package/dist/cybernetic-chatbot-client-full.umd.js

@@ -7,13 +7,14 @@
     // src/ApiClient.ts
     // HTTP client for AsterMind backend API
     /**
-     * Map backend source format to client Source interface
+     * Map backend source format to client Source interface.
+     * Handles both canonical (title/score) and legacy (heading/no-score) field names.
      */
     function mapSource(raw) {
         return {
-            title: raw.title,
-            snippet: raw.content,
-            relevance: raw.score,
+            title: raw.title || raw.heading || 'Document',
+            snippet: raw.content || '',
+            relevance: raw.score ?? 0,
             documentId: raw.documentId,
             fullContent: raw.fullContent,
             downloadUrl: raw.downloadUrl,
@@ -51,9 +52,10 @@
                 throw new Error(error.message || `HTTP ${response.status}: ${response.statusText}`);
             }
             const data = await response.json();
-            // Map backend source format to client Source interface
+            // Normalize response: accept both 'reply' (canonical) and 'answer' (legacy)
             return {
                 ...data,
+                reply: data.reply || data.answer || '',
                 sources: (data.sources || []).map(mapSource)
             };
         }
@@ -129,7 +131,8 @@
             }
         }
         /**
-         * Get general documents for caching
+         * Get general documents for caching.
+         * Normalizes field names from both canonical (title) and legacy (name) formats.
          */
         async getGeneralDocs(since) {
             const params = new URLSearchParams();
@@ -146,10 +149,16 @@
                 throw new Error(`HTTP ${response.status}`);
             }
             const data = await response.json();
-            return data.documents;
+            // Normalize: accept both 'title' (canonical) and 'name' (legacy on-prem)
+            return (data.documents || []).map((doc) => ({
+                id: doc.id,
+                title: doc.title || doc.name || 'Untitled',
+                updatedAt: doc.updatedAt || doc.updated_at || new Date().toISOString(),
+            }));
         }
         /**
-         * Get API status, quota, and system settings
+         * Get API status, quota, and system settings.
+         * Normalizes response from both canonical and legacy backend formats.
          */
         async getStatus() {
             const response = await fetch(`${this.baseUrl}/api/external/status`, {
@@ -160,7 +169,38 @@
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
             }
-            return response.json();
+            const data = await response.json();
+            // Normalize: accept both canonical (apiKey) and legacy (key) structures
+            const apiKeyData = data.apiKey || data.key || {};
+            const scopes = apiKeyData.scopes || apiKeyData.permissions || ['chat'];
+            // Normalize quota: accept both canonical (perMinute/perDay) and legacy structures
+            const quota = data.quota || {};
+            const perMinute = quota.perMinute || {
+                limit: apiKeyData.rateLimit?.limit || quota.rateLimitPerMinute || 30,
+                remaining: apiKeyData.rateLimit?.remaining ?? quota.rateLimitPerMinute ?? 30,
+            };
+            const perDay = quota.perDay || {
+                limit: quota.rateLimitPerDay || perMinute.limit * 60 * 24,
+                remaining: quota.rateLimitPerDay || perMinute.limit * 60 * 24,
+            };
+            // Normalize systemSettings: accept both canonical and legacy (system) structures
+            const settings = data.systemSettings || data.system || {};
+            const cacheRetentionHours = settings.cacheRetentionHours ??
+                (settings.cacheRetentionDays ? settings.cacheRetentionDays * 24 : undefined);
+            return {
+                status: data.status || 'active',
+                apiKey: {
+                    id: apiKeyData.id || '',
+                    scopes,
+                },
+                quota: { perMinute, perDay },
+                systemSettings: {
+                    cacheRetentionHours: cacheRetentionHours ?? 720,
+                    maintenanceMode: settings.maintenanceMode ?? false,
+                    maintenanceMessage: settings.maintenanceMessage,
+                    forceOfflineClients: settings.forceOfflineClients ?? false,
+                },
+            };
         }
         /**
          * Health check (no auth required)
@@ -1016,6 +1056,595 @@
         }
     }
 
+    // src/WebSocketTransport.ts
+    // WebSocket transport for streaming chat via SaaS WebSocket API (chatws.astermind.ai)
+    /**
+     * WebSocket transport for streaming chat.
+     *
+     * Maps the chat-handler Lambda WebSocket protocol to the client's StreamCallbacks:
+     *   Server typing  → ignored (UI has its own indicator)
+     *   Server chunk   → onToken(content)
+     *   Server done    → onSources(sources) + onComplete(response)
+     *   Server error   → onError(error)
+     *
+     * Connection is lazy — established on the first chatStream() call.
+     * Reuses the same connection across multiple messages.
+     * Reconnects with exponential backoff on close/error.
+     */
+    class WebSocketTransport {
+        constructor(wsUrl, apiKey, options) {
+            this.ws = null;
+            this.state = 'disconnected';
+            this.reconnectAttempts = 0;
+            this.connectionPromise = null;
+            // Active streaming request tracking
+            this.activeCallbacks = null;
+            this.activeFullText = '';
+            // Cleanup handler reference
+            this.beforeUnloadHandler = null;
+            // Promise callbacks for the active stream
+            this._resolveStream = null;
+            this._rejectStream = null;
+            this.wsUrl = wsUrl;
+            this.apiKey = apiKey;
+            this.maxReconnectAttempts = options?.maxReconnectAttempts ?? 3;
+            this.reconnectDelay = options?.reconnectDelay ?? 1000;
+            this.connectionTimeout = options?.connectionTimeout ?? 10000;
+        }
+        /**
+         * Current transport state
+         */
+        getState() {
+            return this.state;
+        }
+        /**
+         * Whether the WebSocket is currently connected
+         */
+        isConnected() {
+            return this.state === 'connected' && this.ws?.readyState === WebSocket.OPEN;
+        }
+        /**
+         * Connect to the WebSocket endpoint.
+         * Appends the API key as a query parameter for authentication.
+         * Returns a promise that resolves when the connection is open.
+         */
+        connect() {
+            // Already connected
+            if (this.isConnected()) {
+                return Promise.resolve();
+            }
+            // Connection already in progress
+            if (this.connectionPromise) {
+                return this.connectionPromise;
+            }
+            this.state = 'connecting';
+            this.connectionPromise = new Promise((resolve, reject) => {
+                try {
+                    // Build URL with API key
+                    const separator = this.wsUrl.includes('?') ? '&' : '?';
+                    const fullUrl = `${this.wsUrl}${separator}apiKey=${encodeURIComponent(this.apiKey)}`;
+                    const ws = new WebSocket(fullUrl);
+                    this.ws = ws;
+                    // Connection timeout
+                    const timeout = setTimeout(() => {
+                        if (ws.readyState !== WebSocket.OPEN) {
+                            ws.close();
+                            this.state = 'error';
+                            this.connectionPromise = null;
+                            reject(new Error('WebSocket connection timed out'));
+                        }
+                    }, this.connectionTimeout);
+                    ws.onopen = () => {
+                        clearTimeout(timeout);
+                        this.state = 'connected';
+                        this.reconnectAttempts = 0;
+                        this.connectionPromise = null;
+                        this.registerCleanup();
+                        resolve();
+                    };
+                    ws.onmessage = (event) => {
+                        this.handleMessage(event);
+                    };
+                    ws.onerror = () => {
+                        clearTimeout(timeout);
+                        this.state = 'error';
+                        this.connectionPromise = null;
+                        // The close event fires after error, which will trigger reconnect
+                    };
+                    ws.onclose = (event) => {
+                        clearTimeout(timeout);
+                        const wasConnected = this.state === 'connected';
+                        this.state = 'disconnected';
+                        this.connectionPromise = null;
+                        this.unregisterCleanup();
+                        // If we had an active request, report the error
+                        if (this.activeCallbacks) {
+                            this.activeCallbacks.onError?.({
+                                code: 'WS_ERROR',
+                                message: event.reason || `WebSocket closed (code: ${event.code})`
+                            });
+                            this.clearActiveRequest();
+                        }
+                        // Reject if we were trying to connect
+                        if (!wasConnected) {
+                            reject(new Error(event.reason || `WebSocket closed (code: ${event.code})`));
+                        }
+                    };
+                }
+                catch (error) {
+                    this.state = 'error';
+                    this.connectionPromise = null;
+                    reject(error);
+                }
+            });
+            return this.connectionPromise;
+        }
+        /**
+         * Stream a chat message over WebSocket.
+         *
+         * Sends: { type: "sendMessage", message, sessionId?, wordLimit?, context? }
+         * Receives: typing → chunk × N → done (with sources and metadata)
+         */
+        async chatStream(message, options) {
+            const { sessionId, context, wordLimit, onToken, onSources, onComplete, onError } = options;
+            // Ensure connection is established (lazy connect)
+            try {
+                await this.connect();
+            }
+            catch (error) {
+                onError?.({
+                    code: 'WS_ERROR',
+                    message: `Failed to connect: ${error instanceof Error ? error.message : String(error)}`
+                });
+                throw error;
+            }
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+                const err = { code: 'WS_ERROR', message: 'WebSocket not connected' };
+                onError?.(err);
+                throw new Error(err.message);
+            }
+            // Set up active request tracking
+            this.activeCallbacks = { onToken, onSources, onComplete, onError };
+            this.activeFullText = '';
+            this.activeSessionId = sessionId;
+            // Build and send the message
+            const payload = {
+                type: 'sendMessage',
+                message,
+            };
+            if (sessionId)
+                payload.sessionId = sessionId;
+            if (wordLimit)
+                payload.wordLimit = wordLimit;
+            if (context)
+                payload.context = context;
+            // Return a promise that resolves when done/error is received
+            return new Promise((resolve, reject) => {
+                // Store resolve/reject so handleMessage can call them
+                this._resolveStream = resolve;
+                this._rejectStream = reject;
+                this.ws.send(JSON.stringify(payload));
+            });
+        }
+        /**
+         * Disconnect and clean up the WebSocket connection
+         */
+        disconnect() {
+            this.unregisterCleanup();
+            if (this.ws) {
+                // Remove handlers to avoid triggering reconnect
+                this.ws.onclose = null;
+                this.ws.onerror = null;
+                this.ws.onmessage = null;
+                this.ws.close();
+                this.ws = null;
+            }
+            this.state = 'disconnected';
+            this.connectionPromise = null;
+            this.clearActiveRequest();
+        }
+        /**
+         * Attempt reconnection with exponential backoff.
+         * Used internally after connection loss.
+         */
+        async reconnect() {
+            if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+                this.state = 'error';
+                throw new Error(`Max reconnection attempts (${this.maxReconnectAttempts}) exceeded`);
+            }
+            const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts);
+            this.reconnectAttempts++;
+            console.log(`[Cybernetic WS] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+            // Ensure old connection is cleaned up
+            if (this.ws) {
+                this.ws.onclose = null;
+                this.ws.onerror = null;
+                this.ws.close();
+                this.ws = null;
+            }
+            return this.connect();
+        }
+        // ==================== INTERNAL ====================
+        /**
+         * Handle incoming WebSocket messages from the chat-handler Lambda.
+         *
+         * Protocol:
+         *   { type: 'typing', status: boolean }    → ignored
+         *   { type: 'chunk', content: string }      → onToken(content)
+         *   { type: 'done', sessionId, sources, metadata, messageId } → onSources + onComplete
+         *   { type: 'error', error: string }        → onError
+         */
+        handleMessage(event) {
+            if (!this.activeCallbacks)
+                return;
+            try {
+                const data = JSON.parse(event.data);
+                switch (data.type) {
+                    case 'typing':
+                        // Ignored — the chatbot-template manages its own typing indicator
+                        break;
+                    case 'chunk':
+                        if (data.content) {
+                            this.activeFullText += data.content;
+                            this.activeCallbacks.onToken?.(data.content);
+                        }
+                        break;
+                    case 'done': {
+                        // Map sources from chat-handler format to client Source format
+                        const sources = this.mapSources(data.sources || []);
+                        // Emit sources
+                        this.activeCallbacks.onSources?.(sources);
+                        // Build complete response
+                        const response = {
+                            reply: this.activeFullText,
+                            confidence: 'high',
+                            sources,
+                            offline: false,
+                            sessionId: data.sessionId || this.activeSessionId,
+                        };
+                        this.activeCallbacks.onComplete?.(response);
+                        this._resolveStream?.();
+                        this.clearActiveRequest();
+                        break;
+                    }
+                    case 'error': {
+                        const err = {
+                            code: 'WS_ERROR',
+                            message: data.error || 'Unknown WebSocket error'
+                        };
+                        this.activeCallbacks.onError?.(err);
+                        this._rejectStream?.(new Error(err.message));
+                        this.clearActiveRequest();
+                        break;
+                    }
+                    default:
+                        // Unknown message type — log and ignore
+                        console.warn('[Cybernetic WS] Unknown message type:', data.type);
+                        break;
+                }
+            }
+            catch (error) {
+                console.error('[Cybernetic WS] Failed to parse message:', error, event.data);
+            }
+        }
+        /**
+         * Map sources from the chat-handler WebSocket format to the client Source interface.
+         *
+         * Chat-handler sends: { heading, content, score, documentId, documentName }
+         * Client expects:      { title, snippet, relevance, documentId, documentName }
+         */
+        mapSources(wsSources) {
+            if (!Array.isArray(wsSources))
+                return [];
+            return wsSources.map((s) => ({
+                title: s.title || s.heading || s.documentName || 'Document',
+                snippet: s.content || '',
+                relevance: s.score ?? 0,
+                documentId: s.documentId,
+                documentName: s.documentName,
+                sourceType: s.sourceType || 'document',
+                chunkId: s.chunkId,
+            }));
+        }
+        /**
+         * Clear active request state after completion or error
+         */
+        clearActiveRequest() {
+            this.activeCallbacks = null;
+            this.activeFullText = '';
+            this._resolveStream = null;
+            this._rejectStream = null;
+        }
+        /**
+         * Register a beforeunload handler to close the WebSocket on page unload
+         */
+        registerCleanup() {
+            if (typeof window !== 'undefined' && !this.beforeUnloadHandler) {
+                this.beforeUnloadHandler = () => this.disconnect();
+                window.addEventListener('beforeunload', this.beforeUnloadHandler);
+            }
+        }
+        /**
+         * Remove the beforeunload handler
+         */
+        unregisterCleanup() {
+            if (typeof window !== 'undefined' && this.beforeUnloadHandler) {
+                window.removeEventListener('beforeunload', this.beforeUnloadHandler);
+                this.beforeUnloadHandler = null;
+            }
+        }
+    }
+
+    // src/config.ts
+    // Configuration loading and validation
+    /** Default API URL when not specified */
+    const DEFAULT_API_URL = 'https://api.astermind.ai';
+    /**
+     * Derive WebSocket URL from API URL for known SaaS domains.
+     * Maps REST API domains to their WebSocket counterparts:
+     *   chatapi.astermind.ai     → wss://chatws.astermind.ai
+     *   chatapi-dev.astermind.ai → wss://chatws-dev.astermind.ai
+     *   api.astermind.ai         → wss://chatws.astermind.ai
+     *
+     * Returns undefined for non-SaaS (on-prem) URLs.
+     */
+    function deriveWsUrl(apiUrl) {
+        try {
+            const url = new URL(apiUrl);
+            // chatapi[-env].astermind.ai → chatws[-env].astermind.ai
+            const match = url.hostname.match(/^chatapi(-[\w]+)?\.astermind\.ai$/);
+            if (match) {
+                const envSuffix = match[1] || '';
+                return `wss://chatws${envSuffix}.astermind.ai`;
+            }
+            // api.astermind.ai → chatws.astermind.ai (default SaaS)
+            if (url.hostname === 'api.astermind.ai') {
+                return 'wss://chatws.astermind.ai';
+            }
+        }
+        catch {
+            // Invalid URL, no WS derivation
+        }
+        return undefined;
+    }
+    /**
+     * Try to load wsUrl from environment or globals.
+     * Returns the first found wsUrl or undefined.
+     */
+    function loadWsUrl() {
+        // Vite env var
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const importMeta = globalThis.import?.meta?.env;
+            if (importMeta?.VITE_ASTERMIND_RAG_WS_URL) {
+                return importMeta.VITE_ASTERMIND_RAG_WS_URL;
+            }
+        }
+        catch { /* not available */ }
+        // Node.js / CRA env var
+        if (typeof process !== 'undefined' && process.env) {
+            if (process.env.ASTERMIND_RAG_WS_URL)
+                return process.env.ASTERMIND_RAG_WS_URL;
+            if (process.env.REACT_APP_ASTERMIND_RAG_WS_URL)
+                return process.env.REACT_APP_ASTERMIND_RAG_WS_URL;
+        }
+        // SSR-injected config
+        if (typeof window !== 'undefined') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const injected = window.__ASTERMIND_CONFIG__;
+            if (injected?.wsUrl)
+                return injected.wsUrl;
+            // Global config object
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const globalConfig = window.astermindConfig;
+            if (globalConfig?.wsUrl)
+                return globalConfig.wsUrl;
+        }
+        // Script data attribute
+        if (typeof document !== 'undefined') {
+            const script = document.querySelector('script[data-astermind-ws-url]');
+            if (script) {
+                const wsUrl = script.getAttribute('data-astermind-ws-url');
+                if (wsUrl)
+                    return wsUrl;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolve the WebSocket URL for a given config.
+     * Priority: explicit wsUrl → env var → auto-derived from apiUrl
+     */
+    function resolveWsUrl(config) {
+        // Explicit wsUrl takes priority
+        if (config.wsUrl)
+            return config.wsUrl;
+        // Don't auto-detect if transport is forced to REST
+        if (config.transport === 'rest')
+            return undefined;
+        // Try environment / globals
+        const envWsUrl = loadWsUrl();
+        if (envWsUrl)
+            return envWsUrl;
+        // Auto-derive from apiUrl for known SaaS domains
+        return deriveWsUrl(config.apiUrl);
+    }
+    /**
+     * Validate configuration
+     */
+    function validateConfig(config) {
+        if (!config || typeof config !== 'object') {
+            throw new Error('Config must be an object');
+        }
+        const c = config;
+        if (!c.apiUrl || typeof c.apiUrl !== 'string') {
+            throw new Error('apiUrl is required and must be a string');
+        }
+        if (!c.apiKey || typeof c.apiKey !== 'string') {
+            throw new Error('apiKey is required and must be a string');
+        }
+        if (!c.apiKey.startsWith('am_')) {
+            throw new Error('apiKey must start with "am_"');
+        }
+        return true;
+    }
+    /**
+     * Load config from Node.js process.env (for bundlers that replace process.env)
+     */
+    function loadFromProcessEnv() {
+        // Check if process.env exists (Node.js or bundler-injected)
+        if (typeof process === 'undefined' || !process.env) {
+            return null;
+        }
+        // Check for ASTERMIND_RAG_* env vars (non-prefixed, for Node.js/server environments)
+        const apiKey = process.env.ASTERMIND_RAG_API_KEY;
+        const apiUrl = process.env.ASTERMIND_RAG_API_SERVER_URL;
+        if (apiKey) {
+            return {
+                apiKey,
+                apiUrl: apiUrl || DEFAULT_API_URL,
+                _source: 'env'
+            };
+        }
+        // Check for CRA-style REACT_APP_* env vars
+        const craApiKey = process.env.REACT_APP_ASTERMIND_RAG_API_KEY;
+        const craApiUrl = process.env.REACT_APP_ASTERMIND_RAG_API_SERVER_URL;
+        if (craApiKey) {
+            return {
+                apiKey: craApiKey,
+                apiUrl: craApiUrl || DEFAULT_API_URL,
+                _source: 'env'
+            };
+        }
+        return null;
+    }
+    /**
+     * Load config from Vite's import.meta.env (browser environment)
+     * Note: This only works at build time when Vite replaces the variables
+     */
+    function loadFromViteEnv() {
+        // Check for window.__ASTERMIND_CONFIG__ (SSR-injected config)
+        if (typeof window !== 'undefined') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const injected = window.__ASTERMIND_CONFIG__;
+            if (injected && typeof injected === 'object' && injected.apiKey) {
+                return {
+                    ...injected,
+                    apiUrl: injected.apiUrl || DEFAULT_API_URL,
+                    _source: 'vite'
+                };
+            }
+        }
+        // Check for Vite's import.meta.env (replaced at build time)
+        // Note: TypeScript doesn't know about import.meta.env, so we use a try-catch
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const importMeta = globalThis.import?.meta?.env;
+            if (importMeta) {
+                const apiKey = importMeta.VITE_ASTERMIND_RAG_API_KEY;
+                const apiUrl = importMeta.VITE_ASTERMIND_RAG_API_SERVER_URL;
+                if (apiKey) {
+                    return {
+                        apiKey,
+                        apiUrl: apiUrl || DEFAULT_API_URL,
+                        _source: 'vite'
+                    };
+                }
+            }
+        }
+        catch {
+            // import.meta not available in this environment
+        }
+        return null;
+    }
+    /**
+     * Load config from window.astermindConfig global object
+     */
+    function loadFromGlobalObject() {
+        if (typeof window === 'undefined') {
+            return null;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const globalConfig = window.astermindConfig;
+        if (globalConfig && typeof globalConfig === 'object' && globalConfig.apiKey) {
+            return {
+                ...globalConfig,
+                apiUrl: globalConfig.apiUrl || DEFAULT_API_URL,
+                _source: 'window'
+            };
+        }
+        return null;
+    }
+    /**
+     * Load config from script tag data attributes
+     */
+    function loadFromScriptAttributes() {
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            return null;
+        }
+        const script = document.querySelector('script[data-astermind-key]');
+        if (script) {
+            const apiKey = script.getAttribute('data-astermind-key');
+            if (apiKey) {
+                return {
+                    apiKey,
+                    apiUrl: script.getAttribute('data-astermind-url') || DEFAULT_API_URL,
+                    _source: 'data-attr'
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Load config using priority-based fallback chain:
+     * 1. Environment variables (process.env - for bundlers/Node.js)
+     * 2. Vite environment variables (import.meta.env or window.__ASTERMIND_CONFIG__)
+     * 3. Global object (window.astermindConfig)
+     * 4. Script data attributes (data-astermind-key, data-astermind-url)
+     *
+     * @param options - Configuration options
+     * @param options.throwOnMissingKey - If true (default), throws when no API key found. If false, returns null and logs a warning.
+     * @returns Configuration object or null if not found and throwOnMissingKey is false
+     */
+    function loadConfig(options = {}) {
+        const { throwOnMissingKey = true } = options;
+        // Priority 1: Environment variables (Node.js/bundler)
+        const envConfig = loadFromProcessEnv();
+        if (envConfig) {
+            return envConfig;
+        }
+        // Priority 2: Vite environment variables / SSR-injected config
+        const viteConfig = loadFromViteEnv();
+        if (viteConfig) {
+            return viteConfig;
+        }
+        // Priority 3: Global object (window.astermindConfig)
+        const globalConfig = loadFromGlobalObject();
+        if (globalConfig) {
+            validateConfig(globalConfig);
+            return globalConfig;
+        }
+        // Priority 4: Script data attributes
+        const scriptConfig = loadFromScriptAttributes();
+        if (scriptConfig) {
+            return scriptConfig;
+        }
+        // No config found
+        if (throwOnMissingKey) {
+            throw new Error('AsterMind API key is required. Configure using one of these methods:\n' +
+                '  1. Set VITE_ASTERMIND_RAG_API_KEY environment variable (Vite)\n' +
+                '  2. Set REACT_APP_ASTERMIND_RAG_API_KEY environment variable (CRA)\n' +
+                '  3. Set window.astermindConfig = { apiKey: "am_...", apiUrl: "..." }\n' +
+                '  4. Add data-astermind-key attribute to your script tag\n' +
+                '  5. Pass apiKey directly to createClient() or CyberneticClient constructor');
+        }
+        else {
+            console.warn('[AsterMind] No API key found. Chatbot will not function until configured.');
+            return null;
+        }
+    }
+
     // src/license/base64url.ts
     // Base64URL encoding/decoding utilities for JWT handling
     /**
@@ -1651,6 +2280,7 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
      */
     class CyberneticClient {
         constructor(config) {
+            this.wsTransport = null;
             this.status = 'connecting';
             this.lastError = null;
             // Maintenance mode tracking (ADR-200)
@@ -1665,10 +2295,15 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
             this.omegaRAG = null;
             // Track if offline warning has been shown
             this.offlineWarningShown = false;
+            // Resolve WebSocket URL (explicit → env → auto-derived from apiUrl)
+            const wsUrl = resolveWsUrl(config);
+            const transport = config.transport ?? 'auto';
             // Apply defaults
             this.config = {
                 apiUrl: config.apiUrl,
                 apiKey: config.apiKey,
+                wsUrl,
+                transport,
                 fallback: {
                     enabled: config.fallback?.enabled ?? true,
                     cacheMaxAge: config.fallback?.cacheMaxAge ?? 86400000, // 24 hours
@@ -1711,6 +2346,11 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
             }).catch(() => {
                 // License verification errors are handled internally
             });
+            // Initialize WebSocket transport if configured and not forced to REST
+            if (wsUrl && transport !== 'rest' && typeof WebSocket !== 'undefined') {
+                this.wsTransport = new WebSocketTransport(wsUrl, config.apiKey, config.websocket);
+                console.log(`[Cybernetic] WebSocket transport enabled: ${wsUrl}`);
+            }
             // Monitor connection status
             this.monitorConnection();
             // Pre-cache documents on init if enabled
@@ -2089,6 +2729,60 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
                 callbacks.onComplete?.(response);
                 return;
             }
+            // Try WebSocket transport first (if available and not forced to REST)
+            if (this.wsTransport && this.config.transport !== 'rest') {
+                try {
+                    await this.wsTransport.chatStream(message, {
+                        sessionId: options?.sessionId,
+                        context: options?.context,
+                        onToken: callbacks.onToken,
+                        onSources: callbacks.onSources,
+                        onComplete: (response) => {
+                            this.setStatus('online');
+                            // Process through license manager
+                            const processedReply = this.licenseManager.processResponse(response.reply);
+                            callbacks.onComplete?.({
+                                ...response,
+                                reply: processedReply
+                            });
+                        },
+                        onError: (error) => {
+                            // In 'auto' mode, fall back to SSE on WS error
+                            if (this.config.transport === 'auto') {
+                                console.warn('[Cybernetic] WebSocket error, falling back to SSE:', error.message);
+                                this.streamViaSSE(message, callbacks, options);
+                            }
+                            else {
+                                // 'websocket' mode — no fallback
+                                const normalizedError = this.normalizeError(error);
+                                this.config.onError(normalizedError);
+                                callbacks.onError?.(normalizedError);
+                            }
+                        }
+                    });
+                    return;
+                }
+                catch (error) {
+                    if (this.config.transport === 'websocket') {
+                        // Forced WebSocket mode — don't fall back
+                        const normalizedError = this.normalizeError(error);
+                        this.lastError = normalizedError;
+                        this.config.onError(normalizedError);
+                        callbacks.onError?.(normalizedError);
+                        return;
+                    }
+                    // 'auto' mode: fall through to SSE
+                    console.warn('[Cybernetic] WebSocket connect failed, using SSE fallback');
+                }
+            }
+            // REST+SSE path (on-prem, or fallback from WebSocket)
+            await this.streamViaSSE(message, callbacks, options);
+        }
+        /**
+         * Stream chat via REST+SSE (original transport).
+         * Used as the primary transport for on-prem, or as fallback for SaaS WebSocket failures.
+         */
+        async streamViaSSE(message, callbacks, options) {
             try {
                 await this.apiClient.chatStream(message, {
                     sessionId: options?.sessionId,
@@ -2172,6 +2866,16 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
             await this.cache.clear();
             this.localRAG.reset();
         }
+        /**
+         * Clean up all resources (WebSocket connection, caches, event listeners).
+         * Call this when the client is no longer needed to prevent memory leaks.
+         */
+        destroy() {
+            if (this.wsTransport) {
+                this.wsTransport.disconnect();
+                this.wsTransport = null;
+            }
+        }
         /**
          * Manually check if backend is reachable
          */
@@ -2482,185 +3186,6 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
         }
     }
 
-    // src/config.ts
-    // Configuration loading and validation
-    /** Default API URL when not specified */
-    const DEFAULT_API_URL = 'https://api.astermind.ai';
-    /**
-     * Validate configuration
-     */
-    function validateConfig(config) {
-        if (!config || typeof config !== 'object') {
-            throw new Error('Config must be an object');
-        }
-        const c = config;
-        if (!c.apiUrl || typeof c.apiUrl !== 'string') {
-            throw new Error('apiUrl is required and must be a string');
-        }
-        if (!c.apiKey || typeof c.apiKey !== 'string') {
-            throw new Error('apiKey is required and must be a string');
-        }
-        if (!c.apiKey.startsWith('am_')) {
-            throw new Error('apiKey must start with "am_"');
-        }
-        return true;
-    }
-    /**
-     * Load config from Node.js process.env (for bundlers that replace process.env)
-     */
-    function loadFromProcessEnv() {
-        // Check if process.env exists (Node.js or bundler-injected)
-        if (typeof process === 'undefined' || !process.env) {
-            return null;
-        }
-        // Check for ASTERMIND_RAG_* env vars (non-prefixed, for Node.js/server environments)
-        const apiKey = process.env.ASTERMIND_RAG_API_KEY;
-        const apiUrl = process.env.ASTERMIND_RAG_API_SERVER_URL;
-        if (apiKey) {
-            return {
-                apiKey,
-                apiUrl: apiUrl || DEFAULT_API_URL,
-                _source: 'env'
-            };
-        }
-        // Check for CRA-style REACT_APP_* env vars
-        const craApiKey = process.env.REACT_APP_ASTERMIND_RAG_API_KEY;
-        const craApiUrl = process.env.REACT_APP_ASTERMIND_RAG_API_SERVER_URL;
-        if (craApiKey) {
-            return {
-                apiKey: craApiKey,
-                apiUrl: craApiUrl || DEFAULT_API_URL,
-                _source: 'env'
-            };
-        }
-        return null;
-    }
-    /**
-     * Load config from Vite's import.meta.env (browser environment)
-     * Note: This only works at build time when Vite replaces the variables
-     */
-    function loadFromViteEnv() {
-        // Check for window.__ASTERMIND_CONFIG__ (SSR-injected config)
-        if (typeof window !== 'undefined') {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const injected = window.__ASTERMIND_CONFIG__;
-            if (injected && typeof injected === 'object' && injected.apiKey) {
-                return {
-                    ...injected,
-                    apiUrl: injected.apiUrl || DEFAULT_API_URL,
-                    _source: 'vite'
-                };
-            }
-        }
-        // Check for Vite's import.meta.env (replaced at build time)
-        // Note: TypeScript doesn't know about import.meta.env, so we use a try-catch
-        try {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const importMeta = globalThis.import?.meta?.env;
-            if (importMeta) {
-                const apiKey = importMeta.VITE_ASTERMIND_RAG_API_KEY;
-                const apiUrl = importMeta.VITE_ASTERMIND_RAG_API_SERVER_URL;
-                if (apiKey) {
-                    return {
-                        apiKey,
-                        apiUrl: apiUrl || DEFAULT_API_URL,
-                        _source: 'vite'
-                    };
-                }
-            }
-        }
-        catch {
-            // import.meta not available in this environment
-        }
-        return null;
-    }
-    /**
-     * Load config from window.astermindConfig global object
-     */
-    function loadFromGlobalObject() {
-        if (typeof window === 'undefined') {
-            return null;
-        }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const globalConfig = window.astermindConfig;
-        if (globalConfig && typeof globalConfig === 'object' && globalConfig.apiKey) {
-            return {
-                ...globalConfig,
-                apiUrl: globalConfig.apiUrl || DEFAULT_API_URL,
-                _source: 'window'
-            };
-        }
-        return null;
-    }
-    /**
-     * Load config from script tag data attributes
-     */
-    function loadFromScriptAttributes() {
-        if (typeof window === 'undefined' || typeof document === 'undefined') {
-            return null;
-        }
-        const script = document.querySelector('script[data-astermind-key]');
-        if (script) {
-            const apiKey = script.getAttribute('data-astermind-key');
-            if (apiKey) {
-                return {
-                    apiKey,
-                    apiUrl: script.getAttribute('data-astermind-url') || DEFAULT_API_URL,
-                    _source: 'data-attr'
-                };
-            }
-        }
-        return null;
-    }
-    /**
-     * Load config using priority-based fallback chain:
-     * 1. Environment variables (process.env - for bundlers/Node.js)
-     * 2. Vite environment variables (import.meta.env or window.__ASTERMIND_CONFIG__)
-     * 3. Global object (window.astermindConfig)
-     * 4. Script data attributes (data-astermind-key, data-astermind-url)
-     *
-     * @param options - Configuration options
-     * @param options.throwOnMissingKey - If true (default), throws when no API key found. If false, returns null and logs a warning.
-     * @returns Configuration object or null if not found and throwOnMissingKey is false
-     */
-    function loadConfig(options = {}) {
-        const { throwOnMissingKey = true } = options;
-        // Priority 1: Environment variables (Node.js/bundler)
-        const envConfig = loadFromProcessEnv();
-        if (envConfig) {
-            return envConfig;
-        }
-        // Priority 2: Vite environment variables / SSR-injected config
-        const viteConfig = loadFromViteEnv();
-        if (viteConfig) {
-            return viteConfig;
-        }
-        // Priority 3: Global object (window.astermindConfig)
-        const globalConfig = loadFromGlobalObject();
-        if (globalConfig) {
-            validateConfig(globalConfig);
-            return globalConfig;
-        }
-        // Priority 4: Script data attributes
-        const scriptConfig = loadFromScriptAttributes();
-        if (scriptConfig) {
-            return scriptConfig;
-        }
-        // No config found
-        if (throwOnMissingKey) {
-            throw new Error('AsterMind API key is required. Configure using one of these methods:\n' +
-                '  1. Set VITE_ASTERMIND_RAG_API_KEY environment variable (Vite)\n' +
-                '  2. Set REACT_APP_ASTERMIND_RAG_API_KEY environment variable (CRA)\n' +
-                '  3. Set window.astermindConfig = { apiKey: "am_...", apiUrl: "..." }\n' +
-                '  4. Add data-astermind-key attribute to your script tag\n' +
-                '  5. Pass apiKey directly to createClient() or CyberneticClient constructor');
-        }
-        else {
-            console.warn('[AsterMind] No API key found. Chatbot will not function until configured.');
-            return null;
-        }
-    }
-
     // src/agentic/SiteMapDiscovery.ts
     // Multi-source sitemap discovery and merging for agentic navigation
     // Zero-config mode: automatically discovers routes on any site