nostr-websocket-utils 0.2.4 → 0.2.5

package/README.md

@@ -1,25 +1,23 @@
-# Nostr Websocket Utils
+# nostr-websocket-utils
 
-[![npm version](https://img.shields.io/npm/v/nostr-websocket-utils.svg)](https://www.npmjs.com/package/nostr-websocket-utils)
-[![License](https://img.shields.io/npm/l/nostr-websocket-utils.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/@humanjavaenterprises/nostr-websocket-utils.svg)](https://www.npmjs.com/package/@humanjavaenterprises/nostr-websocket-utils)
+[![License](https://img.shields.io/npm/l/@humanjavaenterprises/nostr-websocket-utils.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/blob/main/LICENSE)
 [![Build Status](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/workflows/CI/badge.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/actions)
+[![Documentation](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/workflows/Documentation/badge.svg)](https://humanjavaenterprises.github.io/nostr-websocket-utils/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 
-A TypeScript library providing WebSocket utilities for Nostr applications, focusing on robust connection handling, automatic reconnection, and channel-based messaging. This library has been streamlined to remove any DOM-related code, enhancing performance and maintainability.
+A TypeScript library for building Nostr protocol WebSocket clients and servers.
 
 ## Features
 
-- 🔄 Automatic reconnection with configurable attempts
-- 💓 Heartbeat monitoring with configurable intervals
-- 📨 Message queueing during disconnections
-- 📢 Channel-based broadcasting with filtered subscriptions
-- 🔒 Type-safe message handling with required handlers
-- 📝 Built-in logging with Winston integration
-- 🛡️ Comprehensive error handling and validation
-- 🧪 100% test coverage with Jest
-- 📦 Zero DOM dependencies
-- 🔍 Full TypeScript type safety
+- 🚀 Full Nostr protocol support
+- 🔒 Secure WebSocket connections
+- ♥️ Heartbeat mechanism for connection health
+- 🔄 Automatic reconnection handling
+- 📝 Comprehensive logging
+- 🎯 Type-safe message handling
+- 📦 Easy to use API
 
 ## Installation
 
@@ -27,118 +25,108 @@ A TypeScript library providing WebSocket utilities for Nostr applications, focus
 npm install nostr-websocket-utils
 ```
 
-## Breaking Changes in v0.2.4
+## Quick Start
 
-- 🆕 Added dedicated Nostr WebSocket server implementation
-- 📝 Enhanced TypeScript type definitions for Nostr messages
-- 🔄 Improved message handling with strict type checking
-- 🧪 Added comprehensive test suite for Nostr server
-- 🛡️ Strengthened type safety with `unknown` types
-- 🔌 Added support for Nostr EVENT and REQ messages
+### Creating a Nostr WebSocket Client
 
-## Usage
+```typescript
+import { NostrWSClient } from 'nostr-websocket-utils';
+
+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();
+```
 
-### Nostr Server Example
+### Creating a Nostr WebSocket Server
 
 ```typescript
-import { NostrWSServer, createWSServer } from 'nostr-websocket-utils';
-import { NostrWSMessageType, NostrWSEvent } from 'nostr-websocket-utils/types/nostr';
+import { createNostrServer } from '@humanjavaenterprises/nostr-websocket-utils';
 
-// Create Nostr WebSocket server
-const server = createWSServer({
-  port: 8080,
-  heartbeatInterval: 30000, // Optional: 30 seconds
+const server = await createNostrServer(8080, {
+  logger: console,
+  heartbeatInterval: 30000,
   handlers: {
-    // Required: Handle incoming messages
-    message: async (socket, message) => {
-      switch (message[0]) {
-        case NostrWSMessageType.EVENT:
-          const event = message[1] as NostrWSEvent;
-          // Handle Nostr event
-          break;
-        case NostrWSMessageType.REQ:
-          const [_type, subscriptionId, filter] = message;
-          // Handle subscription request
-          break;
-      }
-    },
-    // Optional: Handle errors
-    error: (socket, error) => {
-      console.error('WebSocket error:', error);
-    },
-    // Optional: Handle client disconnection
-    close: (socket) => {
-      console.info('Client disconnected');
+    message: async (ws, msg) => {
+      console.log('Received message:', msg);
+      // Handle the message
     }
   }
 });
-
-// Start listening
-server.listen();
 ```
 
-### Types
+## Documentation
+
+Comprehensive API documentation is available in our [documentation site](https://humanjavaenterprises.github.io/nostr-websocket-utils/). Here's what you'll find:
+
+### Core Components
+- [NostrWSClient](docs/classes/NostrWSClient.md) - WebSocket client implementation
+- [NostrWSServer](docs/classes/NostrWSServer.md) - WebSocket server implementation
+- [NostrServer](docs/classes/NostrServer.md) - High-level Nostr server
+
+### Types and Interfaces
+- [NostrWSMessage](docs/interfaces/NostrWSMessage.md) - Message structure
+- [NostrWSOptions](docs/interfaces/NostrWSOptions.md) - Configuration options
+- [NostrWSSubscription](docs/interfaces/NostrWSSubscription.md) - Subscription interface
+- [ExtendedWebSocket](docs/interfaces/ExtendedWebSocket.md) - Enhanced WebSocket interface
+
+### Utility Functions
+- [createServer](docs/functions/createServer.md) - Server creation helper
+- [getLogger](docs/functions/getLogger.md) - Logging utility
+
+### Type Definitions
+- [MessageType](docs/enumerations/NostrWSMessageType.md) - Message type enumeration
+- [Global Types](docs/globals.md) - Global type definitions
+
+## Examples
+
+### Subscribe to a Channel
 
 ```typescript
-// Nostr Event Type
-interface NostrWSEvent {
-  id: string;
-  pubkey: string;
-  created_at: number;
-  kind: number;
-  tags: string[][];
-  content: string;
-  sig: string;
-}
-
-// Nostr Filter Type
-interface NostrWSFilter {
-  ids?: string[];
-  authors?: string[];
-  kinds?: number[];
-  '#e'?: string[];
-  '#p'?: string[];
-  since?: number;
-  until?: number;
-  limit?: number;
-}
-
-// Message Types
-enum NostrWSMessageType {
-  EVENT = 'EVENT',
-  REQ = 'REQ',
-  CLOSE = 'CLOSE',
-  NOTICE = 'NOTICE',
-  AUTH = 'AUTH',
-  EOSE = 'EOSE'
-}
+client.subscribe('my-channel', {
+  filter: {
+    authors: ['pubkey1', 'pubkey2'],
+    kinds: [1]
+  }
+});
 ```
 
-## Advanced Configuration
-
-### Server Options
+### Broadcast a Message
 
 ```typescript
-interface NostrWSServerOptions {
-  port: number;
-  heartbeatInterval?: number;
-  maxPayloadSize?: number;
-  cors?: {
-    origin?: string | string[];
-    methods?: string[];
-  };
-  handlers: {
-    message: MessageHandler;
-    error?: ErrorHandler;
-    close?: CloseHandler;
-  };
-}
+server.broadcast({
+  type: 'event',
+  data: {
+    content: 'Hello everyone!',
+    kind: 1
+  }
+});
 ```
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
 
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Related Projects
+
+- [nostr-protocol](https://github.com/nostr-protocol/nostr)
+- [nostr-tools](https://github.com/nbd-wtf/nostr-tools)
+
+## Support
+
+If you have any questions or need help, please:
+
+1. Check the [documentation](https://humanjavaenterprises.github.io/nostr-websocket-utils/)
+2. Open an [issue](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/issues)
+3. Join our [Discord community](https://discord.gg/your-discord)

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/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @file Main entry point for the nostr-websocket-utils library
+ * @module nostr-websocket-utils
+ */
 export { NostrWSClient } from './client.js';
 export { NostrWSServer } from './server.js';
 export { NostrWSServer as NostrServer } from './nostr-server.js';

package/dist/index.js

@@ -1,3 +1,7 @@
+/**
+ * @file Main entry point for the nostr-websocket-utils library
+ * @module nostr-websocket-utils
+ */
 export { NostrWSClient } from './client.js';
 export { NostrWSServer } from './server.js';
 export { NostrWSServer as NostrServer } from './nostr-server.js';

package/dist/nostr-server.d.ts

@@ -1,8 +1,31 @@
 import { NostrWSServerOptions } from './types/nostr';
+/**
+ * Represents a Nostr WebSocket server
+ */
 export declare class NostrWSServer {
+    /**
+     * The underlying WebSocket server instance
+     */
     private server;
+    /**
+     * Logger instance for this server
+     */
     private logger;
+    /**
+     * Creates a new Nostr WebSocket server instance
+     *
+     * @param {NostrWSServerOptions} options - Server configuration options
+     */
     constructor(options: NostrWSServerOptions);
+    /**
+     * Closes the WebSocket server
+     */
     close(): void;
 }
+/**
+ * Creates a new Nostr WebSocket server instance
+ *
+ * @param {NostrWSServerOptions} options - Server configuration options
+ * @returns {NostrWSServer} The created server instance
+ */
 export declare function createWSServer(options: NostrWSServerOptions): NostrWSServer;

package/dist/nostr-server.js

@@ -1,15 +1,36 @@
 import { Server as WebSocketServer } from 'ws';
 import { getLogger } from './utils/logger';
+/**
+ * Represents a Nostr WebSocket server
+ */
 export class NostrWSServer {
+    /**
+     * Creates a new Nostr WebSocket server instance
+     *
+     * @param {NostrWSServerOptions} options - Server configuration options
+     */
     constructor(options) {
+        /**
+         * Logger instance for this server
+         */
         this.logger = getLogger('NostrWSServer');
         this.server = new WebSocketServer({ port: options.port });
+        /**
+         * Handles incoming WebSocket connections
+         *
+         * @param {NostrWSSocket} socket - The connected WebSocket client
+         */
         this.server.on('connection', (socket) => {
             socket.subscriptions = new Set();
             socket.isAlive = true;
             if (options.onConnection) {
                 options.onConnection(socket);
             }
+            /**
+             * Handles incoming messages from the client
+             *
+             * @param {Buffer | ArrayBuffer | Buffer[]} data - The incoming message data
+             */
             const handleMessage = async (data) => {
                 try {
                     const message = JSON.parse(data.toString());
@@ -24,11 +45,19 @@ export class NostrWSServer {
                 }
             };
             socket.on('message', handleMessage);
+            /**
+             * Handles client disconnections
+             */
             socket.on('close', () => {
                 if (options.handlers?.close) {
                     options.handlers.close(socket);
                 }
             });
+            /**
+             * Handles WebSocket errors
+             *
+             * @param {Error} error - The error that occurred
+             */
             socket.on('error', (error) => {
                 if (options.handlers?.error) {
                     options.handlers.error(socket, error);
@@ -45,19 +74,34 @@ export class NostrWSServer {
                     socket.isAlive = false;
                     socket.ping();
                 }, options.heartbeatInterval);
+                /**
+                 * Handles WebSocket pong responses
+                 */
                 socket.on('pong', () => {
                     socket.isAlive = true;
                 });
+                /**
+                 * Handles client disconnections (again, to clear the interval)
+                 */
                 socket.on('close', () => {
                     clearInterval(interval);
                 });
             }
         });
     }
+    /**
+     * Closes the WebSocket server
+     */
     close() {
         this.server.close();
     }
 }
+/**
+ * Creates a new Nostr WebSocket server instance
+ *
+ * @param {NostrWSServerOptions} options - Server configuration options
+ * @returns {NostrWSServer} The created server instance
+ */
 export function createWSServer(options) {
     return new NostrWSServer(options);
 }

package/dist/server.d.ts

@@ -1,12 +1,16 @@
 /// <reference types="node" />
-import { EventEmitter } from 'events';
 import { WebSocketServer } from 'ws';
-import type { NostrWSOptions, NostrWSMessage, ExtendedWebSocket } from './types/index.js';
+import { EventEmitter } from 'events';
+import type { NostrWSOptions, NostrWSMessage } from './types/index.js';
+/**
+ * WebSocket server implementation for Nostr protocol
+ * Extends EventEmitter to provide event-based message handling
+ */
 export declare class NostrWSServer extends EventEmitter {
     private wss;
     private options;
+    private clients;
     private heartbeatInterval;
-    clients: Map<string, ExtendedWebSocket>;
     constructor(wss: WebSocketServer, options?: Partial<NostrWSOptions>);
     private setupServer;
     private handleConnection;
@@ -14,4 +18,10 @@ export declare class NostrWSServer extends EventEmitter {
     broadcast(message: NostrWSMessage): void;
     broadcastToChannel(channel: string, message: NostrWSMessage): void;
     close(): void;
+    /**
+     * Check if a client with the given ID exists
+     * @param clientId - The ID of the client to check
+     * @returns boolean indicating if the client exists
+     */
+    hasClient(clientId: string): boolean;
 }

package/dist/server.js

@@ -1,50 +1,59 @@
-import { EventEmitter } from 'events';
 import { WebSocket } from 'ws';
+import { EventEmitter } from 'events';
 import { v4 as uuidv4 } from 'uuid';
+/**
+ * WebSocket server implementation for Nostr protocol
+ * Extends EventEmitter to provide event-based message handling
+ */
 export class NostrWSServer extends EventEmitter {
     constructor(wss, options = {}) {
         super();
-        this.heartbeatInterval = null;
+        this.wss = null;
         this.clients = new Map();
+        this.heartbeatInterval = null;
         if (!options.logger) {
             throw new Error('Logger is required');
         }
-        if (!options.handlers?.message) {
-            throw new Error('Message handler is required');
-        }
+        this.wss = wss;
         this.options = {
-            heartbeatInterval: options.heartbeatInterval || 30000,
+            heartbeatInterval: 30000,
             logger: options.logger,
-            WebSocketImpl: options.WebSocketImpl || WebSocket,
+            WebSocketImpl: WebSocket,
+            ...options,
             handlers: {
-                message: options.handlers.message,
-                error: options.handlers.error || (() => { }),
-                close: options.handlers.close || (() => { })
-            }
+                message: async (_ws, _message) => { },
+                ...options.handlers,
+            },
         };
-        this.wss = wss;
         this.setupServer();
     }
     setupServer() {
+        if (!this.wss)
+            return;
         this.wss.on('connection', (ws) => {
-            this.handleConnection(ws);
+            const extWs = ws;
+            this.handleConnection(extWs);
         });
-        if (this.options.heartbeatInterval && this.options.heartbeatInterval > 0) {
+        if (this.options.heartbeatInterval) {
             this.startHeartbeat();
         }
     }
     handleConnection(ws) {
         ws.isAlive = true;
         ws.subscriptions = new Set();
-        ws.clientId = ws.clientId || uuidv4();
+        ws.clientId = uuidv4();
+        ws.messageQueue = [];
         this.clients.set(ws.clientId, ws);
         ws.on('message', async (data) => {
             try {
                 const message = JSON.parse(data.toString());
-                await this.options.handlers.message(ws, message);
+                if (this.options.handlers?.message) {
+                    await this.options.handlers.message(ws, message);
+                }
             }
             catch (error) {
-                if (this.options.handlers.error) {
+                this.options.logger.error('Error handling message:', error);
+                if (this.options.handlers?.error) {
                     this.options.handlers.error(ws, error);
                 }
             }
@@ -53,35 +62,39 @@ export class NostrWSServer extends EventEmitter {
             if (ws.clientId) {
                 this.clients.delete(ws.clientId);
             }
-            if (this.options.handlers.close) {
+            if (this.options.handlers?.close) {
                 this.options.handlers.close(ws);
             }
         });
         ws.on('error', (error) => {
-            if (ws.clientId) {
-                this.clients.delete(ws.clientId);
-            }
-            if (this.options.handlers.error) {
+            this.options.logger.error('WebSocket error:', error);
+            if (this.options.handlers?.error) {
                 this.options.handlers.error(ws, error);
             }
         });
     }
     startHeartbeat() {
+        if (this.heartbeatInterval)
+            return;
         this.heartbeatInterval = setInterval(() => {
-            this.wss.clients.forEach((ws) => {
-                const extWs = ws;
-                if (!extWs.isAlive) {
-                    extWs.terminate();
-                    return;
-                }
-                extWs.isAlive = false;
-                if (ws.readyState === WebSocket.OPEN) {
-                    ws.ping();
+            if (!this.wss)
+                return;
+            this.wss.clients.forEach((client) => {
+                const extClient = client;
+                if (extClient.isAlive === false) {
+                    if (extClient.clientId) {
+                        this.clients.delete(extClient.clientId);
+                    }
+                    return extClient.terminate();
                 }
+                extClient.isAlive = false;
+                extClient.ping();
             });
         }, this.options.heartbeatInterval);
     }
     broadcast(message) {
+        if (!this.wss)
+            return;
         this.wss.clients.forEach((client) => {
             if (client.readyState === WebSocket.OPEN) {
                 client.send(JSON.stringify(message));
@@ -89,17 +102,31 @@ export class NostrWSServer extends EventEmitter {
         });
     }
     broadcastToChannel(channel, message) {
+        if (!this.wss)
+            return;
         this.wss.clients.forEach((ws) => {
             const extWs = ws;
             if (extWs.readyState === WebSocket.OPEN && extWs.subscriptions?.has(channel)) {
-                ws.send(JSON.stringify(message));
+                extWs.send(JSON.stringify(message));
             }
         });
     }
     close() {
         if (this.heartbeatInterval) {
             clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
         }
-        this.wss.close();
+        if (this.wss) {
+            this.wss.close();
+            this.wss = null;
+        }
+    }
+    /**
+     * Check if a client with the given ID exists
+     * @param clientId - The ID of the client to check
+     * @returns boolean indicating if the client exists
+     */
+    hasClient(clientId) {
+        return this.clients.has(clientId);
     }
 }

package/dist/types/index.d.ts

@@ -1,58 +1,233 @@
 import type { WebSocket } from 'ws';
+/**
+ * Type of message that can be sent through the WebSocket connection
+ * @type {('subscribe' | 'unsubscribe' | 'event' | 'request' | 'response' | 'error' | 'status')}
+ */
 export type MessageType = 'subscribe' | 'unsubscribe' | 'event' | 'request' | 'response' | 'error' | 'status';
+/**
+ * Configuration options for the NostrWSClient
+ * @interface NostrWSOptions
+ */
 export interface NostrWSOptions {
+    /**
+     * Interval in milliseconds between heartbeat messages
+     * @default 30000
+     */
     heartbeatInterval?: number;
+    /**
+     * Interval in milliseconds between reconnect attempts
+     * @default 5000
+     */
     reconnectInterval?: number;
+    /**
+     * Maximum number of reconnect attempts
+     * @default 10
+     */
     maxReconnectAttempts?: number;
+    /**
+     * Logger instance for handling log messages
+     * Must implement debug, info, error, and warn methods
+     */
     logger: Logger;
+    /**
+     * WebSocket implementation to use
+     * Defaults to the native WebSocket implementation
+     */
     WebSocketImpl: typeof WebSocket;
+    /**
+     * Event handlers for WebSocket events
+     */
     handlers: {
+        /**
+         * Handler for incoming messages
+         * @param ws - The WebSocket instance
+         * @param message - The received message
+         */
         message: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
+        /**
+         * Handler for WebSocket errors
+         * @param ws - The WebSocket instance
+         * @param error - The error object
+         */
         error?: (ws: WebSocket, error: Error) => void;
+        /**
+         * Handler for WebSocket connection close
+         * @param ws - The WebSocket instance
+         */
         close?: (ws: WebSocket) => void;
     };
 }
+/**
+ * Structure of messages sent through the WebSocket connection
+ * @interface NostrWSMessage
+ */
 export interface NostrWSMessage {
-    type: string;
+    /**
+     * Type of the message (e.g., 'EVENT', 'subscribe', 'unsubscribe')
+     */
+    type: MessageType;
+    /**
+     * Unique identifier for the message
+     */
     id?: string;
+    /**
+     * Data payload of the message
+     */
     data: Record<string, unknown>;
 }
+/**
+ * Represents a subscription to a Nostr relay
+ * @interface NostrWSSubscription
+ */
 export interface NostrWSSubscription {
+    /**
+     * Channel identifier for the subscription
+     */
     channel: string;
+    /**
+     * Filter criteria for the subscription
+     */
     filter?: Record<string, unknown>;
 }
+/**
+ * Events emitted by the NostrWSClient
+ * @interface NostrWSClientEvents
+ */
 export interface NostrWSClientEvents {
+    /**
+     * Emitted when the client connects to the relay
+     */
     connect: () => void;
+    /**
+     * Emitted when the client disconnects from the relay
+     */
     disconnect: () => void;
+    /**
+     * Emitted when the client reconnects to the relay
+     */
     reconnect: () => void;
+    /**
+     * Emitted when a message is received from the relay
+     * @param message - The received message
+     */
     message: (message: NostrWSMessage) => void;
+    /**
+     * Emitted when an error occurs
+     * @param error - The error object
+     */
     error: (error: Error) => void;
 }
+/**
+ * Events emitted by the NostrWSServer
+ * @interface NostrWSServerEvents
+ */
 export interface NostrWSServerEvents {
+    /**
+     * Emitted when a client connects to the server
+     * @param client - The connected client
+     */
     connection: (client: ExtendedWebSocket) => void;
+    /**
+     * Emitted when a message is received from a client
+     * @param message - The received message
+     * @param client - The client that sent the message
+     */
     message: (message: NostrWSMessage, client: ExtendedWebSocket) => void;
+    /**
+     * Emitted when an error occurs
+     * @param error - The error object
+     */
     error: (error: Error) => void;
 }
+/**
+ * Extended WebSocket interface with additional properties
+ * @interface ExtendedWebSocket
+ */
 export interface ExtendedWebSocket extends WebSocket {
+    /**
+     * Whether the WebSocket connection is alive
+     */
     isAlive?: boolean;
+    /**
+     * Set of subscription channels
+     */
     subscriptions?: Set<string>;
+    /**
+     * Unique client identifier
+     */
     clientId?: string;
+    /**
+     * Queue of messages to be sent
+     */
     messageQueue?: NostrWSMessage[];
+    /**
+     * Timestamp of the last ping message
+     */
     lastPing?: number;
+    /**
+     * Number of reconnect attempts
+     */
     reconnectAttempts?: number;
 }
+/**
+ * Result of validating a NostrWSMessage
+ * @interface NostrWSValidationResult
+ */
 export interface NostrWSValidationResult {
+    /**
+     * Whether the message is valid
+     */
     isValid: boolean;
+    /**
+     * Error message if the message is invalid
+     */
     error?: string;
 }
+/**
+ * State of the NostrWSClient connection
+ * @interface NostrWSConnectionState
+ */
 export interface NostrWSConnectionState {
+    /**
+     * Whether the client is connected to the relay
+     */
     isConnected: boolean;
+    /**
+     * Number of reconnect attempts
+     */
     reconnectAttempts: number;
+    /**
+     * Last error message
+     */
     lastError?: string;
 }
+/**
+ * Logger interface
+ * @interface Logger
+ */
 export interface Logger {
+    /**
+     * Logs a debug message
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
     debug: (message: string, ...args: unknown[]) => void;
+    /**
+     * Logs an info message
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
     info: (message: string, ...args: unknown[]) => void;
+    /**
+     * Logs a warning message
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
     warn: (message: string, ...args: unknown[]) => void;
+    /**
+     * Logs an error message
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
     error: (message: string, ...args: unknown[]) => void;
 }

package/dist/utils/logger.d.ts

@@ -1,2 +1,6 @@
+/**
+ * @file Logger utility for Nostr WebSocket operations
+ * @module logger
+ */
 import winston from 'winston';
-export declare function getLogger(name?: string): winston.Logger;
+export declare function getLogger(context: string): winston.Logger;

package/dist/utils/logger.js

@@ -1,4 +1,21 @@
+/**
+ * @file Logger utility for Nostr WebSocket operations
+ * @module logger
+ */
 import winston from 'winston';
+/**
+ * Creates a logger instance with a specific context
+ *
+ * @param {string} context - The context identifier for the logger
+ * @returns {Logger} A logger instance with debug, info, warn, and error methods
+ *
+ * @example
+ * ```typescript
+ * const logger = getLogger('MyComponent');
+ * logger.info('Component initialized');
+ * logger.error('An error occurred', new Error('Failed to connect'));
+ * ```
+ */
 const logger = winston.createLogger({
     level: process.env.LOG_LEVEL || 'info',
     format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
@@ -8,9 +25,6 @@ const logger = winston.createLogger({
         })
     ]
 });
-export function getLogger(name) {
-    if (name) {
-        return logger.child({ service: name });
-    }
-    return logger;
+export function getLogger(context) {
+    return logger.child({ service: context });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-websocket-utils",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Robust WebSocket utilities for Nostr applications with automatic reconnection, channel-based messaging, and type-safe handlers. Features heartbeat monitoring, message queueing, and comprehensive error handling.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,10 @@
     "test:coverage": "jest --coverage",
     "lint": "eslint src --ext .ts",
     "prepare": "npm run build",
-    "prepublishOnly": "npm test && npm run lint"
+    "prepublishOnly": "npm test && npm run lint",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "predeploy": "npm run build && npm run docs"
   },
   "keywords": [
     "nostr",
@@ -37,7 +40,7 @@
   "bugs": {
     "url": "https://github.com/HumanjavaEnterprises/nostr-websocket-utils/issues"
   },
-  "homepage": "https://github.com/HumanjavaEnterprises/nostr-websocket-utils#readme",
+  "homepage": "https://humanjavaenterprises.github.io/nostr-websocket-utils",
   "dependencies": {
     "@noble/curves": "^1.3.0",
     "@noble/hashes": "^1.3.3",
@@ -60,6 +63,8 @@
     "eslint": "^8.56.0",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.1",
+    "typedoc": "^0.27.5",
+    "typedoc-plugin-markdown": "^4.3.2",
     "typescript": "^5.3.3"
   },
   "files": [