nostr-websocket-utils 0.2.4 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 MaiQR Platform
+Copyright (c) 2024 Humanjava Enterprises
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,25 +1,77 @@
-# 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
+
+## NIPs Support Status
+
+🟢 Fully implemented 🟡 Partially implemented 🔴 Not implemented
+
+| NIP | Status | Description |
+|-----|--------|-------------|
+| 01 | 🟢 | Basic protocol flow & WebSocket connections |
+| 02 | 🟢 | Contact List and Petnames |
+| 11 | 🟢 | Relay Information Document |
+| 15 | 🟢 | End of Stored Events Notice |
+| 16 | 🟢 | Event Treatment |
+| 20 | 🟢 | Command Results |
+| 42 | 🟢 | Authentication of clients to relays |
+
+### WebSocket Protocol Implementation Details
+
+This package implements the Nostr WebSocket protocol with full support for the core NIPs that define WebSocket behavior. Here's how it works:
+
+#### Key Features & Compliance
+
+1. **Protocol Implementation**:
+   - Full implementation of Nostr WebSocket protocol
+   - Support for all standard message types (EVENT, REQ, CLOSE, etc.)
+   - Robust error handling and status reporting
+
+2. **Connection Management**:
+   - Automatic reconnection with configurable backoff
+   - Heartbeat mechanism for connection health
+   - Connection pooling and load balancing
+
+3. **Message Handling**:
+   - Type-safe message processing
+   - Support for subscription management
+   - Efficient event filtering
+
+4. **Security & Best Practices**:
+   - Secure WebSocket connections (WSS)
+   - Implementation of authentication protocols
+   - Rate limiting and protection mechanisms
+
+#### Interoperability
+
+This implementation ensures compatibility with:
+- All major Nostr relays
+- Other Nostr clients and libraries
+- Standard WebSocket tooling and infrastructure
+
+#### Validation & Testing
+
+The package includes:
+- Comprehensive test suites for protocol compliance
+- Connection reliability testing
+- Performance benchmarks for message handling
 
 ## Installation
 
@@ -27,118 +79,114 @@ A TypeScript library providing WebSocket utilities for Nostr applications, focus
 npm install nostr-websocket-utils
 ```
 
-## Breaking Changes in v0.2.4
+## Quick Start
+
+### Creating a Nostr WebSocket Client
+
+```typescript
+import { NostrWSClient } from 'nostr-websocket-utils';
 
-- 🆕 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
+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')
+  }
+});
 
