nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/types/options.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @file WebSocket client configuration options
+ * @module types/options
+ */
+import WebSocket from 'ws';
+import { NostrWSMessage } from './messages';
+/**
+ * Handler functions for WebSocket events
+ */
+export interface NostrWSHandlers {
+    /**
+     * Handler for incoming messages
+     */
+    message: (message: NostrWSMessage) => Promise<void>;
+    /**
+     * Handler for WebSocket errors
+     */
+    error: (error: Error) => void;
+    /**
+     * Handler for connection close events
+     */
+    close: () => void;
+    /**
+     * Handler for connection state changes
+     */
+    stateChange?: (state: string) => void;
+    /**
+     * Handler for heartbeat events
+     */
+    heartbeat?: () => void;
+    /**
+     * Handler for connection events
+     */
+    connect?: () => void;
+    /**
+     * Handler for disconnection events
+     */
+    disconnect?: () => void;
+    /**
+     * Handler for reconnection events
+     */
+    reconnect?: () => void;
+}
+/**
+ * Connection retry configuration
+ */
+export interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     * @default 10
+     */
+    maxAttempts: number;
+    /**
+     * Initial delay between retries in milliseconds
+     * @default 1000
+     */
+    initialDelay: number;
+    /**
+     * Maximum delay between retries in milliseconds
+     * @default 30000
+     */
+    maxDelay: number;
+    /**
+     * Factor to multiply delay by after each attempt
+     * @default 1.5
+     */
+    backoffFactor: number;
+}
+/**
+ * Queue configuration
+ */
+export interface QueueConfig {
+    /**
+     * Maximum size of the message queue
+     * @default 1000
+     */
+    maxSize: number;
+    /**
+     * Maximum number of retry attempts per message
+     * @default 3
+     */
+    maxRetries: number;
+    /**
+     * Base delay between retries in milliseconds
+     * @default 1000
+     */
+    retryDelay: number;
+    /**
+     * Time in milliseconds after which messages are considered stale
+     * @default 300000 (5 minutes)
+     */
+    staleTimeout: number;
+}
+/**
+ * Heartbeat configuration
+ */
+export interface HeartbeatConfig {
+    /**
+     * Interval between heartbeat pings in milliseconds
+     * @default 30000
+     */
+    interval: number;
+    /**
+     * Timeout for heartbeat response in milliseconds
+     * @default 5000
+     */
+    timeout: number;
+    /**
+     * Maximum missed heartbeats before connection is considered dead
+     * @default 3
+     */
+    maxMissed: number;
+}
+/**
+ * WebSocket client configuration options
+ */
+export interface NostrWSOptions {
+    /**
+     * WebSocket implementation to use
+     * @default ws
+     */
+    WebSocketImpl: typeof WebSocket;
+    /**
+     * Event handlers
+     */
+    handlers: NostrWSHandlers;
+    /**
+     * Retry configuration
+     */
+    retry?: Partial<RetryConfig>;
+    /**
+     * Queue configuration
+     */
+    queue?: Partial<QueueConfig>;
+    /**
+     * Heartbeat configuration
+     */
+    heartbeat?: Partial<HeartbeatConfig>;
+    /**
+     * Whether to automatically reconnect on disconnection
+     * @default true
+     */
+    autoReconnect?: boolean;
+    /**
+     * Whether to buffer messages when disconnected
+     * @default true
+     */
+    bufferMessages?: boolean;
+    /**
+     * Whether to automatically remove stale messages from the queue
+     * @default true
+     */
+    cleanStaleMessages?: boolean;
+}

package/dist/types/options.js

@@ -0,0 +1,5 @@
+/**
+ * @file WebSocket client configuration options
+ * @module types/options
+ */
+export {};

package/dist/types/relays.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file Relay type definitions
+ * @module types/relays
+ */
+/**
+ * Relay information interface
+ */
+export interface NostrRelayInfo {
+    name?: string;
+    description?: string;
+    pubkey?: string;
+    contact?: string;
+    supported_nips?: number[];
+    software?: string;
+    version?: string;
+}
+/**
+ * Relay metadata interface
+ */
+export interface NostrRelayMetadata extends NostrRelayInfo {
+    url: string;
+    status: 'connected' | 'disconnected' | 'error';
+    error?: string;
+    lastConnected?: number;
+    lastDisconnected?: number;
+}

