nostr-websocket-utils/dist/types/index.d.ts

Robust WebSocket utilities for Nostr applications with automatic reconnection, supporting both ESM and CommonJS. Features channel-based messaging, heartbeat monitoring, message queueing, and comprehensive error handling with type-safe handlers.

/**
 * @file Core type definitions
 * @module types
 */
import type { WebSocket } from 'ws';
import type { Logger } from './logger.js';
import type { NostrWSMessage, NostrEvent as MessageNostrEvent } from './messages.js';
export type { NostrWSMessage } from './messages.js';
export type { QueueItem } from './messages.js';
export * from './filters.js';
export * from './relays.js';
export * from './logger.js';
export * from './priority.js';
export type NostrEvent = MessageNostrEvent;
/**
 * 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 {
    WebSocketImpl?: typeof WebSocket;
    connectionTimeout?: number;
    retryAttempts?: number;
    retryDelay?: number;
    onMessage?: (message: string) => void;
    onError?: (error: Error) => void;
    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;
    /**
     * 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;
}
//# sourceMappingURL=index.d.ts.map