nostr-websocket-utils 0.2.3 → 0.2.4

package/README.md

@@ -19,6 +19,7 @@ A TypeScript library providing WebSocket utilities for Nostr applications, focus
 - 🛡️ Comprehensive error handling and validation
 - 🧪 100% test coverage with Jest
 - 📦 Zero DOM dependencies
+- 🔍 Full TypeScript type safety
 
 ## Installation
 
@@ -26,179 +27,118 @@ A TypeScript library providing WebSocket utilities for Nostr applications, focus
 npm install nostr-websocket-utils
 ```
 
-## Breaking Changes in v0.2.2
+## Breaking Changes in v0.2.4
 
-- 🔥 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
+- 🆕 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
 
 ## Usage
 
-### Server Example
+### Nostr Server Example
 
 ```typescript
-import { NostrWSServer } from 'nostr-websocket-utils';
-import { WebSocketServer } from 'ws';
-import { getLogger } from './utils/logger';
+import { NostrWSServer, createWSServer } from 'nostr-websocket-utils';
+import { NostrWSMessageType, NostrWSEvent } from 'nostr-websocket-utils/types/nostr';
 
-// Create WebSocket server
-const wss = new WebSocketServer({ port: 8080 });
-
-// Initialize NostrWSServer with handlers
-const server = new NostrWSServer(wss, {
-  logger: getLogger('nostr-server'),
+// Create Nostr WebSocket server
+const server = createWSServer({
+  port: 8080,
   heartbeatInterval: 30000, // Optional: 30 seconds
   handlers: {
     // Required: Handle incoming messages
-    message: async (ws, message) => {
-      switch (message.type) {
-        case 'subscribe':
-          // Handle subscription
-          ws.subscriptions?.add(message.data.channel);
+    message: async (socket, message) => {
+      switch (message[0]) {
+        case NostrWSMessageType.EVENT:
+          const event = message[1] as NostrWSEvent;
+          // Handle Nostr event
           break;
-        case 'event':
-          // Broadcast to relevant subscribers
-          server.broadcastToChannel(message.data.channel, message);
+        case NostrWSMessageType.REQ:
+          const [_type, subscriptionId, filter] = message;
+          // Handle subscription request
           break;
       }
     },
     // Optional: Handle errors
-    error: (ws, error) => {
-      logger.error('WebSocket error:', error);
+    error: (socket, error) => {
+      console.error('WebSocket error:', error);
     },
     // Optional: Handle client disconnection
-    close: (ws) => {
-      logger.info(`Client ${ws.clientId} disconnected`);
+    close: (socket) => {
+      console.info('Client disconnected');
     }
   }
 });
-```
-
-### Client Example
-
-```typescript
-import { NostrWSClient } from 'nostr-websocket-utils';
-import { getLogger } from './utils/logger';
-
-const client = new NostrWSClient('ws://localhost:8080', {
-  logger: getLogger('nostr-client'),
-  heartbeatInterval: 30000,
-  handlers: {
-    // Required: Handle incoming messages
-    message: async (ws, message) => {
-      console.log('Received:', 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!'
-    }
-  });
-});
 
-// Connect to server
-client.connect();
+// Start listening
+server.listen();
 ```
 
-## API Reference
-
-### NostrWSServer
-
-The server-side WebSocket handler with support for channels and broadcasting.
+### Types
 
 ```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;
+// Nostr Event Type
+interface NostrWSEvent {
+  id: string;
+  pubkey: string;
+  created_at: number;
+  kind: number;
+  tags: string[][];
+  content: string;
+  sig: string;
 }
-```
 
-### NostrWSClient
-
-The client-side WebSocket handler with automatic reconnection and message queueing.
+// Nostr Filter Type
+interface NostrWSFilter {
+  ids?: string[];
+  authors?: string[];
+  kinds?: number[];
+  '#e'?: string[];
+  '#p'?: string[];
+  since?: number;
+  until?: number;
+  limit?: number;
+}
 
-```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;
+// Message Types
+enum NostrWSMessageType {
+  EVENT = 'EVENT',
+  REQ = 'REQ',
+  CLOSE = 'CLOSE',
+  NOTICE = 'NOTICE',
+  AUTH = 'AUTH',
+  EOSE = 'EOSE'
 }
 ```
 
-### NostrWSMessage
+## Advanced Configuration
 
-The standard message format for communication.
+### Server Options
 
 ```typescript
-interface NostrWSMessage {
-  id?: string;           // Auto-generated UUID if not provided
-  type: string;          // Message type (e.g., 'subscribe', 'event')
-  data: {
-    channel?: string;    // Target channel for subscription/broadcast
-    [key: string]: any;  // Additional message data
+interface NostrWSServerOptions {
+  port: number;
+  heartbeatInterval?: number;
+  maxPayloadSize?: number;
+  cors?: {
+    origin?: string | string[];
+    methods?: string[];
+  };
+  handlers: {
+    message: MessageHandler;
+    error?: ErrorHandler;
+    close?: CloseHandler;
   };
 }
 ```
 
-## Why Choose This Library
-
-### 1. Nostr-Optimized
-- Built specifically for Nostr protocol requirements
-- Efficient pub/sub model with filtered subscriptions
-- Type-safe message handling for all Nostr events
-
-### 2. Production-Ready
-- Comprehensive error handling and recovery
-- Memory-efficient subscription management
-- Built-in logging and monitoring
-- Extensive test coverage
-
-### 3. Developer-Friendly
-- Clear TypeScript definitions
-- Flexible configuration options
-- Detailed documentation
-- Active maintenance
-
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+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.
 
 ## License
 
-MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 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,5 @@
 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,8 @@
+import { NostrWSServerOptions } from './types/nostr';
+export declare class NostrWSServer {
+    private server;
+    private logger;
+    constructor(options: NostrWSServerOptions);
+    close(): void;
+}
+export declare function createWSServer(options: NostrWSServerOptions): NostrWSServer;

package/dist/nostr-server.js

@@ -0,0 +1,63 @@
+import { Server as WebSocketServer } from 'ws';
+import { getLogger } from './utils/logger';
+export class NostrWSServer {
+    constructor(options) {
+        this.logger = getLogger('NostrWSServer');
+        this.server = new WebSocketServer({ port: options.port });
+        this.server.on('connection', (socket) => {
+            socket.subscriptions = new Set();
+            socket.isAlive = true;
+            if (options.onConnection) {
+                options.onConnection(socket);
+            }
+            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);
+            socket.on('close', () => {
+                if (options.handlers?.close) {
+                    options.handlers.close(socket);
+                }
+            });
+            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);
+                socket.on('pong', () => {
+                    socket.isAlive = true;
+                });
+                socket.on('close', () => {
+                    clearInterval(interval);
+                });
+            }
+        });
+    }
+    close() {
+        this.server.close();
+    }
+}
+export function createWSServer(options) {
+    return new NostrWSServer(options);
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-websocket-utils",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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",
@@ -51,6 +51,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",