nostr-websocket-utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MaiQR Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+Nostr Websocket Utils
+
+[![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)
+[![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, with robust connection handling, automatic reconnection, and channel-based messaging.
+
+## Features
+
+- 🔄 Automatic reconnection with configurable attempts
+- 💓 Heartbeat monitoring
+- 📨 Message queueing during disconnections
+- 📢 Channel-based broadcasting
+- 🔒 Type-safe message handling
+- 📝 Built-in logging
+
+## Installation
+
+```bash
+npm install @humanjavaenterprises/nostr-websocket-utils
+```
+
+## Usage
+
+### Client Example
+
+```typescript
+import { NostrWSClient } from '@humanjavaenterprises/nostr-websocket-utils';
+
+const client = new NostrWSClient('wss://your-server.com', {
+  heartbeatInterval: 30000,
+  reconnectInterval: 5000,
+  maxReconnectAttempts: 5
+});
+
+client.on('connect', () => {
+  console.log('Connected!');
+  client.subscribe('my-channel');
+});
+
+client.on('message', (message) => {
+  console.log('Received:', message);
+});
+
+client.connect();
+```
+
+### Server Example
+
+```typescript
+import express from 'express';
+import { createServer } from 'http';
+import { NostrWSServer } from '@humanjavaenterprises/nostr-websocket-utils';
+
+const app = express();
+const server = createServer(app);
+const wss = new NostrWSServer(server, {
+  heartbeatInterval: 30000
+});
+
+wss.on('message', (message, client) => {
+  console.log('Received message:', message);
+  
+  // Broadcast to specific channel
+  wss.broadcastToChannel('my-channel', {
+    type: 'event',
+    data: { content: 'Hello channel!' }
+  });
+});
+
+server.listen(3000);
+```
+
+## Why This Library is Perfect for Nostr Development
+
+This library is specifically designed to accelerate Nostr application development by providing a robust foundation for WebSocket communication. Here's what makes it particularly valuable:
+
+### 1. Nostr-Specific Message Types
+- Built-in support for core Nostr protocol message types (`subscribe`, `unsubscribe`, `event`, `request/response`)
+- Perfectly aligned with Nostr's pub/sub model
+- Type-safe message handling for all Nostr events
+
+### 2. Advanced WebSocket Management
+- Zero-config connection maintenance with automatic reconnection
+- Built-in heartbeat mechanism prevents stale connections
+- Smart message queuing ensures no events are lost during disconnections
+- Comprehensive connection state tracking
+
+### 3. Efficient Event Distribution
+- Channel-based broadcasting for targeted event distribution
+- Support for filtered subscriptions (crucial for Nostr event filtering)
+- Memory-efficient subscription tracking
+- Optimized message routing to relevant subscribers
+
+### 4. Developer Experience
+- Full TypeScript support with comprehensive type definitions
+- Event-driven architecture matching Nostr's event-centric nature
+- Clear, consistent error handling and validation
+- Minimal boilerplate needed to get started
+
+### 5. Production-Ready Features
+- Built-in logging system
+- Memory leak prevention through proper client cleanup
+- Scalable client management
+- Support for multiple simultaneous subscriptions
+
+By using this library, you can skip weeks of WebSocket infrastructure development and focus on building your Nostr application's unique features.
+
+## API Reference
+
+### NostrWSClient
+
+- `constructor(url: string, options?: NostrWSOptions)`
+- `connect(): void`
+- `send(message: NostrWSMessage): void`
+- `subscribe(channel: string): void`
+- `unsubscribe(channel: string): void`
+- `close(): void`
+
+Events:
+- `connect`
+- `disconnect`
+- `reconnect`
+- `message`
+- `error`
+
+### NostrWSServer
+
+- `constructor(server: any, options?: NostrWSOptions)`
+- `broadcast(message: NostrWSMessage): void`
+- `broadcastToChannel(channel: string, message: NostrWSMessage): void`
+- `sendTo(client: ExtendedWebSocket, message: NostrWSMessage): void`
+- `getClients(): Set<ExtendedWebSocket>`
+- `close(): void`
+
+Events:
+- `message`
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { EventEmitter } from 'events';
+import type { NostrWSOptions, NostrWSMessage } from './types/index.js';
+export declare class NostrWSClient extends EventEmitter {
+    private url;
+    private ws;
+    private options;
+    private reconnectTimeout;
+    private heartbeatInterval;
+    private reconnectAttempts;
+    private messageQueue;
+    constructor(url: string, options?: Partial<NostrWSOptions>);
+    connect(): void;
+    private setupEventHandlers;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private handleReconnect;
+    subscribe(channel: string, filter?: unknown): void;
+    unsubscribe(channel: string): void;
+    private flushMessageQueue;
+    send(message: NostrWSMessage): Promise<void>;
+    close(): void;
+}

package/dist/client.js

@@ -0,0 +1,148 @@
+import WebSocket from 'ws';
+import { EventEmitter } from 'events';
+export class NostrWSClient extends EventEmitter {
+    constructor(url, options = {}) {
+        super();
+        this.url = url;
+        this.ws = null;
+        this.reconnectTimeout = null;
+        this.heartbeatInterval = null;
+        this.reconnectAttempts = 0;
+        this.messageQueue = [];
+        if (!options.logger) {
+            throw new Error('Logger is required');
+        }
+        this.options = {
+            heartbeatInterval: options.heartbeatInterval || 30000,
+            logger: options.logger,
+            onMessage: options.onMessage,
+            onError: options.onError,
+            onClose: options.onClose
+        };
+    }
+    connect() {
+        if (this.ws) {
+            this.options.logger.info('WebSocket connection already exists');
+            return;
+        }
+        try {
+            this.ws = new WebSocket(this.url);
+            this.setupEventHandlers();
+        }
+        catch (error) {
+            this.options.logger.error('Failed to create WebSocket connection:', error);
+            this.handleReconnect();
+        }
+    }
+    setupEventHandlers() {
+        if (!this.ws)
+            return;
+        this.ws.on('open', () => {
+            this.options.logger.info('WebSocket connection established');
+            this.reconnectAttempts = 0;
+            this.startHeartbeat();
+            this.emit('connect');
+            this.flushMessageQueue();
+        });
+        this.ws.on('message', async (data) => {
+            try {
+                const message = JSON.parse(data.toString());
+                this.emit('message', message);
+                if (this.options.onMessage) {
+                    await this.options.onMessage(this.ws, message);
+                }
+            }
+            catch (error) {
+                this.emit('error', error);
+                if (this.options.onError) {
+                    this.options.onError(this.ws, error);
+                }
+            }
+        });
+        this.ws.on('close', () => {
+            this.options.logger.info('WebSocket connection closed');
+            this.stopHeartbeat();
+            this.handleReconnect();
+            this.emit('disconnect');
+            if (this.options.onClose) {
+                this.options.onClose(this.ws);
+            }
+        });
+        this.ws.on('error', (error) => {
+            this.options.logger.error('WebSocket error:', error);
+            this.emit('error', error);
+            if (this.options.onError) {
+                this.options.onError(this.ws, error);
+            }
+        });
+    }
+    startHeartbeat() {
+        if (this.heartbeatInterval)
+            return;
+        this.heartbeatInterval = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.ping();
+            }
+        }, this.options.heartbeatInterval || 30000);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
+        }
+    }
+    handleReconnect() {
+        if (this.reconnectTimeout)
+            return;
+        this.reconnectAttempts++;
+        this.reconnectTimeout = setTimeout(() => {
+            this.reconnectTimeout = null;
+            this.connect();
+            this.emit('reconnect');
+        }, 5000);
+    }
+    subscribe(channel, filter) {
+        this.send({
+            type: 'subscribe',
+            data: { channel, filter }
+        });
+    }
+    unsubscribe(channel) {
+        this.send({
+            type: 'unsubscribe',
+            data: { channel }
+        });
+    }
+    flushMessageQueue() {
+        while (this.messageQueue.length > 0 && this.ws?.readyState === WebSocket.OPEN) {
+            const message = this.messageQueue.shift();
+            if (message) {
+                this.send(message);
+            }
+        }
+    }
+    async send(message) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            this.messageQueue.push(message);
+            return;
+        }
+        try {
+            this.ws.send(JSON.stringify(message));
+        }
+        catch (error) {
+            this.options.logger.error('Failed to send message:', error);
+            this.handleReconnect();
+        }
+    }
+    close() {
+        this.stopHeartbeat();
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { NostrWSClient } from './client.js';
+export { NostrWSServer } from './server.js';
+export { getLogger } from './utils/logger.js';
+export type { NostrWSOptions, NostrWSMessage, NostrWSSubscription, NostrWSClientEvents, NostrWSServerEvents, ExtendedWebSocket, NostrWSValidationResult, NostrWSConnectionState } from './types/index.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { NostrWSClient } from './client.js';
+export { NostrWSServer } from './server.js';
+export { getLogger } from './utils/logger.js';

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { EventEmitter } from 'events';
+import { Server as HttpServer } from 'http';
+import type { NostrWSOptions, NostrWSMessage } from './types/index.js';
+export declare class NostrWSServer extends EventEmitter {
+    private wss;
+    private options;
+    private heartbeatInterval;
+    constructor(server: HttpServer, options?: Partial<NostrWSOptions>);
+    private setupServer;
+    private startHeartbeat;
+    broadcast(message: NostrWSMessage): void;
+    broadcastToChannel(channel: string, message: NostrWSMessage): void;
+    close(): void;
+}

package/dist/server.js

@@ -0,0 +1,89 @@
+import { EventEmitter } from 'events';
+import { WebSocketServer, WebSocket } from 'ws';
+export class NostrWSServer extends EventEmitter {
+    constructor(server, options = {}) {
+        super();
+        this.heartbeatInterval = null;
+        if (!options.logger) {
+            throw new Error('Logger is required');
+        }
+        this.options = {
+            heartbeatInterval: options.heartbeatInterval || 30000,
+            logger: options.logger,
+            onMessage: options.onMessage || (() => { }),
+            onError: options.onError || (() => { }),
+            onClose: options.onClose || (() => { })
+        };
+        this.wss = new WebSocketServer({ server });
+        this.setupServer();
+    }
+    setupServer() {
+        this.wss.on('connection', (ws) => {
+            const extWs = ws;
+            extWs.subscriptions = new Set();
+            extWs.isAlive = true;
+            ws.on('message', async (data) => {
+                try {
+                    const message = JSON.parse(data.toString());
+                    if (this.options.onMessage) {
+                        await this.options.onMessage(extWs, message);
+                    }
+                }
+                catch (error) {
+                    if (this.options.onError) {
+                        this.options.onError(ws, error);
+                    }
+                }
+            });
+            ws.on('close', () => {
+                extWs.isAlive = false;
+                if (this.options.onClose) {
+                    this.options.onClose(ws);
+                }
+            });
+            ws.on('error', (error) => {
+                if (this.options.onError) {
+                    this.options.onError(ws, error);
+                }
+            });
+        });
+        if (this.options.heartbeatInterval && this.options.heartbeatInterval > 0) {
+            this.startHeartbeat();
+        }
+    }
+    startHeartbeat() {
+        this.heartbeatInterval = setInterval(() => {
+            this.wss.clients.forEach((ws) => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    const extWs = ws;
+                    if (!extWs.isAlive) {
+                        return ws.terminate();
+                    }
+                    ws.ping();
+                    extWs.isAlive = false;
+                }
+            });
+        }, this.options.heartbeatInterval || 30000);
+    }
+    broadcast(message) {
+        this.wss.clients.forEach((client) => {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(JSON.stringify(message));
+            }
+        });
+    }
+    broadcastToChannel(channel, message) {
+        this.wss.clients.forEach((client) => {
+            const extClient = client;
+            if (client.readyState === WebSocket.OPEN && extClient.subscriptions?.has(channel)) {
+                client.send(JSON.stringify(message));
+            }
+        });
+    }
+    close() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+        }
+        this.wss.close();
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,53 @@
+import type { WebSocket } from 'ws';
+export type MessageType = 'subscribe' | 'unsubscribe' | 'event' | 'request' | 'response' | 'error' | 'status';
+export interface NostrWSOptions {
+    heartbeatInterval?: number;
+    reconnectInterval?: number;
+    maxReconnectAttempts?: number;
+    logger: Logger;
+    onMessage?: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
+    onError?: (ws: WebSocket, error: Error) => void;
+    onClose?: (ws: WebSocket) => void;
+}
+export interface NostrWSMessage {
+    type: string;
+    id?: string;
+    data: Record<string, unknown>;
+}
+export interface NostrWSSubscription {
+    channel: string;
+    filter?: Record<string, unknown>;
+}
+export interface NostrWSClientEvents {
+    connect: () => void;
+    disconnect: () => void;
+    reconnect: () => void;
+    message: (message: NostrWSMessage) => void;
+    error: (error: Error) => void;
+}
+export interface NostrWSServerEvents {
+    connection: (client: ExtendedWebSocket) => void;
+    message: (message: NostrWSMessage, client: ExtendedWebSocket) => void;
+    error: (error: Error) => void;
+}
+export interface ExtendedWebSocket extends WebSocket {
+    isAlive?: boolean;
+    subscriptions?: Set<string>;
+    messageQueue?: NostrWSMessage[];
+    lastPing?: number;
+    reconnectAttempts?: number;
+}
+export interface NostrWSValidationResult {
+    isValid: boolean;
+    error?: string;
+}
+export interface NostrWSConnectionState {
+    isConnected: boolean;
+    reconnectAttempts: number;
+    lastError?: string;
+}
+export interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/logger.d.ts