package/dist/types/relays.js

@@ -0,0 +1,5 @@
+/**
+ * @file Relay type definitions
+ * @module types/relays
+ */
+export {};

package/dist/types/scoring.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file Scoring interfaces for connection metrics
+ * @module types/scoring
+ */
+export interface BaseMetrics {
+    totalConnections: number;
+    activeConnections: number;
+    connectionErrors: number;
+    messagesReceived: number;
+    messagesSent: number;
+    bytesReceived: number;
+    bytesSent: number;
+    averageLatency: number;
+    lastSeen: number;
+}
+export interface ScoringStrategy {
+    calculateScore(metrics: BaseMetrics): number;
+}
+export interface MetricsProvider<T extends BaseMetrics = BaseMetrics> {
+    getMetrics(endpoint: string): T;
+    getAllMetrics(): Map<string, T>;
+    trackMetric(endpoint: string, metricType: string, value: any): void;
+}
+export declare const DEFAULT_WEIGHTS: {
+    readonly latency: 0.2;
+    readonly reliability: 0.3;
+    readonly uptime: 0.2;
+    readonly errors: 0.2;
+    readonly activity: 0.1;
+};
+export declare class DefaultScoringStrategy implements ScoringStrategy {
+    private weights;
+    constructor(weights?: {
+        readonly latency: 0.2;
+        readonly reliability: 0.3;
+        readonly uptime: 0.2;
+        readonly errors: 0.2;
+        readonly activity: 0.1;
+    });
+    calculateScore(metrics: BaseMetrics): number;
+}
+export type MetricUpdateEvent = {
+    endpoint: string;
+    metricType: string;
+    value: any;
+    timestamp: number;
+};

package/dist/types/scoring.js

@@ -0,0 +1,29 @@
+/**
+ * @file Scoring interfaces for connection metrics
+ * @module types/scoring
+ */
+// Default scoring weights
+export const DEFAULT_WEIGHTS = {
+    latency: 0.2,
+    reliability: 0.3,
+    uptime: 0.2,
+    errors: 0.2,
+    activity: 0.1,
+};
+// Default scoring strategy
+export class DefaultScoringStrategy {
+    constructor(weights = DEFAULT_WEIGHTS) {
+        this.weights = weights;
+    }
+    calculateScore(metrics) {
+        const now = Date.now();
+        // Basic scoring components that would work for any transport
+        const latencyScore = Math.max(0, 100 - (metrics.averageLatency / 10));
+        const activityScore = metrics.lastSeen ?
+            Math.max(0, 100 - ((now - metrics.lastSeen) / (60 * 1000))) : 0;
+        const errorScore = Math.max(0, 100 - (metrics.connectionErrors * 5));
+        return Math.round((latencyScore * this.weights.latency) +
+            (errorScore * this.weights.errors) +
+            (activityScore * this.weights.activity));
+    }
+}

