@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta → 1.0.2

package/dist/cjs/websocket/client.js

@@ -1,465 +1,314 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = void 0;
-const eventemitter3_1 = require("eventemitter3");
-const ws_1 = __importDefault(require("ws"));
-const smart_caching_1 = require("../advanced/smart-caching");
-const circuit_breaker_1 = require("../advanced/circuit-breaker");
-class WebSocketClient extends eventemitter3_1.EventEmitter {
-    config;
-    ws;
-    nextId = 1;
-    subscriptions = new Map();
-    pendingRequests = new Map();
-    smartCache;
-    circuitBreaker;
+exports.WsClient = void 0;
+/**
+ * WsClient — typed Solana WebSocket subscription client.
+ *
+ * Provides a clean API for all 6 Solana PubSub subscription methods
+ * with automatic reconnect, ping/pong keep-alive, and subscription
+ * restore after reconnection.
+ *
+ * **Cross-platform**: Uses the native `WebSocket` global when available
+ * (browsers, Deno, Cloudflare Workers, Next.js client components) and
+ * falls back to the `ws` npm package on Node.js / Bun.
+ *
+ * @module websocket/client
+ * @since 1.0.0
+ *
+ * @example
+ * ```ts
+ * import { WsClient } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const ws = new WsClient({ endpoint: 'wss://rpc.synapse.com' });
+ * ws.onSlotChange((n) => console.log('Slot:', n.slot));
+ * ws.onAccountChange(pubkey, (n) => console.log('Balance:', n.result.value.lamports));
+ * ```
+ */
+const env_1 = require("../utils/env");
+/** @internal readyState constants (same for browser and `ws`). */
+const WS_OPEN = 1;
+/**
+ * Resolve the WebSocket constructor for the current runtime.
+ *
+ * - Browser / Edge / Deno: `globalThis.WebSocket` (native).
+ * - Node.js / Bun: dynamic `require('ws')`.
+ *
+ * @internal
+ * @throws {Error} If no WebSocket implementation is available.
+ */
+const getWsConstructor = () => {
+    // Browser-native WebSocket (or Node >= 22 with experimental flag)
+    if (typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+        return globalThis.WebSocket;
+    }
+    // Node.js fallback — dynamic require to avoid bundler warnings
+    try {
+        return require('ws');
+    }
+    catch {
+        throw new Error('No WebSocket implementation found. Install the "ws" package for Node.js: pnpm add ws');
+    }
+};
+/**
+ * Typed Solana WebSocket subscription client.
+ *
+ * Supports `accountSubscribe`, `programSubscribe`, `logsSubscribe`,
+ * `signatureSubscribe`, `slotSubscribe`, and `rootSubscribe`.
+ *
+ * Works in **both browser and Node.js** environments.
+ *
+ * @since 1.0.0
+ */
+class WsClient {
+    ws = null;
+    subs = new Map();
+    nextLocalId = 1;
+    reconnecting = false;
     reconnectAttempts = 0;
-    heartbeatTimer;
-    isDestroyed = false;
-    connectionState = 'disconnected';
-    // Metrics
-    metrics = {
-        messagesReceived: 0,
-        messagesSent: 0,
-        subscriptionsActive: 0,
-        reconnectCount: 0,
-        lastLatency: 0,
-        averageLatency: 0
-    };
+    pingTimer;
+    cfg;
+    _isBrowser;
     constructor(config) {
-        super();
-        this.config = {
+        this.cfg = {
             autoReconnect: true,
-            maxReconnectAttempts: 10,
-            reconnectDelay: 5000,
-            heartbeatInterval: 30000,
-            enableCompression: true,
-            enableSmartCaching: true,
-            enableCircuitBreaker: true,
-            maxSubscriptions: 1000,
-            bufferSize: 16 * 1024 * 1024, // 16MB
-            apiKey: config.apiKey || '',
+            reconnectIntervalMs: 2000,
+            maxReconnectAttempts: 20,
+            pingIntervalMs: 30_000,
             ...config
         };
-        this.initializeAdvancedFeatures();
+        this._isBrowser = (0, env_1.isBrowser)();
     }
+    // ── Public subscriptions ──────────────────────────────────────
     /**
-     * 🔌 Connect with enterprise features
+     * Subscribe to changes on a specific account.
+     *
+     * @param pubkey  - Account public key to watch.
+     * @param handler - Callback invoked on every account change.
+     * @param opts    - Encoding and commitment options.
+     * @returns Local subscription ID (use with {@link unsubscribe}).
+     * @since 1.0.0
      */
-    async connect() {
-        if (this.connectionState === 'connected') {
-            return;
-        }
-        return new Promise((resolve, reject) => {
-            this.connectionState = 'connecting';
-            try {
-                const wsUrl = this.config.endpoint.replace(/^http/, 'ws');
-                const headers = {};
-                if (this.config.apiKey) {
-                    headers['Authorization'] = `Bearer ${this.config.apiKey}`;
-                }
-                this.ws = new ws_1.default(wsUrl, {
-                    headers,
-                    perMessageDeflate: this.config.enableCompression,
-                    maxPayload: this.config.bufferSize
-                });
-                this.ws.on('open', () => {
-                    console.log('[Synapse]: Advanced WebSocket connected');
-                    this.connectionState = 'connected';
-                    this.reconnectAttempts = 0;
-                    this.startHeartbeat();
-                    this.emit('connected');
-                    resolve();
-                });
-                this.ws.on('message', (data) => {
-                    this.handleMessage(Buffer.from(data));
-                });
-                this.ws.on('close', (code, reason) => {
-                    this.handleDisconnect(code, reason.toString());
-                    this.emit('disconnected', { code, reason: reason.toString() });
-                });
-                this.ws.on('error', (error) => {
-                    console.error('[Synapse]: WebSocket error:', error);
-                    this.emit('error', error);
-                    reject(error);
-                });
-                // Timeout handler
-                setTimeout(() => {
-                    if (this.connectionState === 'connecting') {
-                        reject(new Error('[Synapse]: WebSocket connection timeout'));
-                    }
-                }, 10000);
-            }
-            catch (error) {
-                this.connectionState = 'disconnected';
-                reject(error);
-            }
-        });
+    onAccountChange(pubkey, handler, opts = {}) {
+        return this.subscribe('accountSubscribe', [pubkey, opts], handler);
     }
     /**
-     * 📡 Enhanced subscription with AI optimizations
+     * Subscribe to changes on all accounts owned by a program.
+     *
+     * @param programId - Program public key.
+     * @param handler   - Callback invoked on every matching account change.
+     * @param opts      - Encoding, commitment, and filter options.
+     * @returns Local subscription ID.
+     * @since 1.0.0
      */
-    async accountSubscribe(publicKey, callback, options = {}) {
-        const method = 'accountSubscribe';
-        const params = [
-            publicKey,
-            {
-                commitment: options.commitment || 'confirmed',
-                encoding: 'jsonParsed'
-            }
-        ];
-        return this.subscribe(method, params, callback, options);
+    onProgramAccountChange(programId, handler, opts = {}) {
+        return this.subscribe('programSubscribe', [programId, opts], handler);
     }
     /**
-     *  Signature subscription with filtering
+     * Subscribe to transaction logs.
+     *
+     * @param filter  - `'all'`, `'allWithVotes'`, or `{ mentions: [pubkey] }`.
+     * @param handler - Callback invoked with signature + log lines.
+     * @param opts    - Commitment options.
+     * @returns Local subscription ID.
+     * @since 1.0.0
      */
-    async signatureSubscribe(signature, callback, options = {}) {
-        const method = 'signatureSubscribe';
-        const params = [signature, { commitment: options.commitment || 'confirmed' }];
-        return this.subscribe(method, params, callback, options);
+    onLogs(filter, handler, opts = {}) {
+        return this.subscribe('logsSubscribe', [filter, opts], handler);
     }
     /**
-     *  Slot subscription with caching
+     * Subscribe to a specific transaction signature's confirmation.
+     *
+     * @param signature - Transaction signature to watch.
+     * @param handler   - Callback invoked on confirmation or received.
+     * @param opts      - Commitment + received-notification options.
+     * @returns Local subscription ID.
+     * @since 1.0.0
      */
-    async slotSubscribe(callback, options = {}) {
-        const method = 'slotSubscribe';
-        return this.subscribe(method, [], callback, options);
+    onSignature(signature, handler, opts = {}) {
+        return this.subscribe('signatureSubscribe', [signature, opts], handler);
     }
     /**
-     *  Root subscription
+     * Subscribe to slot changes.
+     *
+     * @param handler - Callback invoked on every new slot.
+     * @returns Local subscription ID.
+     * @since 1.0.0
      */
-    async rootSubscribe(callback, options = {}) {
-        const method = 'rootSubscribe';
-        return this.subscribe(method, [], callback, options);
+    onSlotChange(handler) {
+        return this.subscribe('slotSubscribe', [], handler);
     }
     /**
-     *  Program subscription with filtering
+     * Subscribe to root slot changes.
+     *
+     * @param handler - Callback invoked on every new root.
+     * @returns Local subscription ID.
+     * @since 1.0.0
      */
-    async programSubscribe(programId, callback, options = {}) {
-        const method = 'programSubscribe';
-        const params = [
-            programId,
-            {
-                commitment: options.commitment || 'confirmed',
-                encoding: options.encoding || 'jsonParsed',
-                filters: options.filters || []
-            }
-        ];
-        return this.subscribe(method, params, callback, options);
+    onRootChange(handler) {
+        return this.subscribe('rootSubscribe', [], handler);
     }
     /**
-     *  Enhanced unsubscribe
+     * Unsubscribe from a previously created subscription.
+     *
+     * @param localId - The ID returned by one of the `on*` methods.
+     * @since 1.0.0
      */
-    async unsubscribe(subscriptionId) {
-        const subscription = this.subscriptions.get(subscriptionId);
-        if (!subscription) {
-            throw new Error(`Subscription ${subscriptionId} not found`);
+    unsubscribe(localId) {
+        const entry = this.subs.get(localId);
+        if (!entry)
+            return;
+        if (entry.id != null && this.ws?.readyState === WS_OPEN) {
+            const unsubMethod = entry.method.replace('Subscribe', 'Unsubscribe');
+            this.sendJson({ jsonrpc: '2.0', id: localId, method: unsubMethod, params: [entry.id] });
         }
-        await this.request(`${subscription.method.replace('Subscribe', 'Unsubscribe')}`, [subscriptionId]);
-        this.subscriptions.delete(subscriptionId);
-        this.metrics.subscriptionsActive--;
+        this.subs.delete(localId);
     }
     /**
-     *  Generic subscription handler
+     * Close the WebSocket connection and clear all subscriptions.
+     * Disables auto-reconnect.
+     * @since 1.0.0
      */
-    async subscribe(method, params, callback, options) {
-        if (this.subscriptions.size >= this.config.maxSubscriptions) {
-            throw new Error('Maximum subscriptions reached');
-        }
-        const subscriptionId = await this.request(method, params);
-        // Enhanced callback with caching and filtering
-        const enhancedCallback = (data) => {
-            try {
-                // Apply custom filters
-                if (options.enableFiltering && options.customFilters) {
-                    if (!this.matchesFilters(data, options.customFilters)) {
-                        return; // Skip filtered data
-                    }
-                }
-                // Cache recent data
-                if (options.enableCache && this.smartCache) {
-                    const cacheKey = `ws:${method}:${subscriptionId}:latest`;
-                    this.smartCache.set(cacheKey, data, 10000); // 10s TTL
-                }
-                callback(data);
-            }
-            catch (error) {
-                console.error('❌ Subscription callback error:', error);
-            }
-        };
-        this.subscriptions.set(subscriptionId, {
-            method,
-            params,
-            options,
-            lastUpdate: Date.now(),
-            callback: enhancedCallback
-        });
-        this.metrics.subscriptionsActive++;
-        return subscriptionId;
+    close() {
+        this.cfg.autoReconnect = false;
+        this.stopPing();
+        this.ws?.close();
+        this.ws = null;
+        this.subs.clear();
     }
-    /**
-     *  Enhanced request with circuit breaker
-     */
-    async request(method, params = []) {
-        const executeRequest = async () => {
-            return new Promise((resolve, reject) => {
-                if (!this.ws || this.ws.readyState !== ws_1.default.OPEN) {
-                    reject(new Error('WebSocket not connected'));
-                    return;
-                }
-                const id = this.nextId++;
-                const message = { id, method, params };
-                this.pendingRequests.set(id, {
-                    resolve,
-                    reject,
-                    timestamp: Date.now()
+    // ── Internals ─────────────────────────────────────────────────
+    subscribe(method, params, handler) {
+        const localId = this.nextLocalId++;
+        const entry = { method, params, handler };
+        this.subs.set(localId, entry);
+        this.ensureConnected().then(() => this.sendSub(localId, entry));
+        return localId;
+    }
+    async ensureConnected() {
+        if (this.ws?.readyState === WS_OPEN)
+            return;
+        await this.connect();
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            const WsCtor = getWsConstructor();
+            const ws = new WsCtor(this.cfg.endpoint);
+            this.ws = ws;
+            // ── Node.js `ws` — uses EventEmitter-style `.on()` ──────
+            if (typeof ws.on === 'function') {
+                ws.on('open', () => {
+                    this.reconnectAttempts = 0;
+                    this.startPing();
+                    resolve();
                 });
-                this.ws.send(JSON.stringify(message));
-                this.metrics.messagesSent++;
-                // Timeout handler
-                setTimeout(() => {
-                    const request = this.pendingRequests.get(id);
-                    if (request) {
-                        this.pendingRequests.delete(id);
-                        request.reject(new Error(`Request ${id} timeout`));
+                ws.on('message', (raw) => {
+                    try {
+                        const msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString());
+                        this.handleMessage(msg);
                     }
-                }, 30000);
-            });
-        };
-        if (this.circuitBreaker) {
-            return this.circuitBreaker.execute(executeRequest, () => Promise.reject(new Error('Circuit breaker fallback')));
-        }
-        return executeRequest();
-    }
-    /**
-     *  Message handler
-     */
-    handleMessage(data) {
-        try {
-            const message = JSON.parse(data.toString());
-            this.metrics.messagesReceived++;
-            // Handle subscription updates
-            if (message.subscription !== undefined) {
-                const subscription = this.subscriptions.get(message.subscription);
-                if (subscription) {
-                    subscription.lastUpdate = Date.now();
-                    subscription.callback(message.result);
-                }
-                return;
+                    catch { /* ignore malformed */ }
+                });
+                ws.on('close', () => {
+                    this.stopPing();
+                    if (this.cfg.autoReconnect)
+                        this.scheduleReconnect();
+                });
+                ws.on('error', (err) => {
+                    if (this.ws === ws && ws.readyState !== WS_OPEN)
+                        reject(err);
+                });
             }
-            // Handle request responses
-            if (message.id !== undefined) {
-                const request = this.pendingRequests.get(message.id);
-                if (request) {
-                    this.pendingRequests.delete(message.id);
-                    // Calculate latency
-                    const latency = Date.now() - request.timestamp;
-                    this.metrics.lastLatency = latency;
-                    this.metrics.averageLatency = (this.metrics.averageLatency + latency) / 2;
-                    if (message.error) {
-                        request.reject(new Error(message.error.message || 'WebSocket request failed'));
+            // ── Browser native WebSocket — uses `.addEventListener()` ─
+            else if (typeof ws.addEventListener === 'function') {
+                ws.addEventListener('open', () => {
+                    this.reconnectAttempts = 0;
+                    this.startPing();
+                    resolve();
+                });
+                ws.addEventListener('message', (evt) => {
+                    try {
+                        const data = typeof evt === 'string' ? evt : (evt.data ?? evt);
+                        const msg = JSON.parse(typeof data === 'string' ? data : String(data));
+                        this.handleMessage(msg);
                     }
-                    else {
-                        request.resolve(message.result);
+                    catch { /* ignore malformed */ }
+                });
+                ws.addEventListener('close', () => {
+                    this.stopPing();
+                    if (this.cfg.autoReconnect)
+                        this.scheduleReconnect();
+                });
+                ws.addEventListener('error', () => {
+                    if (this.ws === ws && ws.readyState !== WS_OPEN) {
+                        reject(new Error('WebSocket connection failed'));
                     }
-                }
-            }
-        }
-        catch (error) {
-            console.error('❌ Failed to parse WebSocket message:', error);
-        }
-    }
-    /**
-     *  Auto-reconnect with exponential backoff
-     */
-    handleDisconnect(code, reason) {
-        this.connectionState = 'disconnected';
-        this.stopHeartbeat();
-        if (this.isDestroyed)
-            return;
-        console.log(`🔌 WebSocket disconnected: ${code} - ${reason}`);
-        if (this.config.autoReconnect && this.reconnectAttempts < this.config.maxReconnectAttempts) {
-            this.connectionState = 'reconnecting';
-            const delay = this.config.reconnectDelay * Math.pow(2, this.reconnectAttempts);
-            console.log(` Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts + 1})`);
-            setTimeout(() => {
-                this.reconnectAttempts++;
-                this.metrics.reconnectCount++;
-                this.connect()
-                    .then(() => this.resubscribeAll())
-                    .catch((error) => {
-                    console.error('❌ Reconnection failed:', error);
                 });
-            }, delay);
-        }
-    }
-    /**
-     *  Resubscribe all subscriptions
-     */
-    async resubscribeAll() {
-        const subscriptions = Array.from(this.subscriptions.entries());
-        for (const [oldId, subscription] of subscriptions) {
-            try {
-                const newId = await this.request(subscription.method, subscription.params);
-                // Update subscription ID
-                this.subscriptions.delete(oldId);
-                this.subscriptions.set(newId, subscription);
-                console.log(`✅ Resubscribed: ${subscription.method} (${oldId} → ${newId})`);
-            }
-            catch (error) {
-                console.error(`❌ Failed to resubscribe ${subscription.method}:`, error);
-                this.subscriptions.delete(oldId);
             }
-        }
+        });
     }
-    /**
-     *  Heartbeat system
-     */
-    startHeartbeat() {
-        this.heartbeatTimer = setInterval(async () => {
-            if (this.ws?.readyState === ws_1.default.OPEN) {
-                try {
-                    await this.request('ping');
-                }
-                catch (error) {
-                    console.warn(' Heartbeat failed:', error);
+    handleMessage(msg) {
+        if (msg.id != null && msg.result != null && typeof msg.result === 'number') {
+            for (const [, entry] of this.subs) {
+                if (!entry.id) {
+                    entry.id = msg.result;
+                    break;
                 }
             }
-        }, this.config.heartbeatInterval);
-    }
-    stopHeartbeat() {
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = undefined;
+            return;
         }
-    }
-    /**
-     *  Filter matching logic
-     */
-    matchesFilters(data, filters) {
-        for (const [key, value] of Object.entries(filters)) {
-            if (!this.matchesFilter(data, key, value)) {
-                return false;
+        if (msg.method && msg.params?.subscription != null) {
+            for (const entry of this.subs.values()) {
+                if (entry.id === msg.params.subscription) {
+                    entry.handler(msg.params);
+                    return;
+                }
             }
         }
-        return true;
     }
-    matchesFilter(data, key, value) {
-        const keys = key.split('.');
-        let current = data;
-        for (const k of keys) {
-            if (current == null || typeof current !== 'object') {
-                return false;
-            }
-            current = current[k];
-        }
-        if (Array.isArray(value)) {
-            return value.includes(current);
-        }
-        return current === value;
+    sendSub(localId, entry) {
+        this.sendJson({ jsonrpc: '2.0', id: localId, method: entry.method, params: entry.params });
     }
-    /**
-     * 🔧 Initialize advanced features
-     */
-    initializeAdvancedFeatures() {
-        if (this.config.enableSmartCaching) {
-            this.smartCache = new smart_caching_1.SmartCaching({
-                strategy: 'balanced',
-                maxSize: 5000,
-                enablePredictive: false,
-                enableDistributed: false,
-                compressionLevel: 'low'
-            });
-        }
-        if (this.config.enableCircuitBreaker) {
-            this.circuitBreaker = new circuit_breaker_1.CircuitBreaker({
-                failureThreshold: 3,
-                timeout: 30000,
-                retryInterval: 15000,
-                monitorWindow: 60000,
-                enableFallback: true
-            });
+    sendJson(data) {
+        if (this.ws?.readyState === WS_OPEN) {
+            this.ws.send(JSON.stringify(data));
         }
     }
-    /**
-     *  Get real-time metrics
-     */
-    getMetrics() {
-        return {
-            connection: {
-                state: this.connectionState,
-                reconnectAttempts: this.reconnectAttempts,
-                reconnectCount: this.metrics.reconnectCount
-            },
-            performance: {
-                latency: {
-                    last: this.metrics.lastLatency,
-                    average: this.metrics.averageLatency
-                },
-                throughput: {
-                    messagesReceived: this.metrics.messagesReceived,
-                    messagesSent: this.metrics.messagesSent
+    scheduleReconnect() {
+        if (this.reconnecting)
+            return;
+        if (this.reconnectAttempts >= this.cfg.maxReconnectAttempts)
+            return;
+        this.reconnecting = true;
+        this.reconnectAttempts++;
+        setTimeout(async () => {
+            this.reconnecting = false;
+            try {
+                await this.connect();
+                for (const [localId, entry] of this.subs) {
+                    entry.id = undefined;
+                    this.sendSub(localId, entry);
                 }
-            },
-            subscriptions: {
-                active: this.metrics.subscriptionsActive,
-                total: this.subscriptions.size
-            },
-            cache: this.smartCache?.getAdvancedStats() || null,
-            circuitBreaker: this.circuitBreaker?.getAdvancedMetrics() || null
-        };
-    }
-    /**
-     *  Advanced configuration methods
-     */
-    setFilter(subscriptionId, filters) {
-        const subscription = this.subscriptions.get(subscriptionId);
-        if (subscription) {
-            subscription.options.customFilters = filters;
-        }
+            }
+            catch { /* will retry on next close */ }
+        }, this.cfg.reconnectIntervalMs * Math.min(this.reconnectAttempts, 10));
     }
-    enableCacheForSubscription(subscriptionId, enable) {
-        const subscription = this.subscriptions.get(subscriptionId);
-        if (subscription) {
-            subscription.options.enableCache = enable;
+    startPing() {
+        this.stopPing();
+        // Browser WebSocket does not expose .ping() — the browser handles
+        // TCP keep-alive automatically. Only Node.js `ws` has .ping().
+        if (typeof this.ws?.ping === 'function') {
+            this.pingTimer = setInterval(() => {
+                if (this.ws?.readyState === WS_OPEN && typeof this.ws.ping === 'function') {
+                    this.ws.ping();
+                }
+            }, this.cfg.pingIntervalMs);
         }
     }
-    /**
-     *  Health monitoring
-     */
-    isHealthy() {
-        const isConnected = this.connectionState === 'connected';
-        const hasActiveSubscriptions = this.subscriptions.size > 0;
-        const lowLatency = this.metrics.averageLatency < 1000;
-        const circuitBreakerOk = !this.circuitBreaker ||
-            this.circuitBreaker.getAdvancedMetrics().state !== 'open';
-        return isConnected && (!hasActiveSubscriptions || lowLatency) && circuitBreakerOk;
-    }
-    /**
-     *  Cleanup
-     */
-    async disconnect() {
-        this.isDestroyed = true;
-        this.stopHeartbeat();
-        if (this.ws) {
-            this.ws.close(1000, 'Client disconnect');
+    stopPing() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = undefined;
         }
-        this.subscriptions.clear();
-        this.pendingRequests.clear();
-        this.smartCache?.clear();
-    }
-    /**
-     *  Manual reconnect
-     */
-    async reconnect() {
-        await this.disconnect();
-        this.isDestroyed = false;
-        this.reconnectAttempts = 0;
-        await this.connect();
     }
 }
-exports.WebSocketClient = WebSocketClient;
+exports.WsClient = WsClient;
 //# sourceMappingURL=client.js.map