-## Usage
+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
+## Dependencies
+
+This package relies on:
+- [nostr-crypto-utils](https://github.com/HumanjavaEnterprises/nostr-crypto-utils) - For all cryptographic operations
+- [ws](https://github.com/websockets/ws) - For WebSocket functionality
+- [pino](https://github.com/pinojs/pino) - For logging
+- [uuid](https://github.com/uuidjs/uuid) - For unique identifiers
+
+## 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)
+
+## 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)

package/dist/__mocks__/extendedWsMock.d.ts

@@ -0,0 +1,35 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+export declare class ExtendedWsMock extends EventEmitter {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+    readyState: 0 | 1 | 2 | 3;
+    protocol: string;
+    url: string;
+    bufferedAmount: number;
+    extensions: string;
+    binaryType: 'nodebuffer' | 'arraybuffer' | 'fragments';
+    isPaused: boolean;
+    onopen: ((event: any) => void) | null;
+    onclose: ((event: any) => void) | null;
+    onerror: ((event: any) => void) | null;
+    onmessage: ((event: any) => void) | null;
+    constructor();
+    private bindMethods;
+    private createWsEvent;
+    addEventListener(type: string, listener: (event: any) => void): void;
+    removeEventListener(type: string, listener: (event: any) => void): void;
+    send: import("@vitest/spy").Mock<[data: any], this>;
+    ping: import("@vitest/spy").Mock<[data?: Buffer | Uint8Array | undefined], this>;
+    pong: import("@vitest/spy").Mock<[data?: Buffer | Uint8Array | undefined], this>;
+    close: import("@vitest/spy").Mock<[code?: number | undefined, reason?: string | undefined], this>;
+    terminate: import("@vitest/spy").Mock<[], this>;
+    pause(): this;
+    resume(): this;
+    setMaxListeners(n: number): this;
+}
+export declare const mockWebSocket: ExtendedWsMock;

package/dist/__mocks__/extendedWsMock.js

@@ -0,0 +1,156 @@
+import { vi } from 'vitest';
+import { EventEmitter } from 'events';
+export class ExtendedWsMock extends EventEmitter {
+    constructor() {
+        super();
+        // WebSocket state constants
+        this.CONNECTING = 0;
+        this.OPEN = 1;
+        this.CLOSING = 2;
+        this.CLOSED = 3;
+        // Required WebSocket properties
+        this.readyState = 1;
+        this.protocol = '';
+        this.url = 'ws://test.com';
+        this.bufferedAmount = 0;
+        this.extensions = '';
+        this.binaryType = 'nodebuffer';
+        this.isPaused = false;
+        // Event handlers
+        this.onopen = null;
+        this.onclose = null;
+        this.onerror = null;
+        this.onmessage = null;
+        this.send = vi.fn((data) => {
+            if (this.isPaused)
+                return this;
+            const isBinary = !(typeof data === 'string');
+            const event = this.createWsEvent('message', {
+                data: data
+            });
+            this.emit('message', data, isBinary);
+            this.onmessage?.apply(this, [event]);
+            return this;
+        });
+        this.ping = vi.fn((data) => {
+            if (!this.isPaused) {
+                this.emit('ping', data);
+            }
+            return this;
+        });
+        this.pong = vi.fn((data) => {
+            if (!this.isPaused) {
+                this.emit('pong', data);
+            }
+            return this;
+        });
+        this.close = vi.fn((code, reason) => {
+            this.readyState = this.CLOSED;
+            const event = this.createWsEvent('close', {
+                code,
+                reason,
+                wasClean: true
+            });
+            this.emit('close', code, Buffer.from(reason || ''));
+            this.onclose?.apply(this, [event]);
+            return this;
+        });
+        this.terminate = vi.fn(() => {
+            this.readyState = this.CLOSED;
+            const event = this.createWsEvent('close', {
+                code: 1006,
+                reason: 'Connection terminated',
+                wasClean: false
+            });
+            this.emit('close', 1006, Buffer.from('Connection terminated'));
+            this.onclose?.apply(this, [event]);
+            return this;
+        });
+        this.bindMethods();
+    }
+    bindMethods() {
+        // Bind all methods that need 'this' context
+        this.send = this.send.bind(this);
+        this.ping = this.ping.bind(this);
+        this.pong = this.pong.bind(this);
+        this.close = this.close.bind(this);
+        this.terminate = this.terminate.bind(this);
+        this.pause = this.pause.bind(this);
+        this.resume = this.resume.bind(this);
+    }
+    createWsEvent(type, data) {
+        const event = {
+            type,
+            target: this,
+            currentTarget: this,
+            ...data
+        };
+        return event;
+    }
+    addEventListener(type, listener) {
+        const boundListener = ((event) => {
+            listener.apply(this, [event]);
+        });
+        this.on(type, boundListener);
+    }
+    removeEventListener(type, listener) {
+        this.removeListener(type, listener);
+    }
+    pause() {
+        this.isPaused = true;
+        return this;
+    }
+    resume() {
+        this.isPaused = false;
+        return this;
+    }
+    // Additional required methods
+    setMaxListeners(n) {
+        super.setMaxListeners(n);
+        return this;
+    }
+}
+// Create mock event classes for Node.js environment
+class MockEvent {
+    constructor(type, target) {
+        this.type = type;
+        this.target = target || mockWebSocket;
+        this.currentTarget = this.target;
+    }
+}
+class MockMessageEvent extends MockEvent {
+    constructor(type, init) {
+        super(type, init?.target);
+        this.data = init?.data ?? '';
+        this.isBinary = init?.isBinary ?? false;
+    }
+}
+class MockCloseEvent extends MockEvent {
+    constructor(type, init) {
+        super(type, init?.target);
+        this.code = init?.code ?? 1000;
+        this.reason = init?.reason ?? '';
+        this.wasClean = init?.wasClean ?? true;
+    }
+}
+class MockErrorEvent extends MockEvent {
+    constructor(type, init) {
+        super(type, init?.target);
+        this.error = init?.error ?? new Error('WebSocket Error');
+        this.message = init?.message ?? 'WebSocket Error';
+    }
+}
+if (typeof Event === 'undefined') {
+    global.Event = MockEvent;
+}
+if (typeof MessageEvent === 'undefined') {
+    global.MessageEvent = MockMessageEvent;
+}
+if (typeof CloseEvent === 'undefined') {
+    global.CloseEvent = MockCloseEvent;
+}
+if (typeof ErrorEvent === 'undefined') {
+    global.ErrorEvent = MockErrorEvent;
+}
+// Export a singleton instance
+export const mockWebSocket = new ExtendedWsMock();

package/dist/__mocks__/logger.d.ts

@@ -0,0 +1,9 @@
+type LoggerFunction = (message: string, ...args: unknown[]) => void;
+interface MockLogger {
+    debug: LoggerFunction;
+    info: LoggerFunction;
+    warn: LoggerFunction;
+    error: LoggerFunction;
+}
+export declare const getLogger: (_name: string) => MockLogger;
+export {};

package/dist/__mocks__/logger.js

@@ -0,0 +1,6 @@
+export const getLogger = (_name) => ({
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+});

package/dist/__mocks__/mockLogger.d.ts

@@ -0,0 +1,41 @@
+import type { Logger, ChildLoggerOptions, Bindings } from 'pino';
+export declare class MockPinoLogger implements Partial<Logger> {
+    level: string;
+    levelVal: number;
+    version: string;
+    LOG_VERSION: number;
+    useLevelLabels: boolean;
+    useOnlyCustomLevels: boolean;
+    customLevels: {};
+    debug: import("@vitest/spy").Mock<any, any>;
+    info: import("@vitest/spy").Mock<any, any>;
+    warn: import("@vitest/spy").Mock<any, any>;
+    error: import("@vitest/spy").Mock<any, any>;
+    fatal: import("@vitest/spy").Mock<any, any>;
+    trace: import("@vitest/spy").Mock<any, any>;
+    silent: import("@vitest/spy").Mock<any, any>;
+    levels: {
+        values: {
+            fatal: number;
+            error: number;
+            warn: number;
+            info: number;
+            debug: number;
+            trace: number;
+        };
+        labels: {
+            10: string;
+            20: string;
+            30: string;
+            40: string;
+            50: string;
+            60: string;
+        };
+    };
+    bindings: () => {};
+    flush: () => Promise<void>;
+    isLevelEnabled: () => boolean;
+    child<ChildCustomLevels extends string = never>(_bindings: Bindings, _options?: ChildLoggerOptions<ChildCustomLevels>): Logger<ChildCustomLevels>;
+    static create(): Logger;
+}
+export declare const createMockLogger: () => Logger;

package/dist/__mocks__/mockLogger.js

@@ -0,0 +1,47 @@
+import { vi } from 'vitest';
+export class MockPinoLogger {
+    constructor() {
+        this.level = 'debug';
+        this.levelVal = 20;
+        this.version = '8.0.0';
+        this.LOG_VERSION = 1;
+        this.useLevelLabels = true;
+        this.useOnlyCustomLevels = false;
+        this.customLevels = {};
+        this.debug = vi.fn();
+        this.info = vi.fn();
+        this.warn = vi.fn();
+        this.error = vi.fn();
+        this.fatal = vi.fn();
+        this.trace = vi.fn();
+        this.silent = vi.fn();
+        this.levels = {
+            values: {
+                fatal: 60,
+                error: 50,
+                warn: 40,
+                info: 30,
+                debug: 20,
+                trace: 10
+            },
+            labels: {
+                10: 'trace',
+                20: 'debug',
+                30: 'info',
+                40: 'warn',
+                50: 'error',
+                60: 'fatal'
+            }
+        };
+        this.bindings = () => ({});
+        this.flush = () => Promise.resolve();
+        this.isLevelEnabled = () => true;
+    }
+    child(_bindings, _options) {
+        return new MockPinoLogger();
+    }
+    static create() {
+        return new MockPinoLogger();
+    }
+}
+export const createMockLogger = () => MockPinoLogger.create();

package/dist/__mocks__/mockserver.d.ts

@@ -0,0 +1,31 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import type { NostrWSMessage } from '../types/messages';
+import type { NostrWSSocket } from '../types/socket';
+import type { IncomingMessage } from 'http';
+import type { Socket } from 'net';
+import type { WebSocket } from 'ws';
+interface MockServerOptions {
+    port?: number;
+    host?: string;
+    [key: string]: unknown;
+}
+export declare class MockServer extends EventEmitter {
+    clients: Set<NostrWSSocket>;
+    options: MockServerOptions;
+    path: string;
+    address: string;
+    constructor(options?: MockServerOptions);
+    listen(port: number, cb?: () => void): void;
+    handleConnection: import("@vitest/spy").Mock<[socket: NostrWSSocket], void>;
+    handleMessage: import("@vitest/spy").Mock<[socket: NostrWSSocket, message: NostrWSMessage], void>;
+    handleClose: import("@vitest/spy").Mock<[socket: NostrWSSocket], void>;
+    broadcast: import("@vitest/spy").Mock<[message: NostrWSMessage], void>;
+    handleUpgrade: import("@vitest/spy").Mock<[request: IncomingMessage, socket: Socket, head: Buffer, callback: (ws: WebSocket) => void], void>;
+    shouldHandle: import("@vitest/spy").Mock<[_request: IncomingMessage], boolean>;
+}
+export {};

package/dist/__mocks__/mockserver.js

@@ -0,0 +1,39 @@
+import { vi } from 'vitest';
+import { EventEmitter } from 'events';
+import { ExtendedWsMock } from './extendedWsMock';
+export class MockServer extends EventEmitter {
+    constructor(options) {
+        super();
+        this.clients = new Set();
+        this.handleConnection = vi.fn((socket) => {
+            this.clients.add(socket);
+            this.emit('connection', socket);
+        });
+        this.handleMessage = vi.fn((socket, message) => {
+            this.emit('message', socket, message);
+        });
+        this.handleClose = vi.fn((socket) => {
+            this.clients.delete(socket);
+            this.emit('close', socket);
+        });
+        this.broadcast = vi.fn((message) => {
+            this.clients.forEach(client => {
+                client.send(JSON.stringify(message));
+            });
+        });
+        this.handleUpgrade = vi.fn((request, socket, head, callback) => {
+            const ws = new ExtendedWsMock();
+            callback(ws);
+        });
+        this.shouldHandle = vi.fn((_request) => {
+            return true;
+        });
+        this.options = options || {};
+        this.path = '/';
+        this.address = 'localhost';
+    }
+    listen(port, cb) {
+        if (cb)
+            cb();
+    }
+}