package/dist/types/socket.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @file Socket type definitions
+ * @module types/socket
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+import type { WebSocket } from 'ws';
+import type { NostrWSMessage } from './messages';
+/**
+ * Extended WebSocket interface with Nostr-specific properties
+ */
+export interface NostrWSSocket extends WebSocket {
+    /**
+     * Unique client ID
+     */
+    clientId?: string;
+    /**
+     * Set of subscribed channels
+     */
+    subscriptions?: Set<string>;
+    /**
+     * Whether the socket is alive (for heartbeat)
+     */
+    isAlive?: boolean;
+    /**
+     * Send a message through the WebSocket
+     */
+    send(message: string | Buffer): void;
+}
+/**
+ * WebSocket client options
+ */
+export interface NostrWSClientOptions {
+    /**
+     * WebSocket implementation to use
+     */
+    WebSocketImpl?: typeof WebSocket;
+    /**
+     * Heartbeat interval in milliseconds
+     */
+    heartbeatInterval?: number;
+    /**
+     * Reconnect interval in milliseconds
+     */
+    reconnectInterval?: number;
+    /**
+     * Maximum number of reconnect attempts
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Message handlers
+     */
+    handlers?: {
+        message?: (message: NostrWSMessage) => Promise<void>;
+        connect?: () => Promise<void>;
+        disconnect?: () => Promise<void>;
+        error?: (error: Error) => Promise<void>;
+    };
+}
+/**
+ * WebSocket server options
+ */
+export interface NostrWSServerOptions {
+    /**
+     * WebSocket server implementation to use
+     */
+    WebSocketImpl?: typeof WebSocket;
+    /**
+     * Heartbeat interval in milliseconds
+     */
+    heartbeatInterval?: number;
+    /**
+     * Message handlers
+     */
+    handlers?: {
+        message?: (ws: NostrWSSocket, message: NostrWSMessage) => Promise<void>;
+        connect?: (ws: NostrWSSocket) => Promise<void>;
+        disconnect?: (ws: NostrWSSocket) => Promise<void>;
+        error?: (ws: NostrWSSocket, error: Error) => Promise<void>;
+    };
+}
+/**
+ * Client event types
+ */
+export type NostrWSClientEvents = {
+    message: (message: NostrWSMessage) => void;
+    connect: () => void;
+    disconnect: () => void;
+    error: (error: Error) => void;
+};
+/**
+ * Server event types
+ */
+export type NostrWSServerEvents = {
+    message: (ws: NostrWSSocket, message: NostrWSMessage) => void;
+    connect: (ws: NostrWSSocket) => void;
+    disconnect: (ws: NostrWSSocket) => void;
+    error: (ws: NostrWSSocket, error: Error) => void;
+};

package/dist/types/socket.js

@@ -0,0 +1,5 @@
+/**
+ * @file Socket type definitions
+ * @module types/socket
+ */
+export {};

package/dist/types/transport.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @file Transport type definitions
+ * @module types/transport
+ */
+import { NostrEvent } from './events';
+import { NostrWSMessage } from './messages';
+/**
+ * Base transport interface
+ */
+export interface Transport {
+    /**
+     * Connect to the transport
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the transport
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a message through the transport
+     */
+    send(message: NostrWSMessage): Promise<void>;
+    /**
+     * Subscribe to events
+     */
+    subscribe(filter: NostrEvent): Promise<void>;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(subscriptionId: string): Promise<void>;
+    /**
+     * Check if transport is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get transport metrics
+     */
+    getMetrics(): TransportMetrics;
+}
+/**
+ * Transport metrics
+ */
+export interface TransportMetrics {
+    /**
+     * Total number of messages sent
+     */
+    messagesSent: number;
+    /**
+     * Total number of messages received
+     */
+    messagesReceived: number;
+    /**
+     * Total number of bytes sent
+     */
+    bytesSent: number;
+    /**
+     * Total number of bytes received
+     */
+    bytesReceived: number;
+    /**
+     * Average message latency in milliseconds
+     */
+    averageLatency: number;
+    /**
+     * Number of active subscriptions
+     */
+    activeSubscriptions: number;
+    /**
+     * Connection uptime in milliseconds
+     */
+    uptime: number;
+    /**
+     * Number of connection attempts
+     */
+    connectionAttempts: number;
+    /**
+     * Number of successful connections
+     */
+    successfulConnections: number;
+    /**
+     * Number of failed connections
+     */
+    failedConnections: number;
+    /**
+     * Transport-specific metrics
+     */
+    [key: string]: number | string | boolean | undefined;
+}
+/**
+ * Transport factory interface
+ */
+export interface TransportFactory {
+    /**
+     * Create a new transport instance
+     */
+    create(options: unknown): Transport;
+}

package/dist/types/transport.js

@@ -0,0 +1,5 @@
+/**
+ * @file Transport type definitions
+ * @module types/transport
+ */
+export {};

