nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/__mocks__/wsMock.d.ts

@@ -0,0 +1,26 @@
+/// <reference types="node" />
+/// <reference types="node" />
+declare class MockWebSocket {
+    static OPEN: number;
+    static CLOSED: number;
+    static CONNECTING: number;
+    static CLOSING: number;
+    url: string;
+    readyState: number;
+    onopen: ((event: Event) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    eventListeners: {
+        [type: string]: ((data: Buffer) => void)[];
+    };
+    constructor(url: string | URL, _protocols?: string | string[]);
+    send(_data: unknown): void;
+    close(): void;
+    simulateOpen(): void;
+    simulateMessage(data: unknown): void;
+    simulateClose(): void;
+    addEventListener(type: string, listener: (data: Buffer) => void): void;
+    dispatchEvent(event: Event | CloseEvent | MessageEvent): boolean;
+}
+declare const mockWebSocket: MockWebSocket;
+export default mockWebSocket;

package/dist/__mocks__/wsMock.js

@@ -0,0 +1,120 @@
+class MockWebSocket {
+    constructor(url, _protocols) {
+        this.onopen = null;
+        this.onclose = null;
+        this.onmessage = null;
+        this.eventListeners = {};
+        this.url = typeof url === 'string' ? url : url.toString();
+        this.readyState = MockWebSocket.CONNECTING;
+    }
+    send(_data) {
+        // Implementation not needed for these tests
+    }
+    close() {
+        this.readyState = MockWebSocket.CLOSING;
+        this.simulateClose();
+    }
+    simulateOpen() {
+        this.readyState = MockWebSocket.OPEN;
+        const event = new MockEvent('open');
+        if (this.onopen)
+            this.onopen(event);
+    }
+    simulateMessage(data) {
+        const messageData = Buffer.from(JSON.stringify(data));
+        const listeners = this.eventListeners['message'] || [];
+        listeners.forEach(listener => listener(messageData));
+    }
+    simulateClose() {
+        this.readyState = MockWebSocket.CLOSED;
+        const event = new MockCloseEvent('close');
+        if (this.onclose)
+            this.onclose(event);
+    }
+    addEventListener(type, listener) {
+        if (!this.eventListeners[type]) {
+            this.eventListeners[type] = [];
+        }
+        this.eventListeners[type].push(listener);
+    }
+    dispatchEvent(event) {
+        if (event.type === 'close' && this.onclose) {
+            this.onclose(event);
+        }
+        else if (event.type === 'open' && this.onopen) {
+            this.onopen(event);
+        }
+        else if (event.type === 'message' && this.onmessage) {
+            this.onmessage(event);
+        }
+        return true;
+    }
+}
+MockWebSocket.OPEN = 1;
+MockWebSocket.CLOSED = 3;
+MockWebSocket.CONNECTING = 0;
+MockWebSocket.CLOSING = 2;
+// Set up the global WebSocket with proper typing
+global.WebSocket = MockWebSocket;
+class MockEvent {
+    constructor(type) {
+        this.NONE = 0;
+        this.CAPTURING_PHASE = 1;
+        this.AT_TARGET = 2;
+        this.BUBBLING_PHASE = 3;
+        this.target = null;
+        this.currentTarget = null;
+        this.eventPhase = 0;
+        this.bubbles = false;
+        this.cancelable = false;
+        this.defaultPrevented = false;
+        this.composed = false;
+        this.timeStamp = Date.now();
+        this.srcElement = null;
+        this.returnValue = true;
+        this.cancelBubble = false;
+        this.isTrusted = true;
+        this.type = type;
+    }
+    preventDefault() { }
+    stopPropagation() { }
+    stopImmediatePropagation() { }
+    composedPath() { return []; }
+    initEvent(_type, _bubbles, _cancelable) { }
+}
+class MockCloseEvent extends MockEvent {
+    constructor(type) {
+        super(type);
+        this.code = 1000;
+        this.reason = '';
+        this.wasClean = true;
+    }
+}
+/*
+class MockMessageEvent extends MockEvent implements MessageEvent {
+  readonly data: unknown;
+  readonly origin: string = '';
+  readonly lastEventId: string = '';
+  readonly source: Window | MessagePort | ServiceWorker | null = null;
+  readonly ports: ReadonlyArray<MessagePort> = [];
+
+  constructor(data: unknown) {
+    super('message');
+    this.data = data;
+  }
+
+  initMessageEvent(
+    _type: string,
+    _bubbles?: boolean,
+    _cancelable?: boolean,
+    _data: unknown = null,
+    _origin: string = '',
+    _lastEventId: string = '',
+    _source: Window | MessagePort | ServiceWorker | null = null,
+    _ports: MessagePort[] = []
+  ): void {}
+}
+*/
+// Export an instance of MockWebSocket
+const mockWebSocket = new MockWebSocket('ws://test.com');
+export default mockWebSocket;

package/dist/client.d.ts

@@ -1,6 +1,27 @@
 /// <reference types="node" />
 import { EventEmitter } from 'events';
 import type { NostrWSOptions, NostrWSMessage } from './types/index.js';
+/**
+ * WebSocket client implementation for Nostr protocol communication
+ * Extends EventEmitter to provide event-based message handling
+ *
+ * @extends EventEmitter
+ * @example
+ * ```typescript
+ * const client = new NostrWSClient('wss://relay.example.com', {
+ *   logger: console,
+ *   heartbeatInterval: 30000,
+ *   handlers: {
+ *     message: async (msg) => console.log('Received:', msg),
+ *     error: (err) => console.error('Error:', err),
+ *     close: () => console.log('Connection closed')
+ *   }
+ * });
+ *
+ * await client.connect();
+ * client.send({ type: 'EVENT', data: { ... } });
+ * ```
+ */
 export declare class NostrWSClient extends EventEmitter {
     private url;
     private ws;
@@ -10,15 +31,99 @@ export declare class NostrWSClient extends EventEmitter {
     private reconnectAttempts;
     private messageQueue;
     private clientId;
+    /**
+     * Creates a new NostrWSClient instance
+     *
+     * @param {string} url - The WebSocket server URL to connect to
+     * @param {Partial<NostrWSOptions>} options - Configuration options
+     * @param {number} [options.heartbeatInterval=30000] - Interval for sending heartbeat messages in milliseconds
+     * @param {object} options.logger - Logger instance (required)
+     * @param {Function} [options.WebSocketImpl=WebSocket] - WebSocket implementation to use
+     * @param {object} [options.handlers] - Event handlers
+     * @param {Function} [options.handlers.message] - Message handler function
+     * @param {Function} [options.handlers.error] - Error handler function
+     * @param {Function} [options.handlers.close] - Connection close handler function
+     * @throws {Error} If logger is not provided
+     */
     constructor(url: string, options?: Partial<NostrWSOptions>);
+    /**
+     * Establishes a connection to the WebSocket server
+     *
+     * @example
+     * ```typescript
+     * client.connect();
+     * ```
+     */
     connect(): void;
+    /**
+     * Sets up event handlers for the WebSocket connection
+     *
+     * @private
+     */
     private setupEventHandlers;
+    /**
+     * Starts sending heartbeat messages at the specified interval
+     *
+     * @private
+     */
     private startHeartbeat;
+    /**
+     * Stops sending heartbeat messages
+     *
+     * @private
+     */
     private stopHeartbeat;
+    /**
+     * Handles reconnecting to the WebSocket server after a disconnection
+     *
+     * @private
+     */
     private handleReconnect;
+    /**
+     * Subscribes to a channel with optional filter
+     *
+     * @param {string} channel - Channel name
+     * @param {unknown} [filter] - Filter data
+     * @example
+     * ```typescript
+     * client.subscribe('channel-name', { ...filterData });
+     * ```
+     */
     subscribe(channel: string, filter?: unknown): void;
+    /**
+     * Unsubscribes from a channel
+     *
+     * @param {string} channel - Channel name
+     * @example
+     * ```typescript
+     * client.unsubscribe('channel-name');
+     * ```
+     */
     unsubscribe(channel: string): void;
+    /**
+     * Flushes the message queue by sending pending messages
+     *
+     * @private
+     */
     private flushMessageQueue;
+    /**
+     * Sends a message to the WebSocket server
+     *
+     * @param {NostrWSMessage} message - Message to send
+     * @returns {Promise<void>}
+     * @example
+     * ```typescript
+     * client.send({ type: 'EVENT', data: { ... } });
+     * ```
+     */
     send(message: NostrWSMessage): Promise<void>;
+    /**
+     * Closes the WebSocket connection
+     *
+     * @example
+     * ```typescript
+     * client.close();
+     * ```
+     */
     close(): void;
 }

package/dist/client.js

@@ -1,7 +1,42 @@
 import { v4 as uuidv4 } from 'uuid';
 import WebSocket from 'ws';
 import { EventEmitter } from 'events';
+/**
+ * WebSocket client implementation for Nostr protocol communication
+ * Extends EventEmitter to provide event-based message handling
+ *
+ * @extends EventEmitter
+ * @example
+ * ```typescript
+ * const client = new NostrWSClient('wss://relay.example.com', {
+ *   logger: console,
+ *   heartbeatInterval: 30000,
+ *   handlers: {
+ *     message: async (msg) => console.log('Received:', msg),
+ *     error: (err) => console.error('Error:', err),
+ *     close: () => console.log('Connection closed')
+ *   }
+ * });
+ *
+ * await client.connect();
+ * client.send({ type: 'EVENT', data: { ... } });
+ * ```
+ */
 export class NostrWSClient extends EventEmitter {
+    /**
+     * Creates a new NostrWSClient instance
+     *
+     * @param {string} url - The WebSocket server URL to connect to
+     * @param {Partial<NostrWSOptions>} options - Configuration options
+     * @param {number} [options.heartbeatInterval=30000] - Interval for sending heartbeat messages in milliseconds
+     * @param {object} options.logger - Logger instance (required)
+     * @param {Function} [options.WebSocketImpl=WebSocket] - WebSocket implementation to use
+     * @param {object} [options.handlers] - Event handlers
+     * @param {Function} [options.handlers.message] - Message handler function
+     * @param {Function} [options.handlers.error] - Error handler function
+     * @param {Function} [options.handlers.close] - Connection close handler function
+     * @throws {Error} If logger is not provided
+     */
     constructor(url, options = {}) {
         super();
         this.url = url;
@@ -25,6 +60,14 @@ export class NostrWSClient extends EventEmitter {
             }
         };
     }
+    /**
+     * Establishes a connection to the WebSocket server
+     *
+     * @example
+     * ```typescript
+     * client.connect();
+     * ```
+     */
     connect() {
         if (this.ws) {
             this.options.logger.info('WebSocket connection already exists');
@@ -41,6 +84,11 @@ export class NostrWSClient extends EventEmitter {
             this.handleReconnect();
         }
     }
+    /**
+     * Sets up event handlers for the WebSocket connection
+     *
+     * @private
+     */
     setupEventHandlers() {
         if (!this.ws)
             return;
@@ -81,6 +129,11 @@ export class NostrWSClient extends EventEmitter {
             }
         });
     }
+    /**
+     * Starts sending heartbeat messages at the specified interval
+     *
+     * @private
+     */
     startHeartbeat() {
         if (this.heartbeatInterval)
             return;
@@ -90,12 +143,22 @@ export class NostrWSClient extends EventEmitter {
             }
         }, this.options.heartbeatInterval || 30000);
     }
