@juspay/neurolink 9.30.0 → 9.31.1

package/dist/client/client/wsClient.js

@@ -0,0 +1,369 @@
+/**
+ * WebSocket Client for NeuroLink SDK
+ *
+ * Provides a dedicated WebSocket client for real-time streaming connections
+ * to NeuroLink servers. Supports bidirectional communication, automatic
+ * reconnection, and message queuing.
+ *
+ * @module @neurolink/client/wsClient
+ */
+// =============================================================================
+// WebSocket Client
+// =============================================================================
+/**
+ * WebSocket streaming client for NeuroLink
+ *
+ * Provides real-time bidirectional communication with NeuroLink servers.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const wsClient = new NeuroLinkWebSocket({
+ *   baseUrl: 'wss://api.neurolink.example.com/ws',
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * wsClient.connect({
+ *   onMessage: (event) => console.log('Received:', event),
+ *   onError: (error) => console.error('Error:', error),
+ * });
+ *
+ * // Send a message
+ * wsClient.send({
+ *   type: 'message',
+ *   channel: 'chat',
+ *   payload: { prompt: 'Hello!' },
+ * });
+ * ```
+ */
+export class NeuroLinkWebSocket {
+    ws = null;
+    config;
+    state = "disconnected";
+    reconnectAttempts = 0;
+    heartbeatTimer = null;
+    messageQueue = [];
+    eventHandlers = {};
+    subscriptions = new Map();
+    pendingAuth = false;
+    /**
+     * Local flag to suppress reconnection during an explicit disconnect().
+     * Unlike mutating config.autoReconnect, this preserves the user's
+     * original configuration so that a subsequent connect() still honours it.
+     */
+    disconnectRequested = false;
+    constructor(config) {
+        this.config = {
+            baseUrl: config.baseUrl,
+            apiKey: config.apiKey ?? "",
+            token: config.token ?? "",
+            timeout: config.timeout ?? 30000,
+            headers: config.headers ?? {},
+            autoReconnect: config.autoReconnect ?? true,
+            maxReconnectAttempts: config.maxReconnectAttempts ?? 10,
+            reconnectDelay: config.reconnectDelay ?? 1000,
+            maxReconnectDelay: config.maxReconnectDelay ?? 30000,
+            heartbeatInterval: config.heartbeatInterval ?? 30000,
+            queueSize: config.queueSize ?? 100,
+        };
+    }
+    /**
+     * Get current connection state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.state === "connected" && this.ws?.readyState === WebSocket.OPEN;
+    }
+    /**
+     * Connect to WebSocket server
+     */
+    connect(handlers) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            return;
+        }
+        // Reset the disconnect flag so reconnection logic works again
+        this.disconnectRequested = false;
+        this.eventHandlers = handlers ?? {};
+        this.setState("connecting");
+        // Build WebSocket URL (credentials are sent via headers, not query params,
+        // to avoid leaking secrets in server logs, browser history, and HTTP referers)
+        const url = new URL(this.config.baseUrl);
+        // Build auth headers matching httpClient.ts conventions
+        const authHeaders = {
+            ...this.config.headers,
+        };
+        if (this.config.apiKey) {
+            authHeaders["X-API-Key"] = this.config.apiKey;
+        }
+        if (this.config.token) {
+            authHeaders["Authorization"] = `Bearer ${this.config.token}`;
+        }
+        // In Node.js (ws package), pass headers via the options parameter.
+        // In browsers, the WebSocket API does not support custom headers, so
+        // credentials are sent as the first message after the connection opens.
+        const isNode = typeof globalThis.process !== "undefined" &&
+            typeof globalThis.process.versions?.node === "string";
+        if (isNode && Object.keys(authHeaders).length > 0) {
+            // The `ws` npm package accepts a second `options` object with a `headers`
+            // property.  The DOM WebSocket type does not model this, so we cast
+            // through `unknown` to satisfy TypeScript while remaining correct at
+            // runtime under Node.js.
+            this.ws = new WebSocket(url.toString(), { headers: authHeaders });
+        }
+        else {
+            this.ws = new WebSocket(url.toString());
+        }
+        this.pendingAuth = !isNode && (!!this.config.apiKey || !!this.config.token);
+        this.setupEventListeners();
+    }
+    /**
+     * Disconnect from WebSocket server
+     *
+     * Sets a local flag to prevent the onclose handler from triggering
+     * reconnection, without mutating the shared config.
+     */
+    disconnect() {
+        this.stopHeartbeat();
+        this.disconnectRequested = true;
+        if (this.ws) {
+            this.ws.close(1000, "Client disconnect");
+            this.ws = null;
+        }
+        this.setState("disconnected");
+    }
+    /**
+     * Send a message through WebSocket
+     */
+    send(message) {
+        if (this.isConnected() && this.ws) {
+            this.ws.send(JSON.stringify(message));
+        }
+        else {
+            // Queue message for when connected
+            if (this.messageQueue.length < this.config.queueSize) {
+                this.messageQueue.push(message);
+            }
+        }
+    }
+    /**
+     * Subscribe to a channel with streaming callbacks
+     */
+    subscribe(channel, callbacks) {
+        this.subscriptions.set(channel, callbacks);
+        this.send({
+            type: "subscribe",
+            channel,
+        });
+    }
+    /**
+     * Unsubscribe from a channel
+     */
+    unsubscribe(channel) {
+        this.subscriptions.delete(channel);
+        this.send({
+            type: "unsubscribe",
+            channel,
+        });
+    }
+    /**
+     * Stream a prompt with callbacks
+     */
+    stream(prompt, options) {
+        const channel = options?.channel ?? `stream_${Date.now()}`;
+        if (options) {
+            this.subscribe(channel, {
+                onText: options.onText,
+                onToolCall: options.onToolCall,
+                onToolResult: options.onToolResult,
+                onDone: options.onDone,
+                onError: options.onError,
+            });
+        }
+        this.send({
+            type: "message",
+            channel,
+            payload: { prompt },
+        });
+    }
+    // =============================================================================
+    // Private Methods
+    // =============================================================================
+    setupEventListeners() {
+        if (!this.ws) {
+            return;
+        }
+        this.ws.onopen = () => {
+            this.setState("connected");
+            this.reconnectAttempts = 0;
+            // In browser environments, send credentials as the first message
+            // since the browser WebSocket API does not support custom headers.
+            if (this.pendingAuth && this.ws) {
+                const authPayload = { type: "auth" };
+                if (this.config.apiKey) {
+                    authPayload["apiKey"] = this.config.apiKey;
+                }
+                if (this.config.token) {
+                    authPayload["token"] = this.config.token;
+                }
+                this.ws.send(JSON.stringify(authPayload));
+                this.pendingAuth = false;
+            }
+            this.eventHandlers.onOpen?.();
+            this.startHeartbeat();
+            this.flushMessageQueue();
+            // Re-subscribe to all active channels after a reconnect so that
+            // channel listeners are restored transparently.
+            this.replaySubscriptions();
+        };
+        this.ws.onclose = (event) => {
+            this.setState("disconnected");
+            this.stopHeartbeat();
+            this.eventHandlers.onClose?.(event.code, event.reason);
+            // Only attempt reconnection when auto-reconnect is enabled AND this
+            // was not an intentional disconnect (code 1000 or explicit call).
+            if (this.config.autoReconnect &&
+                !this.disconnectRequested &&
+                event.code !== 1000) {
+                this.attemptReconnect();
+            }
+        };
+        this.ws.onerror = () => {
+            this.setState("error");
+            const error = new Error("WebSocket connection error");
+            this.eventHandlers.onError?.(error);
+        };
+        this.ws.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data);
+                this.handleMessage(data);
+            }
+            catch {
+                // Handle non-JSON messages
+                this.eventHandlers.onMessage?.({
+                    type: "text",
+                    content: event.data,
+                    timestamp: Date.now(),
+                });
+            }
+        };
+    }
+    handleMessage(data) {
+        // Notify global handler
+        this.eventHandlers.onMessage?.(data);
+        // Notify channel-specific subscribers
+        if (data.channel) {
+            const callbacks = this.subscriptions.get(data.channel);
+            if (callbacks) {
+                this.dispatchToCallbacks(data, callbacks);
+            }
+        }
+    }
+    dispatchToCallbacks(event, callbacks) {
+        switch (event.type) {
+            case "text":
+                callbacks.onText?.(event.content ?? "");
+                break;
+            case "tool-call":
+                if (event.toolCall) {
+                    callbacks.onToolCall?.(event.toolCall);
+                }
+                break;
+            case "tool-result":
+                if (event.toolResult) {
+                    callbacks.onToolResult?.(event.toolResult);
+                }
+                break;
+            case "done": {
+                // Create a StreamResult from the event
+                const result = {
+                    content: event.content ?? "",
+                    finishReason: "stop",
+                };
+                callbacks.onDone?.(result);
+                break;
+            }
+            case "error":
+                if (event.error) {
+                    callbacks.onError?.(event.error);
+                }
+                break;
+        }
+    }
+    setState(state) {
+        this.state = state;
+        this.eventHandlers.onStateChange?.(state);
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (this.isConnected()) {
+                this.send({ type: "ping" });
+            }
+        }, this.config.heartbeatInterval);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    attemptReconnect() {
+        if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+            this.eventHandlers.onError?.(new Error(`Max reconnection attempts (${this.config.maxReconnectAttempts}) exceeded`));
+            return;
+        }
+        this.reconnectAttempts++;
+        const delay = Math.min(this.config.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1), this.config.maxReconnectDelay);
+        this.eventHandlers.onReconnect?.(this.reconnectAttempts);
+        setTimeout(() => {
+            this.connect(this.eventHandlers);
+        }, delay);
+    }
+    flushMessageQueue() {
+        while (this.messageQueue.length > 0 && this.isConnected()) {
+            const message = this.messageQueue.shift();
+            if (message) {
+                this.send(message);
+            }
+        }
+    }
+    /**
+     * Re-send subscribe messages for every active subscription.
+     * Called after a successful reconnect so that channel listeners
+     * resume working without the caller needing to re-subscribe manually.
+     */
+    replaySubscriptions() {
+        for (const channel of this.subscriptions.keys()) {
+            this.send({
+                type: "subscribe",
+                channel,
+            });
+        }
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a WebSocket client instance
+ *
+ * @example
+ * ```typescript
+ * const client = createWebSocketClient({
+ *   baseUrl: 'wss://api.neurolink.example.com/ws',
+ *   apiKey: 'your-api-key',
+ *   autoReconnect: true,
+ * });
+ *
+ * client.connect({
+ *   onMessage: (event) => console.log('Received:', event),
+ * });
+ * ```
+ */
+export function createWebSocketClient(config) {
+    return new NeuroLinkWebSocket(config);
+}

package/dist/client/config/configManager.js

@@ -0,0 +1,303 @@
+/**
+ * NeuroLink Config Manager with Backup/Restore System
+ * Industry standard configuration management with safety mechanisms
+ */
+import { promises as fs } from "fs";
+import { join } from "path";
+import { createHash } from "crypto";
+import { logger } from "../utils/logger.js";
+import { DEFAULT_CONFIG } from "../types/configTypes.js";
+const { readFile, writeFile, readdir, mkdir, unlink, access } = fs;
+/**
+ * Enhanced Config Manager with automatic backup/restore capabilities
+ */
+export class NeuroLinkConfigManager {
+    configPath = ".neurolink.config";
+    backupDir = ".neurolink.backups";
+    config = null;
+    configCache = new Map();
+    /**
+     * Load configuration with caching
+     */
+    async loadConfig() {
+        if (!this.config) {
+            this.config = await this.readConfigFile();
+        }
+        return this.config;
+    }
+    /**
+     * Update configuration with automatic backup
+     */
+    async updateConfig(updates, options = {}) {
+        const { createBackup = true, validate = true, merge = true, reason = "update", silent = false, } = options;
+        // ALWAYS create backup before updating (unless explicitly disabled)
+        if (createBackup) {
+            await this.createBackup(reason);
+            if (!silent) {
+                logger.info("💾 Backup created before config update");
+            }
+        }
+        const existing = await this.loadConfig();
+        // Merge or replace based on options
+        this.config = merge
+            ? { ...existing, ...updates, lastUpdated: Date.now() }
+            : { ...updates, lastUpdated: Date.now() };
+        // Validate config if requested
+        if (validate) {
+            const validation = await this.validateConfig(this.config);
+            if (!validation.valid) {
+                throw new Error(`Config validation failed: ${validation.errors.join(", ")}`);
+            }
+        }
+        try {
+            await this.persistConfig(this.config);
+            if (!silent) {
+                logger.info("✅ Configuration updated successfully");
+            }
+        }
+        catch (error) {
+            // Auto-restore on failure
+            if (createBackup) {
+                await this.restoreLatestBackup();
+                if (!silent) {
+                    logger.info("🔄 Auto-restored from backup due to error");
+                }
+            }
+            throw new Error(`Config update failed, restored from backup: ${error.message}`, { cause: error });
+        }
+    }
+    /**
+     * Create a backup with metadata
+     */
+    async createBackup(reason = "manual") {
+        await this.ensureBackupDirectory();
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const backupFilename = `neurolink-config-${timestamp}.js`;
+        const backupPath = join(this.backupDir, backupFilename);
+        const currentConfig = await this.loadConfig();
+        const configHash = this.generateConfigHash(currentConfig);
+        const backupMetadata = {
+            reason,
+            timestamp: Date.now(),
+            version: currentConfig.configVersion || "unknown",
+            originalPath: this.configPath,
+            hash: configHash,
+            size: JSON.stringify(currentConfig).length,
+            createdBy: "NeuroLinkConfigManager",
+        };
+        const backupContent = `// NeuroLink Config Backup - ${reason}
+// Created: ${new Date().toISOString()}
+// Reason: ${reason}
+// Hash: ${configHash}
+export const metadata = ${JSON.stringify(backupMetadata, null, 2)};
+export default ${JSON.stringify(currentConfig, null, 2)};`;
+        await writeFile(backupPath, backupContent, "utf-8");
+        return backupPath;
+    }
+    /**
+     * List all available backups
+     */
+    async listBackups() {
+        await this.ensureBackupDirectory();
+        try {
+            const files = await readdir(this.backupDir);
+            const backupFiles = files.filter((f) => f.startsWith("neurolink-config-") && f.endsWith(".js"));
+            const backups = [];
+            for (const file of backupFiles) {
+                try {
+                    const filePath = join(this.backupDir, file);
+                    const content = await readFile(filePath, "utf-8");
+                    const metadata = this.extractMetadataFromBackup(content);
+                    const config = this.extractConfigFromBackup(content);
+                    backups.push({
+                        filename: file,
+                        path: filePath,
+                        metadata,
+                        config,
+                    });
+                }
+                catch (error) {
+                    logger.warn(`Failed to read backup ${file}:`, error.message);
+                }
+            }
+            return backups.sort((a, b) => b.metadata.timestamp - a.metadata.timestamp);
+        }
+        catch (error) {
+            logger.warn("Failed to list backups:", error.message);
+            return [];
+        }
+    }
+    /**
+     * Restore from specific backup
+     */
+    async restoreFromBackup(backupFilename) {
+        const backupPath = join(this.backupDir, backupFilename);
+        // Create backup of current config before restore
+        await this.createBackup("pre-restore");
+        try {
+            const content = await readFile(backupPath, "utf-8");
+            const restoredConfig = this.extractConfigFromBackup(content);
+            // Validate restored config
+            const validation = await this.validateConfig(restoredConfig);
+            if (!validation.valid) {
+                throw new Error(`Backup config is invalid: ${validation.errors.join(", ")}`);
+            }
+            this.config = restoredConfig;
+            await this.persistConfig(this.config);
+            logger.info(`✅ Config restored from backup: ${backupFilename}`);
+        }
+        catch (error) {
+            throw new Error(`Failed to restore from backup ${backupFilename}: ${error.message}`, { cause: error });
+        }
+    }
+    /**
+     * Restore from latest backup
+     */
+    async restoreLatestBackup() {
+        const backups = await this.listBackups();
+        if (backups.length === 0) {
+            throw new Error("No backups available for restore");
+        }
+        await this.restoreFromBackup(backups[0].filename);
+    }
+    /**
+     * Clean up old backups
+     */
+    async cleanupOldBackups(keepCount = 10) {
+        const backups = await this.listBackups();
+        const toDelete = backups.slice(keepCount);
+        for (const backup of toDelete) {
+            try {
+                await unlink(backup.path);
+                logger.info(`🗑️ Deleted old backup: ${backup.filename}`);
+            }
+            catch (error) {
+                logger.warn(`Failed to delete backup ${backup.filename}:`, error.message);
+            }
+        }
+    }
+    /**
+     * Update provider status
+     */
+    async updateProviderStatus(providerId, status) {
+        const config = await this.loadConfig();
+        if (!config.providers) {
+            config.providers = {};
+        }
+        config.providers[providerId] = {
+            ...config.providers[providerId],
+            ...status,
+            lastCheck: Date.now(),
+        };
+        await this.updateConfig({ providers: config.providers }, { reason: `provider-${providerId}-update` });
+    }
+    /**
+     * Validate configuration
+     */
+    async validateConfig(config) {
+        const result = {
+            valid: true,
+            errors: [],
+            warnings: [],
+            suggestions: [],
+        };
+        // Basic validation
+        if (!config || typeof config !== "object") {
+            result.errors.push("Config must be a valid object");
+            result.valid = false;
+            return result;
+        }
+        // Version validation
+        if (config.configVersion && typeof config.configVersion !== "string") {
+            result.errors.push("configVersion must be a string");
+            result.valid = false;
+        }
+        // Provider validation
+        if (config.providers) {
+            if (typeof config.providers !== "object") {
+                result.errors.push("providers must be an object");
+                result.valid = false;
+            }
+            else {
+                // Check for default provider
+                if (!config.providers.defaultProvider) {
+                    result.warnings.push("No default provider specified");
+                    result.suggestions.push('Consider setting providers.defaultProvider to "googleAi"');
+                }
+            }
+        }
+        // Performance validation
+        if (config.performance?.cache?.ttlMs) {
+            if (config.performance.cache.ttlMs < 1000) {
+                result.warnings.push("Cache TTL is very low (< 1 second)");
+            }
+        }
+        return result;
+    }
+    /**
+     * Generate default configuration
+     */
+    async generateDefaultConfig() {
+        return {
+            ...DEFAULT_CONFIG,
+            lastUpdated: Date.now(),
+        };
+    }
+    // Private helper methods
+    async ensureBackupDirectory() {
+        try {
+            await mkdir(this.backupDir, { recursive: true });
+        }
+        catch (error) {
+            logger.warn("Failed to create backup directory:", error.message);
+        }
+    }
+    async readConfigFile() {
+        try {
+            // Check if config file exists
+            await access(this.configPath);
+            const content = await readFile(this.configPath, "utf-8");
+            // Parse as JavaScript module
+            const configMatch = content.match(/export default ([\s\S]+);?$/);
+            if (configMatch) {
+                const configJson = configMatch[1].trim();
+                return JSON.parse(configJson);
+            }
+            throw new Error("Invalid config file format");
+        }
+        catch (error) {
+            logger.info("Config file not found or invalid, generating default...", {
+                error: error instanceof Error ? error.message : String(error),
+                configPath: this.configPath,
+            });
+            return await this.generateDefaultConfig();
+        }
+    }
+    async persistConfig(config) {
+        const configContent = `export default ${JSON.stringify(config, null, 2)};`;
+        await writeFile(this.configPath, configContent, "utf-8");
+        // Clear cache after persisting
+        this.config = config;
+    }
+    generateConfigHash(config) {
+        const configString = JSON.stringify(config, Object.keys(config).sort());
+        return createHash("sha256")
+            .update(configString)
+            .digest("hex")
+            .substring(0, 8);
+    }
+    extractMetadataFromBackup(content) {
+        const metadataMatch = content.match(/export const metadata = ([\s\S]+?);/);
+        if (metadataMatch) {
+            return JSON.parse(metadataMatch[1]);
+        }
+        throw new Error("No metadata found in backup file");
+    }
+    extractConfigFromBackup(content) {
+        const configMatch = content.match(/export default ([\s\S]+);$/);
+        if (configMatch) {
+            return JSON.parse(configMatch[1]);
+        }
+        throw new Error("No config found in backup file");
+    }
+}