nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/types/index.d.ts

@@ -1,58 +1,137 @@
+/**
+ * @file Core type definitions
+ * @module types
+ */
 import type { WebSocket } from 'ws';
-export type MessageType = 'subscribe' | 'unsubscribe' | 'event' | 'request' | 'response' | 'error' | 'status';
+import type { Logger } from './logger';
+import type { NostrWSMessage } from './messages';
+export * from './messages';
+export * from './events';
+export * from './filters';
+export * from './relays';
+export * from './logger';
+/**
+ * Extended WebSocket interface with client ID
+ */
+export interface ExtendedWebSocket extends WebSocket {
+    clientId?: string;
+    isAlive?: boolean;
+    subscriptions?: Set<string>;
+    lastPing?: number;
+    reconnectAttempts?: number;
+    messageQueue?: NostrWSMessage[];
+}
+/**
+ * WebSocket connection states
+ */
+export declare enum ConnectionState {
+    CONNECTING = "CONNECTING",
+    CONNECTED = "CONNECTED",
+    DISCONNECTED = "DISCONNECTED",
+    RECONNECTING = "RECONNECTING",
+    FAILED = "FAILED"
+}
+/**
+ * Retry configuration options
+ */
+export interface RetryConfig {
+    maxAttempts: number;
+    initialDelay: number;
+    maxDelay: number;
+    backoffFactor: number;
+}
+/**
+ * Queue configuration options
+ */
+export interface QueueConfig {
+    maxSize: number;
+    maxRetries: number;
+    retryDelay: number;
+    staleTimeout: number;
+}
+/**
+ * Heartbeat configuration options
+ */
+export interface HeartbeatConfig {
+    interval: number;
+    timeout: number;
+    maxMissed: number;
+}
+/**
+ * WebSocket client options
+ */
 export interface NostrWSOptions {
-    heartbeatInterval?: number;
-    reconnectInterval?: number;
-    maxReconnectAttempts?: number;
-    logger: Logger;
     WebSocketImpl: typeof WebSocket;
-    handlers: {
-        message: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
-        error?: (ws: WebSocket, error: Error) => void;
-        close?: (ws: WebSocket) => void;
-    };
-}
-export interface NostrWSMessage {
-    type: string;
-    id?: string;
-    data: Record<string, unknown>;
+    handlers: NostrWSClientEvents;
+    retry?: Partial<RetryConfig>;
+    queue?: Partial<QueueConfig>;
+    heartbeat?: Partial<HeartbeatConfig>;
+    autoReconnect?: boolean;
+    bufferMessages?: boolean;
+    cleanStaleMessages?: boolean;
+    logger: Logger;
 }
+/**
+ * Represents a subscription to a Nostr relay
+ */
 export interface NostrWSSubscription {
+    /**
+     * Channel identifier for the subscription
+     */
     channel: string;
+    /**
+     * Filter criteria for the subscription
+     */
     filter?: Record<string, unknown>;
 }
+/**
+ * Events emitted by the NostrWSClient
+ */
 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;
-    message: (message: NostrWSMessage) => void;
+    /**
+     * Emitted when a message is received from the relay
+     * @param message - The received message
+     */
+    message: (message: NostrWSMessage) => Promise<void>;
+    /**
+     * Emitted when an error occurs
+     * @param error - The error that occurred
+     */
     error: (error: Error) => void;
+    close: () => void;
+    stateChange?: (state: ConnectionState) => void;
+    heartbeat?: () => void;
 }
+/**
+ * Events emitted by the NostrWSServer
+ */
 export interface NostrWSServerEvents {
+    /**
+     * Emitted when a client connects
+     * @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 that occurred
+     */
     error: (error: Error) => void;
 }
-export interface ExtendedWebSocket extends WebSocket {
-    isAlive?: boolean;
-    subscriptions?: Set<string>;
-    clientId?: 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;
-    warn: (message: string, ...args: unknown[]) => void;
-    error: (message: string, ...args: unknown[]) => void;
-}

package/dist/types/index.js

@@ -1 +1,21 @@
-export {};
+/**
+ * @file Core type definitions
+ * @module types
+ */
+// Re-export all types
+export * from './messages';
+export * from './events';
+export * from './filters';
+export * from './relays';
+export * from './logger';
+/**
+ * WebSocket connection states
+ */
+export var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["CONNECTING"] = "CONNECTING";
+    ConnectionState["CONNECTED"] = "CONNECTED";
+    ConnectionState["DISCONNECTED"] = "DISCONNECTED";
+    ConnectionState["RECONNECTING"] = "RECONNECTING";
+    ConnectionState["FAILED"] = "FAILED";
+})(ConnectionState || (ConnectionState = {}));