+    /**
+     * Stops sending heartbeat messages
+     *
+     * @private
+     */
     stopHeartbeat() {
         if (this.heartbeatInterval) {
             clearInterval(this.heartbeatInterval);
             this.heartbeatInterval = null;
         }
     }
+    /**
+     * Handles reconnecting to the WebSocket server after a disconnection
+     *
+     * @private
+     */
     handleReconnect() {
         if (this.reconnectTimeout)
             return;
@@ -106,18 +169,42 @@ export class NostrWSClient extends EventEmitter {
             this.emit('reconnect');
         }, 5000);
     }
+    /**
+     * Subscribes to a channel with optional filter
+     *
+     * @param {string} channel - Channel name
+     * @param {unknown} [filter] - Filter data
+     * @example
+     * ```typescript
+     * client.subscribe('channel-name', { ...filterData });
+     * ```
+     */
     subscribe(channel, filter) {
         this.send({
             type: 'subscribe',
             data: { channel, filter }
         });
     }
+    /**
+     * Unsubscribes from a channel
+     *
+     * @param {string} channel - Channel name
+     * @example
+     * ```typescript
+     * client.unsubscribe('channel-name');
+     * ```
+     */
     unsubscribe(channel) {
         this.send({
             type: 'unsubscribe',
             data: { channel }
         });
     }