@@ -0,0 +1,2 @@
+import winston from 'winston';
+export declare function getLogger(name?: string): winston.Logger;

package/dist/utils/logger.js

@@ -0,0 +1,16 @@
+import winston from 'winston';
+const logger = winston.createLogger({
+    level: process.env.LOG_LEVEL || 'info',
+    format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
+    transports: [
+        new winston.transports.Console({
+            format: winston.format.combine(winston.format.colorize(), winston.format.simple())
+        })
+    ]
+});
+export function getLogger(name) {
+    if (name) {
+        return logger.child({ service: name });
+    }
+    return logger;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "nostr-websocket-utils",
+  "version": "0.1.0",
+  "description": "WebSocket utilities for Nostr applications",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test && npm run lint"
+  },
+  "keywords": [
+    "nostr",
+    "websocket",
+    "utils",
+    "maiqr"
+  ],
+  "author": "Human Java Enterprises",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.16.0",
+    "winston": "^3.11.0",
+    "@noble/curves": "^1.3.0",
+    "@noble/hashes": "^1.3.3",
+    "nostr-tools": "^2.1.4"
+  },
+  "peerDependencies": {
+    "nostr-tools": "^2.1.4"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.11.0",
+    "@types/ws": "^8.5.10",
+    "@typescript-eslint/eslint-plugin": "^6.18.1",
+    "@typescript-eslint/parser": "^6.18.1",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/humanjavaenterprises/nostr-websocket-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/humanjavaenterprises/nostr-websocket-utils/issues"
+  },
+  "homepage": "https://github.com/humanjavaenterprises/nostr-websocket-utils#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}