package/dist/types/validation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file Validation type definitions
+ * @module types/validation
+ */
+import { NostrEvent } from './events';
+import { NostrWSMessage } from './messages';
+/**
+ * Validation result interface
+ */
+export interface NostrWSValidationResult {
+    /**
+     * Whether the validation passed
+     */
+    isValid: boolean;
+    /**
+     * Error message if validation failed
+     */
+    error?: string;
+}
+/**
+ * Event validator interface
+ */
+export interface NostrEventValidator {
+    /**
+     * Validate a Nostr event
+     */
+    validateEvent(event: NostrEvent): NostrWSValidationResult;
+}
+/**
+ * Message validator interface
+ */
+export interface NostrMessageValidator {
+    /**
+     * Validate a WebSocket message
+     */
+    validateMessage(message: NostrWSMessage): NostrWSValidationResult;
+}
+/**
+ * Validator factory interface
+ */
+export interface ValidatorFactory {
+    /**
+     * Create an event validator
+     */
+    createEventValidator(): NostrEventValidator;
+    /**
+     * Create a message validator
+     */
+    createMessageValidator(): NostrMessageValidator;
+}

package/dist/types/validation.js

@@ -0,0 +1,5 @@
+/**
+ * @file Validation type definitions
+ * @module types/validation
+ */
+export {};

package/dist/types/websocket.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @file WebSocket type definitions and extensions
+ * @module types/websocket
+ */
+import type { WebSocket } from 'ws';
+import type { NostrWSMessage } from './messages';
+import { MessageType } from './messages';
+import { RateLimitConfig } from '../utils/rate-limiter';
+import type { Logger } from './logger';
+/**
+ * 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;
+    /**
+     * Timestamp of the last pong message
+     */
+    lastPong?: number;
+}
+/**
+ * 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
+     */
+    logger: Logger;
+    /**
+     * WebSocket implementation to use
+     */
+    WebSocketImpl: typeof WebSocket;
+}
+/**
+ * State of the NostrWSClient connection
+ * @interface NostrWSConnectionState
+ */
+export interface NostrWSConnectionState {
+    /**
+     * Whether the client is currently connected
+     */
+    isConnected: boolean;
+    /**
+     * Number of reconnection attempts made
+     */
+    reconnectAttempts: number;
+    /**
+     * Last error encountered
+     */
+    lastError?: string;
+}
+/**
+ * Server configuration options
+ * @interface NostrWSServerOptions
+ */
+export interface NostrWSServerOptions {
+    /**
+     * Port to listen on
+     */
+    port: number;
+    /**
+     * Host to bind to
+     */
+    host?: string;
+    /**
+     * Path for the WebSocket endpoint
+     */
+    path?: string;
+    /**
+     * Maximum payload size in bytes
+     */
+    maxPayload?: number;
+    /**
+     * Maximum number of concurrent connections
+     */
+    maxConnections?: number;
+    /**
+     * Ping interval in milliseconds
+     */
+    pingInterval?: number;
+    /**
+     * Rate limiting configuration
+     */
+    rateLimits?: RateLimitConfig;
+    /**
+     * Message handler
+     */
+    onMessage?: (message: NostrWSMessage, socket: NostrWSServerSocket) => Promise<void>;
+    /**
+     * Error handler
+     */
+    onError?: (error: Error, socket: NostrWSServerSocket) => void;
+    /**
+     * Close handler
+     */
+    onClose?: (socket: NostrWSServerSocket) => void;
+    /**
+     * Connection handler
+     */
+    onConnection?: (socket: NostrWSServerSocket) => Promise<void>;
+}
+/**
+ * Server message structure
+ * @interface NostrWSServerMessage
+ */
+export interface NostrWSServerMessage {
+    /**
+     * Message type
+     */
+    type: MessageType;
+    /**
+     * Message data
+     */
+    data?: unknown;
+    /**
+     * Error message if applicable
+     */
+    error?: string;
+}
+/**
+ * Extended WebSocket interface for Nostr server
+ * @interface NostrWSServerSocket
+ */
+export interface NostrWSServerSocket extends WebSocket {
+    clientId: string;
+    subscriptions: Set<string>;
+    lastPing?: number;
+    isAlive: boolean;
+}
+/**
+ * Nostr WebSocket server message with client info
+ * @interface NostrWSServerClientMessage
+ */
+export interface NostrWSServerClientMessage extends NostrWSMessage {
+    clientId?: string;
+    timestamp?: number;
+}