package/dist/types/logger.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Logger type definitions
+ * @module types/logger
+ */
+import type { Logger as PinoLogger } from 'pino';
+export type Logger = PinoLogger;
+/**
+ * WebSocket context for logging
+ */
+export interface WebSocketLogContext {
+    clientId?: string;
+    url?: string;
+    messageId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Extended logger interface with WebSocket-specific methods
+ */
+export interface NostrWSLogger extends Logger {
+    /**
+     * Log WebSocket connection event
+     */
+    wsConnect(context: WebSocketLogContext): void;
+    /**
+     * Log WebSocket disconnection event
+     */
+    wsDisconnect(context: WebSocketLogContext): void;
+    /**
+     * Log WebSocket message event
+     */
+    wsMessage(context: WebSocketLogContext): void;
+    /**
+     * Log WebSocket error event
+     */
+    wsError(error: Error, context: WebSocketLogContext): void;
+    /**
+     * Log WebSocket metrics
+     */
+    wsMetrics(metrics: Record<string, unknown>, context: WebSocketLogContext): void;
+}

package/dist/types/logger.js

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

package/dist/types/messages.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @file Message type definitions for WebSocket communication
+ * @module types/messages
+ */
+/**
+ * Connection states for WebSocket client
+ */
+export declare enum ConnectionState {
+    CONNECTING = "CONNECTING",
+    CONNECTED = "CONNECTED",
+    DISCONNECTED = "DISCONNECTED",
+    RECONNECTING = "RECONNECTING",
+    FAILED = "FAILED"
+}
+/**
+ * Type of message that can be sent through the WebSocket connection
+ * Following NIP-01 and other NIPs message types
+ */
+export type MessageType = 'EVENT' | 'REQ' | 'CLOSE' | 'NOTICE' | 'EOSE' | 'OK' | 'AUTH' | 'COUNT' | 'PING' | 'PONG' | 'error';
+/**
+ * Message priority levels for queue management
+ */
+export declare enum MessagePriority {
+    HIGH = 0,// Critical messages (AUTH, etc.)
+    MEDIUM = 1,// Normal messages (EVENT, REQ)
+    LOW = 2
+}
+/**
+ * Structure of a Nostr WebSocket event
+ */
+export interface NostrWSEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig?: string;
+}
+/**
+ * Structure of a Nostr WebSocket filter
+ */
+export interface NostrWSFilter {
+    ids?: string[];
+    authors?: string[];
+    kinds?: number[];
+    since?: number;
+    until?: number;
+    limit?: number;
+    [key: string]: unknown;
+}
+/**
+ * Structure of messages sent through the WebSocket connection
+ */
+export interface NostrWSMessage {
+    /**
+     * Type of the message following NIP specifications
+     */
+    type: MessageType;
+    /**
+     * Message content - structure depends on type
+     */
+    content?: NostrWSEvent | NostrWSFilter | string | unknown;
+    /**
+     * Optional subscription ID for subscription-based messages
+     */
+    subscription_id?: string;
+    /**
+     * Message priority for queue management
+     */
+    priority?: MessagePriority;
+    /**
+     * Timestamp when the message was queued
+     */
+    queuedAt?: number;
+    /**
+     * Number of retry attempts for this message
+     */
+    retryCount?: number;
+    /**
+     * Additional data for the message
+     */
+    data?: unknown;
+}
+/**
+ * Represents a subscription to a Nostr relay
+ */
+export interface NostrWSSubscription {
+    /**
+     * Unique identifier for the subscription
+     */
+    subscription_id: string;
+    /**
+     * Filters for the subscription
+     */
+    filters: Array<Record<string, unknown>>;
+    /**
+     * Active state of the subscription
+     */
+    active?: boolean;
+    /**
+     * Timestamp when the subscription was created
+     */
+    createdAt?: number;
+}
+/**
+ * Result of validating a NostrWSMessage
+ */
+export interface NostrWSValidationResult {
+    /**
+     * Whether the message is valid
+     */
+    isValid: boolean;
+    /**
+     * Error message if validation failed
+     */
+    error?: string;
+}
+/**
+ * Message types as defined in NIP-01 and other NIPs
+ */
+export declare const MESSAGE_TYPES: {
+    readonly EVENT: "EVENT";
+    readonly REQ: "REQ";
+    readonly CLOSE: "CLOSE";
+    readonly NOTICE: "NOTICE";
+    readonly EOSE: "EOSE";
+    readonly OK: "OK";
+    readonly AUTH: "AUTH";
+    readonly COUNT: "COUNT";
+    readonly PING: "PING";
+    readonly PONG: "PONG";
+    readonly ERROR: "error";
+};
+export type NostrWSMessageType = MessageType;

package/dist/types/messages.js

