nostr-websocket-utils 0.2.3 → 0.2.5

package/README.md

@@ -1,24 +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 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
 
@@ -26,179 +25,108 @@ A TypeScript library providing WebSocket utilities for Nostr applications, focus
 npm install nostr-websocket-utils
 ```
 
-## Breaking Changes in v0.2.2
+## Quick Start
 
-- 🔥 Removed all DOM-related code for better server-side compatibility
-- 🆔 Added UUID support for message tracking and correlation
-- 🔌 Introduced `WebSocketImpl` option for custom WebSocket implementations
-- 🛡️ Enhanced TypeScript type safety and validation
-- 🔄 Improved reconnection and error handling logic
-- 📝 Added comprehensive logging support
-
-## Usage
-
-### Server Example
+### Creating a Nostr WebSocket Client
 
 ```typescript
-import { NostrWSServer } from 'nostr-websocket-utils';
-import { WebSocketServer } from 'ws';
-import { getLogger } from './utils/logger';
-
-// Create WebSocket server
-const wss = new WebSocketServer({ port: 8080 });
+import { NostrWSClient } from 'nostr-websocket-utils';
 
-// Initialize NostrWSServer with handlers
-const server = new NostrWSServer(wss, {
-  logger: getLogger('nostr-server'),
-  heartbeatInterval: 30000, // Optional: 30 seconds
+const client = new NostrWSClient('wss://relay.example.com', {
+  logger: console,
+  heartbeatInterval: 30000,
   handlers: {
-    // Required: Handle incoming messages
-    message: async (ws, message) => {
-      switch (message.type) {
-        case 'subscribe':
-          // Handle subscription
-          ws.subscriptions?.add(message.data.channel);
-          break;
-        case 'event':
-          // Broadcast to relevant subscribers
-          server.broadcastToChannel(message.data.channel, message);
-          break;
-      }
-    },
-    // Optional: Handle errors
-    error: (ws, error) => {
-      logger.error('WebSocket error:', error);
-    },
-    // Optional: Handle client disconnection
-    close: (ws) => {
-      logger.info(`Client ${ws.clientId} disconnected`);
-    }
+    message: async (msg) => console.log('Received:', msg),
+    error: (err) => console.error('Error:', err),
+    close: () => console.log('Connection closed')
   }
 });
+
+await client.connect();
 ```
 
-### Client Example
+### Creating a Nostr WebSocket Server
 
 ```typescript
-import { NostrWSClient } from 'nostr-websocket-utils';
-import { getLogger } from './utils/logger';
+import { createNostrServer } from '@humanjavaenterprises/nostr-websocket-utils';
 
-const client = new NostrWSClient('ws://localhost:8080', {
-  logger: getLogger('nostr-client'),
+const server = await createNostrServer(8080, {
+  logger: console,
   heartbeatInterval: 30000,
   handlers: {
-    // Required: Handle incoming messages
-    message: async (ws, message) => {
-      console.log('Received:', message);
+    message: async (ws, msg) => {
+      console.log('Received message:', msg);
+      // Handle the message
     }
   }
 });
+```
 
-// Listen for connection events
-client.on('connect', () => {
-  console.log('Connected to server');
-  
-  // Subscribe to a channel
-  client.subscribe('my-channel');
-  
-  // Send an event
-  client.send({
-    type: 'event',
-    data: {
-      channel: 'my-channel',
-      content: 'Hello, Nostr!'
-    }
-  });
-});
+## Documentation
 
-// Connect to server
-client.connect();
-```
+Comprehensive API documentation is available in our [documentation site](https://humanjavaenterprises.github.io/nostr-websocket-utils/). Here's what you'll find:
 
-## API Reference
+### 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
 
-### NostrWSServer
+### 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
 
-The server-side WebSocket handler with support for channels and broadcasting.
+### Utility Functions
+- [createServer](docs/functions/createServer.md) - Server creation helper
+- [getLogger](docs/functions/getLogger.md) - Logging utility
 
-```typescript
-class NostrWSServer {
-  constructor(wss: WebSocketServer, options: NostrWSOptions);
-  
-  // Broadcast to all connected clients
-  broadcast(message: NostrWSMessage): void;
-  
-  // Broadcast to specific channel subscribers
-  broadcastToChannel(channel: string, message: NostrWSMessage): void;
-  
-  // Close the server and all connections
-  close(): void;
-}
-```
+### Type Definitions
+- [MessageType](docs/enumerations/NostrWSMessageType.md) - Message type enumeration
+- [Global Types](docs/globals.md) - Global type definitions
 
-### NostrWSClient
+## Examples
 
-The client-side WebSocket handler with automatic reconnection and message queueing.
+### Subscribe to a Channel
 
 ```typescript
-class NostrWSClient {
-  constructor(url: string, options: NostrWSOptions);
-  
-  // Connect to the server
-  connect(): void;
-  
-  // Subscribe to a channel
-  subscribe(channel: string, filter?: unknown): void;
-  
-  // Unsubscribe from a channel
-  unsubscribe(channel: string): void;
-  
-  // Send a message to the server
-  send(message: NostrWSMessage): Promise<void>;
-  
-  // Close the connection
-  close(): void;
-}
+client.subscribe('my-channel', {
+  filter: {
+    authors: ['pubkey1', 'pubkey2'],
+    kinds: [1]
+  }
+});
 ```
 
-### NostrWSMessage
-
-The standard message format for communication.
+### Broadcast a Message
 
 ```typescript
-interface NostrWSMessage {
-  id?: string;           // Auto-generated UUID if not provided
-  type: string;          // Message type (e.g., 'subscribe', 'event')
+server.broadcast({
+  type: 'event',
   data: {
-    channel?: string;    // Target channel for subscription/broadcast
-    [key: string]: any;  // Additional message data
-  };
-}
+    content: 'Hello everyone!',
+    kind: 1
+  }
+});
 ```
 
-## Why Choose This Library
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
 
-### 1. Nostr-Optimized
-- Built specifically for Nostr protocol requirements
-- Efficient pub/sub model with filtered subscriptions
-- Type-safe message handling for all Nostr events
+## License
 
-### 2. Production-Ready
-- Comprehensive error handling and recovery
-- Memory-efficient subscription management
-- Built-in logging and monitoring
-- Extensive test coverage
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-### 3. Developer-Friendly
-- Clear TypeScript definitions
-- Flexible configuration options
-- Detailed documentation
-- Active maintenance
+## Related Projects
 
-## Contributing
+- [nostr-protocol](https://github.com/nostr-protocol/nostr)
+- [nostr-tools](https://github.com/nbd-wtf/nostr-tools)
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+## Support
 
-## License
+If you have any questions or need help, please:
 
-MIT License - see the [LICENSE](LICENSE) file for details.
+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,4 +1,11 @@
+/**
+ * @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';
+export { createWSServer as createServer } from './nostr-server.js';
 export { getLogger } from './utils/logger.js';
 export type { NostrWSOptions, NostrWSMessage, NostrWSSubscription, NostrWSClientEvents, NostrWSServerEvents, ExtendedWebSocket, NostrWSValidationResult, NostrWSConnectionState } from './types/index.js';
+export type { NostrWSEvent as NostrEvent, NostrWSFilter as NostrFilter, NostrWSSocket as NostrSocket, NostrWSServerOptions, NostrWSServerMessage, NostrWSMessageType } from './types/nostr.js';

package/dist/index.js

@@ -1,3 +1,9 @@
+/**
+ * @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';
+export { createWSServer as createServer } from './nostr-server.js';
 export { getLogger } from './utils/logger.js';

package/dist/nostr-server.d.ts

@@ -0,0 +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

@@ -0,0 +1,107 @@
+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());
+                    if (options.handlers?.message) {
+                        await options.handlers.message(socket, message);
+                    }
+                }
+                catch (error) {
+                    if (options.handlers?.error) {
+                        options.handlers.error(socket, error);
+                    }
+                }
+            };
+            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);
+                }
+            });
+            // Setup heartbeat
+            if (options.heartbeatInterval) {
+                const interval = setInterval(() => {
+                    if (!socket.isAlive) {
+                        socket.terminate();
+                        clearInterval(interval);
+                        return;
+                    }
+                    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/types/nostr.d.ts

@@ -0,0 +1,52 @@
+import { ExtendedWebSocket } from './index';
+export interface NostrWSEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+export interface NostrWSFilter {
+    ids?: string[];
+    authors?: string[];
+    kinds?: number[];
+    '#e'?: string[];
+    '#p'?: string[];
+    since?: number;
+    until?: number;
+    limit?: number;
+}
+export interface NostrWSSocket extends ExtendedWebSocket {
+    subscriptions?: Set<string>;
+    authenticated?: boolean;
+    pubkey?: string;
+}
+export declare enum NostrWSMessageType {
+    EVENT = "EVENT",
+    REQ = "REQ",
+    CLOSE = "CLOSE",
+    NOTICE = "NOTICE",
+    OK = "OK",
+    AUTH = "AUTH",
+    EOSE = "EOSE"
+}
+export type NostrWSServerMessage = [NostrWSMessageType, ...unknown[]];
+export interface NostrWSServerOptions {
+    port: number;
+    heartbeatInterval?: number;
+    maxPayloadSize?: number;
+    cors?: {
+        origin: string;
+        methods: string[];
+    };
+    onConnection?: (socket: NostrWSSocket) => void;
+    onDisconnect?: (socket: NostrWSSocket) => void;
+    onError?: (error: Error, socket?: NostrWSSocket) => void;
+    handlers?: {
+        message: (socket: NostrWSSocket, message: NostrWSServerMessage) => void | Promise<void>;
+        error?: (socket: NostrWSSocket, error: Error) => void;
+        close?: (socket: NostrWSSocket) => void;
+    };
+}

package/dist/types/nostr.js

@@ -0,0 +1,10 @@
+export var NostrWSMessageType;
+(function (NostrWSMessageType) {
+    NostrWSMessageType["EVENT"] = "EVENT";
+    NostrWSMessageType["REQ"] = "REQ";
+    NostrWSMessageType["CLOSE"] = "CLOSE";
+    NostrWSMessageType["NOTICE"] = "NOTICE";
+    NostrWSMessageType["OK"] = "OK";
+    NostrWSMessageType["AUTH"] = "AUTH";
+    NostrWSMessageType["EOSE"] = "EOSE";
+})(NostrWSMessageType || (NostrWSMessageType = {}));

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.3",
+  "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",
@@ -51,6 +54,7 @@
     "nostr-tools": "^2.1.4"
   },
   "devDependencies": {
+    "@jest/globals": "^29.7.0",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.11.0",
     "@types/ws": "^8.5.10",
@@ -59,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": [