+    /**
+     * Flushes the message queue by sending pending messages
+     *
+     * @private
+     */
     flushMessageQueue() {
         while (this.messageQueue.length > 0 && this.ws?.readyState === WebSocket.OPEN) {
             const message = this.messageQueue.shift();
@@ -126,6 +213,16 @@ export class NostrWSClient extends EventEmitter {
             }
         }
     }
+    /**
+     * Sends a message to the WebSocket server
+     *
+     * @param {NostrWSMessage} message - Message to send
+     * @returns {Promise<void>}
+     * @example
+     * ```typescript
+     * client.send({ type: 'EVENT', data: { ... } });
+     * ```
+     */
     async send(message) {
         message.id = message.id || uuidv4();
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -140,6 +237,14 @@ export class NostrWSClient extends EventEmitter {
             this.handleReconnect();
         }
     }
+    /**
+     * Closes the WebSocket connection
+     *
+     * @example
+     * ```typescript
+     * client.close();
+     * ```
+     */
     close() {
         this.stopHeartbeat();
         if (this.reconnectTimeout) {

package/dist/core/client.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @file WebSocket client implementation
+ * @module core/client
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import { NostrWSMessage, NostrWSOptions, ConnectionState } from '../types';
+/**
+ * WebSocket client implementation for Nostr protocol communication
+ * Extends EventEmitter to provide event-based message handling
+ */
+export declare class NostrWSClient extends EventEmitter {
+    private readonly url;
+    private ws;
+    private state;
+    private messageQueue;
+    private reconnectTimeout;
+    private heartbeatInterval;
+    private heartbeatTimeout;
+    private missedHeartbeats;
+    private reconnectAttempts;
+    private subscriptions;
+    private readonly clientId;
+    private readonly options;
+    constructor(url: string, options?: Partial<NostrWSOptions>);
+    /**
+     * Gets the current connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Updates the connection state and notifies handlers
+     */
+    private setState;
+    /**
+     * Establishes a connection to the WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Sets up event handlers for the WebSocket connection
+     */
+    private setupEventHandlers;
+    /**
+     * Starts the heartbeat mechanism
+     */
+    private startHeartbeat;
+    /**
+     * Handles heartbeat responses
+     */
+    private handleHeartbeatResponse;
+    /**
+     * Stops the heartbeat mechanism
+     */
+    private stopHeartbeat;
+    /**
+     * Handles connection errors
+     */
+    private handleConnectionError;
+    /**
+     * Handles disconnection and cleanup
+     */
+    private handleDisconnection;
+    /**
+     * Initiates reconnection with exponential backoff
+     */
+    private reconnect;
+    /**
+     * Subscribes to a channel with optional filter
+     */
+    subscribe(channel: string, filter?: unknown): void;
+    /**
+     * Resubscribes to all active subscriptions
+     */
+    private resubscribeAll;
+    /**
+     * Unsubscribes from a channel
+     */
+    unsubscribe(channel: string): void;
+    /**
+     * Flushes the message queue by sending pending messages
+     */
+    private flushMessageQueue;
+    /**
+     * Sends a message immediately without queueing
+     */
+    private sendImmediate;
+    /**
+     * Sends a message to the WebSocket server
+     */
+    send(message: NostrWSMessage): Promise<void>;
+    /**
+     * Closes the WebSocket connection
+     */
+    close(): void;
+}