@@ -0,0 +1,40 @@
+/**
+ * @file Message type definitions for WebSocket communication
+ * @module types/messages
+ */
+/**
+ * Connection states for WebSocket client
+ */
+export var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["CONNECTING"] = "CONNECTING";
+    ConnectionState["CONNECTED"] = "CONNECTED";
+    ConnectionState["DISCONNECTED"] = "DISCONNECTED";
+    ConnectionState["RECONNECTING"] = "RECONNECTING";
+    ConnectionState["FAILED"] = "FAILED";
+})(ConnectionState || (ConnectionState = {}));
+/**
+ * Message priority levels for queue management
+ */
+export var MessagePriority;
+(function (MessagePriority) {
+    MessagePriority[MessagePriority["HIGH"] = 0] = "HIGH";
+    MessagePriority[MessagePriority["MEDIUM"] = 1] = "MEDIUM";
+    MessagePriority[MessagePriority["LOW"] = 2] = "LOW"; // Non-critical messages (PING)
+})(MessagePriority || (MessagePriority = {}));
+/**
+ * Message types as defined in NIP-01 and other NIPs
+ */
+export const MESSAGE_TYPES = {
+    EVENT: 'EVENT',
+    REQ: 'REQ',
+    CLOSE: 'CLOSE',
+    NOTICE: 'NOTICE',
+    EOSE: 'EOSE',
+    OK: 'OK',
+    AUTH: 'AUTH',
+    COUNT: 'COUNT',
+    PING: 'PING',
+    PONG: 'PONG',
+    ERROR: 'error'
+};

package/dist/types/nostr.d.ts

@@ -1,52 +1,133 @@
-import { ExtendedWebSocket } from './index';
-export interface NostrWSEvent {
+/**
+ * @file Nostr protocol type definitions
+ * @module types/nostr
+ */
+import type { WebSocket as WSClient } from 'ws';
+import { Logger } from './logger';
+import type { NostrWSMessage } from './messages';
+import type { NostrEvent } from './events';
+/**
+ * Signed Nostr event with id and signature
+ */
+export interface SignedNostrEvent extends NostrEvent {
+    /**
+     * Event ID (32-bytes lowercase hex of the serialized event data)
+     */
     id: string;
-    pubkey: string;
-    created_at: number;
-    kind: number;
-    tags: string[][];
-    content: string;
+    /**
+     * Signature of the event ID (64-bytes hex of the schnorr signature)
+     */
     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 {
+/**
+ * Extended WebSocket interface for Nostr
+ */
+export interface NostrWSSocket extends WSClient {
+    /**
+     * Whether the socket is alive (for ping/pong)
+     */
+    isAlive?: boolean;
+    /**
+     * Set of active subscription IDs
+     */
     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"
+    /**
+     * Unique client identifier
+     */
+    clientId?: string;
 }
-export type NostrWSServerMessage = [NostrWSMessageType, ...unknown[]];
+/**
+ * Server configuration options
+ */
 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;
+    /**
+     * Ping interval in milliseconds
+     */
+    pingInterval?: number;
+    /**
+     * Client timeout in milliseconds
+     */
+    clientTimeout?: number;
+    /**
+     * Heartbeat interval in milliseconds
+     */
     heartbeatInterval?: number;
-    maxPayloadSize?: number;
-    cors?: {
-        origin: string;
-        methods: string[];
-    };
-    onConnection?: (socket: NostrWSSocket) => void;
-    onDisconnect?: (socket: NostrWSSocket) => void;
-    onError?: (error: Error, socket?: NostrWSSocket) => void;
+    /**
+     * Handlers for various events
+     */
     handlers?: {
-        message: (socket: NostrWSSocket, message: NostrWSServerMessage) => void | Promise<void>;
+        message?: (socket: NostrWSSocket, message: NostrWSServerMessage) => Promise<void>;
         error?: (socket: NostrWSSocket, error: Error) => void;
         close?: (socket: NostrWSSocket) => void;
     };
+    /**
+     * Callback for when a new connection is established
+     */
+    onConnection?: (socket: NostrWSSocket) => void;
+}
+/**
+ * Server message structure
+ */
+export interface NostrWSServerMessage {
+    /**
+     * Message type
+     */
+    type: string;
+    /**
+     * Message data
+     */
+    data?: unknown;
+    /**
+     * Error message if applicable
+     */
+    error?: string;
+}
+/**
+ * Extended WebSocket interface for Nostr server
+ */
+export interface NostrWSServerSocket extends WSClient {
+    clientId: string;
+    subscriptions: Set<string>;
+    lastPing?: number;
+    isAlive: boolean;
+}
+/**
+ * Nostr WebSocket server options
+ */
+export interface NostrWSServerServerOptions {
+    port: number;
+    host?: string;
+    path?: string;
+    logger: Logger;
+    maxClients?: number;
+    pingInterval?: number;
+    pingTimeout?: number;
+    handlers?: {
+        message?: (message: NostrWSServerMessage, ws: NostrWSServerSocket) => Promise<void>;
+        error?: (error: Error, ws: NostrWSServerSocket) => void;
+        close?: (ws: NostrWSServerSocket) => void;
+    };
+}
+/**
+ * Nostr WebSocket server message
+ */
+export interface NostrWSServerServerMessage extends NostrWSMessage {
+    clientId?: string;
+    timestamp?: number;
 }

package/dist/types/nostr.js

@@ -1,10 +1,5 @@
-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 = {}));
+/**
+ * @file Nostr protocol type definitions
+ * @module types/nostr
+ */
+export {};