@astermind/cybernetic-chatbot-client 2.2.36 → 2.2.48

package/README.md

@@ -12,8 +12,10 @@ Cybernetic Chatbot Client is the official JavaScript SDK for integrating [AsterM
 
 ## Key Features
 
+- **Dual Transport** - WebSocket streaming for SaaS, REST+SSE for on-prem (auto-detected)
 - **Offline-First Architecture** - IndexedDB caching with TF-IDF local search
-- **SSE Streaming** - Real-time token-by-token responses
+- **SSE Streaming** - Real-time token-by-token responses (REST fallback)
+- **WebSocket Streaming** - Low-latency streaming via persistent connection (SaaS)
 - **Session Management** - Multi-turn conversation continuity
 - **Configurable Retry Logic** - Exponential backoff with customizable settings
 - **Connection Status Monitoring** - Real-time online/offline detection
@@ -28,6 +30,7 @@ Cybernetic Chatbot Client is the official JavaScript SDK for integrating [AsterM
 - [Licensing](#licensing)
 - [Configuration](#configuration)
 - [Features](#features)
+  - [WebSocket Transport (SaaS)](#websocket-transport-saas)
   - [Offline-First Architecture](#offline-first-architecture)
   - [Pre-computed Vector Export (Advanced)](#pre-computed-vector-export-advanced)
   - [Streaming Responses](#streaming-responses)
@@ -333,6 +336,19 @@ interface CyberneticConfig {
   /** API key for authentication - must start with 'am_' (required) */
   apiKey: string;
 
+  /** WebSocket URL for SaaS streaming (auto-derived from apiUrl for known SaaS domains) */
+  wsUrl?: string;
+
+  /** Transport mode: 'auto' (default) tries WebSocket then REST, 'websocket' forces WS, 'rest' forces REST+SSE */
+  transport?: 'auto' | 'websocket' | 'rest';
+
+  /** WebSocket transport options */
+  websocket?: {
+    maxReconnectAttempts?: number;  // Default: 3
+    reconnectDelay?: number;       // Default: 1000ms (exponential backoff)
+    connectionTimeout?: number;    // Default: 10000ms
+  };
+
   /** License key (JWT token) from https://astermind.ai */
   licenseKey?: string;
 
@@ -409,6 +425,70 @@ interface AgenticConfig {
 
 ## Features
 
+### WebSocket Transport (SaaS)
+
+When connecting to AsterMind's SaaS infrastructure, the client automatically uses WebSocket transport for streaming chat. This provides lower latency and access to the full RAG pipeline (RSF temporal scoring, hybrid reranking, Omega embeddings, BYOLLM).
+
+**Auto-detection (zero config for SaaS users):**
+
+```typescript
+const client = new CyberneticClient({
+  apiUrl: 'https://chatapi.astermind.ai',
+  apiKey: 'am_your_api_key',
+  // wsUrl auto-derived → wss://chatws.astermind.ai
+});
+```
+
+The client auto-derives WebSocket URLs for known SaaS domains:
+- `chatapi.astermind.ai` → `wss://chatws.astermind.ai`
+- `chatapi-dev.astermind.ai` → `wss://chatws-dev.astermind.ai`
+- `api.astermind.ai` → `wss://chatws.astermind.ai`
+
+**Explicit configuration:**
+
+```typescript
+const client = new CyberneticClient({
+  apiUrl: 'https://chatapi.astermind.ai',
+  apiKey: 'am_your_api_key',
+  wsUrl: 'wss://chatws.astermind.ai',
+  transport: 'websocket',  // Force WebSocket only (no REST fallback)
+});
+```
+
+**On-prem (unchanged, REST+SSE):**
+
+```typescript
+const client = new CyberneticClient({
+  apiUrl: 'http://localhost:3000',
+  apiKey: 'am_your_api_key',
+  // No wsUrl → uses REST+SSE as before
+});
+```
+
+**Transport modes:**
+- `'auto'` (default) — Uses WebSocket when available, falls back to REST+SSE on failure
+- `'websocket'` — Forces WebSocket only, no REST fallback
+- `'rest'` — Forces REST+SSE only, ignores WebSocket
+
+**Environment variable support:**
+
+```env
+# Vite
+VITE_ASTERMIND_RAG_WS_URL=wss://chatws.astermind.ai
+
+# Node.js / CRA
+ASTERMIND_RAG_WS_URL=wss://chatws.astermind.ai
+REACT_APP_ASTERMIND_RAG_WS_URL=wss://chatws.astermind.ai
+```
+
+**Cleanup:**
+
+Call `destroy()` when disposing the client to close the WebSocket connection:
+
+```typescript
+client.destroy();
+```
+
 ### Offline-First Architecture
 
 The client includes **built-in offline fallback** with IndexedDB caching and TF-IDF local search—no additional setup required. When the server is unreachable, the client automatically serves cached responses:
@@ -576,7 +656,7 @@ This helps identify configuration issues without disrupting functionality.
 
 ### Streaming Responses
 
-Real-time token streaming via Server-Sent Events (SSE):
+Real-time token streaming via WebSocket (SaaS) or Server-Sent Events (on-prem):
 
 ```typescript
 await client.askStream('Explain quantum computing', {
@@ -892,6 +972,9 @@ class CyberneticClient {
   // Cache methods
   syncCache(): Promise<void>;
   clearCache(): Promise<void>;
+
+  // Cleanup
+  destroy(): void;  // Close WebSocket connection and clean up resources
 }
 ```
 
@@ -923,7 +1006,7 @@ interface StreamCallbacks {
 }
 
 interface CyberneticError {
-  code: 'NETWORK_ERROR' | 'AUTH_ERROR' | 'RATE_LIMIT' | 'SERVER_ERROR' | 'CACHE_ERROR' | 'LOCAL_RAG_ERROR';
+  code: 'NETWORK_ERROR' | 'AUTH_ERROR' | 'RATE_LIMIT' | 'SERVER_ERROR' | 'CACHE_ERROR' | 'LOCAL_RAG_ERROR' | 'WS_ERROR';
   message: string;
   retryAfter?: number;
 }
@@ -964,7 +1047,9 @@ Requires IndexedDB support for offline caching.
 
 ## Integration with Cybernetic Chatbot Backend
 
-This client is designed to work with the AsterMind Cybernetic Chatbot backend. The following endpoints are used:
+This client is designed to work with the AsterMind Cybernetic Chatbot backend. The client supports two transport modes:
+
+**REST API Endpoints** (on-prem and supplementary):
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
@@ -973,8 +1058,20 @@ This client is designed to work with the AsterMind Cybernetic Chatbot backend. T
 | `/api/external/docs` | GET | Fetch documents for offline caching |
 | `/api/external/status` | GET | Check API status, quota, and system settings |
 | `/api/external/health` | GET | Health check (no auth required) |
+| `/api/external/search` | GET | Search documents |
+| `/api/external/sitemap` | GET | Get document sitemap for navigation |
+| `/api/external/config` | GET | Get chatbot configuration |
+
+**WebSocket Endpoint** (SaaS streaming):
+
+| Endpoint | Description |
+|----------|-------------|
+| `wss://chatws.astermind.ai` | Production WebSocket streaming |
+| `wss://chatws-dev.astermind.ai` | Development WebSocket streaming |
+
+WebSocket authentication uses an API key query parameter: `?apiKey=am_xxx`
 
-**Authentication**: All authenticated endpoints require an `X-API-Key` header with a valid API key (prefixed with `am_`).
+**Authentication**: REST endpoints require an `X-API-Key` header with a valid API key (prefixed with `am_`). WebSocket endpoints use a `?apiKey=am_xxx` query parameter.
 
 **Rate Limiting**: The backend enforces rate limits. The client handles 429 responses gracefully and includes `retryAfter` in responses when applicable.
 

package/dist/ApiClient.d.ts

@@ -62,16 +62,17 @@ export declare class ApiClient {
      */
     chatStream(message: string, options: ChatRequest & StreamCallbacks): Promise<void>;
     /**
-     * Get general documents for caching
+     * Get general documents for caching.
+     * Normalizes field names from both canonical (title) and legacy (name) formats.
      */
     getGeneralDocs(since?: string | null): Promise<Array<{
         id: string;
         title: string;
-        content: string;
         updatedAt: string;
     }>>;
     /**
-     * Get API status, quota, and system settings
+     * Get API status, quota, and system settings.
+     * Normalizes response from both canonical and legacy backend formats.
      */
     getStatus(): Promise<StatusResponse>;
     /**

package/dist/ApiClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiClient.d.ts","sourceRoot":"","sources":["../src/ApiClient.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzD,UAAU,WAAW;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACL;AAED,UAAU,YAAY;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE;QACH,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE;YACZ,MAAM,EAAE,MAAM,CAAC;YACf,GAAG,EAAE,MAAM,CAAC;SACf,CAAC;KACL,CAAC;CACL;AAED,UAAU,eAAe;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACxC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpC;AAED,UAAU,cAAc;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACzC,KAAK,EAAE;QACH,SAAS,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAChD,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAChD,CAAC;IACF,cAAc,CAAC,EAAE,cAAc,CAAC;CACnC;AAkCD;;GAEG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK3C;;OAEG;IACG,IAAI,CACN,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,YAAY,CAAC;IA2BxB;;OAEG;IACG,UAAU,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW,GAAG,eAAe,GACvC,OAAO,CAAC,IAAI,CAAC;IAuEhB;;OAEG;IACG,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC;QACvD,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IAqBH;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC;IAc1C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CASjE"}
+{"version":3,"file":"ApiClient.d.ts","sourceRoot":"","sources":["../src/ApiClient.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzD,UAAU,WAAW;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACL;AAED,UAAU,YAAY;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE;QACH,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE;YACZ,MAAM,EAAE,MAAM,CAAC;YACf,GAAG,EAAE,MAAM,CAAC;SACf,CAAC;KACL,CAAC;CACL;AAED,UAAU,eAAe;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACxC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpC;AAED,UAAU,cAAc;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACzC,KAAK,EAAE;QACH,SAAS,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAChD,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAChD,CAAC;IACF,cAAc,CAAC,EAAE,cAAc,CAAC;CACnC;AAqCD;;GAEG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK3C;;OAEG;IACG,IAAI,CACN,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,YAAY,CAAC;IA4BxB;;OAEG;IACG,UAAU,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW,GAAG,eAAe,GACvC,OAAO,CAAC,IAAI,CAAC;IAuEhB;;;OAGG;IACG,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC;QACvD,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IA0BH;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC;IAiD1C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CASjE"}

package/dist/CyberneticClient.d.ts

@@ -21,6 +21,7 @@ export interface AgenticCapabilities {
 export declare class CyberneticClient {
     private config;
     private apiClient;
+    private wsTransport;
     private cache;
     private localRAG;
     private status;
@@ -189,6 +190,11 @@ export declare class CyberneticClient {
      * @param options - Optional request configuration
      */
     askStream(message: string, callbacks: StreamCallbacks, options?: AskOptions): Promise<void>;
+    /**
+     * Stream chat via REST+SSE (original transport).
+     * Used as the primary transport for on-prem, or as fallback for SaaS WebSocket failures.
+     */
+    private streamViaSSE;
     /**
      * Sync documents to local cache for offline use
      */
@@ -211,6 +217,11 @@ export declare class CyberneticClient {
      * Clear local cache
      */
     clearCache(): Promise<void>;
+    /**
+     * Clean up all resources (WebSocket connection, caches, event listeners).
+     * Call this when the client is no longer needed to prevent memory leaks.
+     */
+    destroy(): void;
     /**
      * Manually check if backend is reachable
      */

package/dist/CyberneticClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CyberneticClient.d.ts","sourceRoot":"","sources":["../src/CyberneticClient.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EACR,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EAIb,aAAa,EAChB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,iDAAiD;IAEjD,KAAK,EAAE,GAAG,CAAC;IACX,4DAA4D;IAE5D,gBAAgB,CAAC,EAAE,GAAG,CAAC;CAC1B;AA2BD;;;;;GAKG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,SAAS,CAAgC;IAGjD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,mBAAmB,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAU;IAGlD,OAAO,CAAC,mBAAmB,CAAoC;IAG/D,OAAO,CAAC,cAAc,CAAiB;IAGvC,OAAO,CAAC,cAAc,CAAyC;IAG/D,OAAO,CAAC,QAAQ,CAAgC;IAGhD,OAAO,CAAC,mBAAmB,CAAS;gBAExB,MAAM,EAAE,gBAAgB;IAuEpC;;;;;;;;;;OAUG;IACH,eAAe,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;IAKxD;;OAEG;IACH,gBAAgB,IAAI,OAAO;IAW3B;;OAEG;IACH,sBAAsB,IAAI,mBAAmB,GAAG,IAAI;IAIpD;;OAEG;IACH,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAMxC;;;OAGG;IACH,gBAAgB,IAAI,aAAa;IAIjC;;;;;;OAMG;IACH,wBAAwB,CAAC,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO;IAiBlE;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG;QAC7B,MAAM,EAAE;YACJ,EAAE,EAAE,MAAM,CAAC;YACX,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;YACnB,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACpC,GAAG,IAAI,CAAC;QACT,cAAc,EAAE,OAAO,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;KAC9B,GAAG,IAAI;IAaR;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE;QACxB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC;QACR,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAeF;;;;;;;OAOG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;QAC3D,QAAQ,CAAC,EAAE,kBAAkB,CAAC;QAC9B,MAAM,CAAC,EAAE;YACL,EAAE,EAAE,MAAM,CAAC;YACX,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;YACnB,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACpC,CAAC;QACF,YAAY,CAAC,EAAE;YACX,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,CAAC,EAAE,MAAM,CAAC;SAClB,CAAC;KACL,CAAC;IA0BF;;;OAGG;YACW,iBAAiB;IA8E/B;;OAEG;YACW,eAAe;IA4B7B;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3C;;OAEG;IACH,qBAAqB,IAAI,OAAO;IAIhC;;OAEG;IACH,mBAAmB,IAAI;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;KAC1B,GAAG,IAAI;IAIR;;OAEG;IACH,iBAAiB,IAAI;QACjB,MAAM,EAAE,OAAO,CAAC;QAChB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KAC1B;IAID;;OAEG;IACH,iBAAiB,IAAI,wBAAwB,GAAG,IAAI;IAMpD;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAyE7E;;;;;;OAMG;IACG,SAAS,CACX,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,eAAe,EAC1B,OAAO,CAAC,EAAE,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC;IA4DhB;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBhC;;OAEG;IACH,SAAS,IAAI;QACT,UAAU,EAAE,gBAAgB,CAAC;QAC7B,KAAK,EAAE,WAAW,CAAC;QACnB,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;QAClC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;QACtC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;KAChC;IAUD;;OAEG;IACH,iBAAiB,IAAI,cAAc;IAInC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAazC;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC;IA8BlD;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;OAEG;IACH,qBAAqB,IAAI,MAAM,GAAG,SAAS;IAI3C;;OAEG;IACH,YAAY,IAAI,OAAO;IAevB;;OAEG;YACW,YAAY;IAuC1B;;;OAGG;YACW,WAAW;IAgIzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB;;OAEG;IACH,OAAO,CAAC,cAAc;IA0CtB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;OAEG;IACH,OAAO,CAAC,KAAK;CAGhB"}
+{"version":3,"file":"CyberneticClient.d.ts","sourceRoot":"","sources":["../src/CyberneticClient.ts"],"names":[],"mappings":"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"}

package/dist/WebSocketTransport.d.ts

@@ -0,0 +1,104 @@
+import type { StreamCallbacks, TransportState, WebSocketOptions } from './types.js';
+/**
+ * Options for a single WebSocket chat request
+ */
+interface WsChatOptions {
+    sessionId?: string;
+    context?: {
+        currentPage?: string;
+        pageTitle?: string;
+    };
+    wordLimit?: number;
+}
+/**
+ * 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.
+ */
+export declare class WebSocketTransport {
+    private ws;
+    private wsUrl;
+    private apiKey;
+    private state;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private connectionTimeout;
+    private connectionPromise;
+    private activeCallbacks;
+    private activeFullText;
+    private activeSessionId;
+    private beforeUnloadHandler;
+    constructor(wsUrl: string, apiKey: string, options?: WebSocketOptions);
+    /**
+     * Current transport state
+     */
+    getState(): TransportState;
+    /**
+     * Whether the WebSocket is currently connected
+     */
+    isConnected(): boolean;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * Stream a chat message over WebSocket.
+     *
+     * Sends: { type: "sendMessage", message, sessionId?, wordLimit?, context? }
+     * Receives: typing → chunk × N → done (with sources and metadata)
+     */
+    chatStream(message: string, options: WsChatOptions & StreamCallbacks): Promise<void>;
+    private _resolveStream;
+    private _rejectStream;
+    /**
+     * Disconnect and clean up the WebSocket connection
+     */
+    disconnect(): void;
+    /**
+     * Attempt reconnection with exponential backoff.
+     * Used internally after connection loss.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * 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
+     */
+    private handleMessage;
+    /**
+     * 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 }
+     */
+    private mapSources;
+    /**
+     * Clear active request state after completion or error
+     */
+    private clearActiveRequest;
+    /**
+     * Register a beforeunload handler to close the WebSocket on page unload
+     */
+    private registerCleanup;
+    /**
+     * Remove the beforeunload handler
+     */
+    private unregisterCleanup;
+}
+export {};
+//# sourceMappingURL=WebSocketTransport.d.ts.map

package/dist/WebSocketTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketTransport.d.ts","sourceRoot":"","sources":["../src/WebSocketTransport.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAIR,eAAe,EACf,cAAc,EACd,gBAAgB,EACnB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,UAAU,aAAa;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAiBD;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,iBAAiB,CAA8B;IAGvD,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,cAAc,CAAM;IAC5B,OAAO,CAAC,eAAe,CAAqB;IAG5C,OAAO,CAAC,mBAAmB,CAA6B;gBAE5C,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAQrE;;OAEG;IACH,QAAQ,IAAI,cAAc;IAI1B;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmFxB;;;;;OAKG;IACG,UAAU,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,GAAG,eAAe,GACzC,OAAO,CAAC,IAAI,CAAC;IA6ChB,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,aAAa,CAAyC;IAE9D;;OAEG;IACH,UAAU,IAAI,IAAI;IAelB;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BhC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IA6DrB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAclB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAM5B"}

package/dist/config.d.ts

@@ -1,4 +1,19 @@
 import type { CyberneticConfig, ConfigOptions } from './types.js';
+/**
+ * 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.
+ */
+export declare function deriveWsUrl(apiUrl: string): string | undefined;
+/**
+ * Resolve the WebSocket URL for a given config.
+ * Priority: explicit wsUrl → env var → auto-derived from apiUrl
+ */
+export declare function resolveWsUrl(config: CyberneticConfig): string | undefined;
 /**
  * Validate configuration
  */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKlE;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,gBAAgB,CAoB1E;AAED;;GAEG;AACH,iBAAS,kBAAkB,IAAI,gBAAgB,GAAG,IAAI,CA+BrD;AAED;;;GAGG;AACH,iBAAS,eAAe,IAAI,gBAAgB,GAAG,IAAI,CAmClD;AAED;;GAEG;AACH,iBAAS,oBAAoB,IAAI,gBAAgB,GAAG,IAAI,CAgBvD;AAED;;GAEG;AACH,iBAAS,wBAAwB,IAAI,gBAAgB,GAAG,IAAI,CAkB3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,aAAkB,GAAG,gBAAgB,GAAG,IAAI,CA0C/E;AAED;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;CAKzB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKlE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB9D;AA8CD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAazE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,gBAAgB,CAoB1E;AAED;;GAEG;AACH,iBAAS,kBAAkB,IAAI,gBAAgB,GAAG,IAAI,CA+BrD;AAED;;;GAGG;AACH,iBAAS,eAAe,IAAI,gBAAgB,GAAG,IAAI,CAmClD;AAED;;GAEG;AACH,iBAAS,oBAAoB,IAAI,gBAAgB,GAAG,IAAI,CAgBvD;AAED;;GAEG;AACH,iBAAS,wBAAwB,IAAI,gBAAgB,GAAG,IAAI,CAkB3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,aAAkB,GAAG,gBAAgB,GAAG,IAAI,CA0C/E;AAED;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;CAKzB,CAAC"}