nostr-websocket-utils 0.3.0 → 0.3.2

package/dist/cjs/transport/websocket.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * @file WebSocket transport implementation
+ * @module transport/websocket
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketTransport = void 0;
+const ws_1 = __importDefault(require("ws"));
+const base_1 = require("./base");
+const logger_1 = require("../utils/logger");
+const logger = (0, logger_1.getLogger)('WebSocketTransport');
+class WebSocketTransport extends base_1.BaseTransport {
+    constructor(options = {}) {
+        super(options);
+        this.connections = new Map();
+    }
+    async connect(endpoint) {
+        if (this.connections.has(endpoint)) {
+            logger.warn({ endpoint }, 'Already connected to endpoint');
+            return;
+        }
+        try {
+            const ws = new ws_1.default(endpoint);
+            ws.on('open', () => {
+                this.trackMetric(endpoint, 'connection', true);
+                this.trackMetric(endpoint, 'openHandshake', Date.now());
+            });
+            ws.on('close', () => {
+                this.trackMetric(endpoint, 'connection', false);
+                this.trackMetric(endpoint, 'closeHandshake', Date.now());
+                this.connections.delete(endpoint);
+            });
+            ws.on('message', (data) => {
+                const length = data instanceof Buffer ? data.length :
+                    data instanceof ArrayBuffer ? data.byteLength :
+                        data instanceof Array ? data.reduce((acc, buf) => acc + buf.length, 0) : 0;
+                this.trackMetric(endpoint, 'messageReceived', length);
+            });
+            ws.on('error', (error) => {
+                this.trackMetric(endpoint, 'error', error);
+                logger.error({ error, endpoint }, 'WebSocket error');
+            });
+            // Track ping/pong for latency
+            ws.on('ping', () => {
+                this.trackMetric(endpoint, 'ping', Date.now());
+            });
+            ws.on('pong', () => {
+                if (!this.metricsEnabled || !this.metricsProvider)
+                    return;
+                const now = Date.now();
+                const metrics = this.metricsProvider.getMetrics(endpoint);
+                if (!metrics || !metrics.lastSeen)
+                    return;
+                this.trackMetric(endpoint, 'latency', now - metrics.lastSeen);
+            });
+            this.connections.set(endpoint, ws);
+        }
+        catch (error) {
+            this.trackMetric(endpoint, 'connectionError', error);
+            throw error;
+        }
+    }
+    async disconnect(endpoint) {
+        const ws = this.connections.get(endpoint);
+        if (!ws)
+            return;
+        return new Promise((resolve, reject) => {
+            ws.close();
+            ws.on('close', () => {
+                this.connections.delete(endpoint);
+                resolve();
+            });
+            ws.on('error', reject);
+        });
+    }
+    async send(endpoint, data) {
+        const ws = this.connections.get(endpoint);
+        if (!ws)
+            throw new Error(`Not connected to ${endpoint}`);
+        return new Promise((resolve, reject) => {
+            ws.send(data, (error) => {
+                if (error) {
+                    this.trackMetric(endpoint, 'sendError', error);
+                    reject(error);
+                }
+                else {
+                    this.trackMetric(endpoint, 'messageSent', data.length);
+                    resolve();
+                }
+            });
+        });
+    }
+    trackMetric(endpoint, metric, value) {
+        if (this.metricsProvider && this.metricsEnabled) {
+            const metricValue = value instanceof Error ? value.message : String(value);
+            this.metricsProvider.trackMetric(endpoint, metric, metricValue);
+        }
+    }
+    async checkEndpointHealth(endpoint) {
+        try {
+            if (!this.metricsEnabled || !this.metricsProvider) {
+                return true;
+            }
+            const metrics = this.metricsProvider.getMetrics(endpoint);
+            if (!metrics || !metrics.lastSeen) {
+                return true;
+            }
+            const now = Date.now();
+            const elapsed = now - metrics.lastSeen;
+            // If we haven't seen a ping response in 30 seconds, consider unhealthy
+            return elapsed < 30000;
+        }
+        catch (error) {
+            logger.error('Error checking endpoint health:', error);
+            return false;
+        }
+    }
+    /**
+     * Get all active WebSocket connections
+     */
+    getActiveConnections() {
+        return Array.from(this.connections.keys());
+    }
+    /**
+     * Check if connected to endpoint
+     */
+    isConnected(endpoint) {
+        const ws = this.connections.get(endpoint);
+        return ws?.readyState === ws_1.default.OPEN;
+    }
+}
+exports.WebSocketTransport = WebSocketTransport;
+//# sourceMappingURL=websocket.js.map

package/dist/cjs/transport/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../../src/transport/websocket.ts"],"names":[],"mappings":"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"}

package/dist/cjs/types/events.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @file Nostr event type definitions
+ * @module types/events
+ */
+/**
+ * Base Nostr event interface following NIP-01 specification
+ * @see https://github.com/nostr-protocol/nips/blob/master/01.md
+ */
+export interface NostrEvent {
+    /** Event ID in hex format */
+    id: string;
+    /** Public key of the event creator in hex format */
+    pubkey: string;
+    /** Unix timestamp in seconds */
+    created_at: number;
+    /** Event kind number */
+    kind: number;
+    /** Array of tags */
+    tags: string[][];
+    /** Event content */
+    content: string;
+    /** Signature of the event data in hex format */
+    sig: string;
+}
+/**
+ * Signed Nostr event with id and signature
+ * @extends NostrEvent
+ */
+export interface SignedNostrEvent extends NostrEvent {
+    /** Event ID in hex format */
+    id: string;
+    /** Signature of the event data in hex format */
+    sig: string;
+}
+/**
+ * Event validation result
+ */
+export interface NostrEventValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Event subscription filter
+ */
+export interface NostrEventFilter {
+    ids?: string[];
+    authors?: string[];
+    kinds?: number[];
+    since?: number;
+    until?: number;
+    limit?: number;
+    [key: string]: unknown;
+}
+/**
+ * Nostr subscription event interface
+ * Used for creating subscription messages to relays
+ */
+export interface NostrSubscriptionEvent {
+    /** Subscription ID */
+    subscriptionId: string;
+    /** Array of filters */
+    filters: NostrEventFilter[];
+}
+/**
+ * Event handler interface for WebSocket client
+ */
+export interface NostrWSEventHandlers {
+    onMessage?: (message: string) => void;
+    onError?: (error: Error) => void;
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+    onReconnect?: () => void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/cjs/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/types/events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IAEX,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IAEf,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IAEnB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IAEb,oBAAoB;IACpB,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IAEjB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B"}

package/dist/cjs/types/events.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * @file Nostr event type definitions
+ * @module types/events
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=events.js.map

package/dist/cjs/types/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/types/events.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/cjs/types/filters.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Filter type definitions
+ * @module types/filters
+ */
+import { NostrEventFilter } from './events';
+/**
+ * Subscription request filter
+ */
+export interface NostrSubscriptionFilter extends NostrEventFilter {
+    subscriptionId?: string;
+    limit?: number;
+}
+/**
+ * Filter validation result
+ */
+export interface NostrFilterValidationResult {
+    valid: boolean;
+    error?: string;
+}
+//# sourceMappingURL=filters.d.ts.map

package/dist/cjs/types/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../../src/types/filters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/cjs/types/filters.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * @file Filter type definitions
+ * @module types/filters
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=filters.js.map

package/dist/cjs/types/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../../../src/types/filters.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/cjs/types/handlers.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file Handler type definitions for WebSocket events
+ * @module types/handlers
+ */
+import type { WebSocket } from 'ws';
+import type { NostrWSMessage } from './messages';
+import type { ExtendedWebSocket } from './websocket';
+/**
+ * Events emitted by the NostrWSClient
+ * @interface NostrWSClientEvents
+ */
+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) => void;
+    /**
+     * Emitted when an error occurs
+     * @param error - The error object
+     */
+    error: (error: Error) => void;
+}
+/**
+ * Events emitted by the NostrWSServer
+ * @interface NostrWSServerEvents
+ */
+export interface NostrWSServerEvents {
+    /**
+     * Emitted when a client connects to the server
+     * @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 object
+     */
+    error: (error: Error) => void;
+}
+/**
+ * Configuration options for WebSocket handlers
+ * @interface NostrWSHandlers
+ */
+export interface NostrWSHandlers {
+    /**
+     * Handler for incoming messages
+     * @param ws - The WebSocket instance
+     * @param message - The received message
+     */
+    message: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
+    /**
+     * Handler for WebSocket errors
+     * @param ws - The WebSocket instance
+     * @param error - The error object
+     */
+    error?: (ws: WebSocket, error: Error) => void;
+    /**
+     * Handler for WebSocket connection close
+     * @param ws - The WebSocket instance
+     */
+    close?: (ws: WebSocket) => void;
+}
+//# sourceMappingURL=handlers.d.ts.map

package/dist/cjs/types/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/types/handlers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IAEpB;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IAEtB;;;OAGG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAE3C;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAEtE;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,EAAE,CAAC,EAAE,EAAE,iBAAiB,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAElF;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAE9C;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAC;CACjC"}

package/dist/cjs/types/handlers.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * @file Handler type definitions for WebSocket events
+ * @module types/handlers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=handlers.js.map

package/dist/cjs/types/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../src/types/handlers.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/cjs/types/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @file Core type definitions
+ * @module types
+ */
+import type { WebSocket } from 'ws';
+import type { Logger } from './logger';
+import type { NostrWSMessage, NostrEvent as MessageNostrEvent } from './messages';
+export { NostrWSMessage } from './messages';
+export { QueueItem } from './messages';
+export * from './filters';
+export * from './relays';
+export * from './logger';
+export * from './priority';
+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

package/dist/cjs/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/types/index.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * @file Core type definitions
+ * @module types
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionState = void 0;
+__exportStar(require("./filters"), exports);
+__exportStar(require("./relays"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./priority"), exports);
+/**
+ * WebSocket connection states
+ */
+var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["CONNECTING"] = "CONNECTING";
+    ConnectionState["CONNECTED"] = "CONNECTED";
+    ConnectionState["DISCONNECTED"] = "DISCONNECTED";
+    ConnectionState["RECONNECTING"] = "RECONNECTING";
+    ConnectionState["FAILED"] = "FAILED";
+})(ConnectionState || (exports.ConnectionState = ConnectionState = {}));
+//# sourceMappingURL=index.js.map

package/dist/cjs/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;;AASH,4CAA0B;AAC1B,2CAAyB;AACzB,2CAAyB;AACzB,6CAA2B;AAiB3B;;GAEG;AACH,IAAY,eAMX;AAND,WAAY,eAAe;IACzB,4CAAyB,CAAA;IACzB,0CAAuB,CAAA;IACvB,gDAA6B,CAAA;IAC7B,gDAA6B,CAAA;IAC7B,oCAAiB,CAAA;AACnB,CAAC,EANW,eAAe,+BAAf,eAAe,QAM1B"}

package/dist/cjs/types/logger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/cjs/types/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/types/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAEjD,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM;IAC3C;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAE9C;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAEjD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAE9C;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAE1D;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACjF"}

package/dist/cjs/types/logger.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * @file Logger type definitions
+ * @module types/logger
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=logger.js.map

package/dist/cjs/types/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/types/logger.ts"],"names":[],"mappings":";AAAA;;;GAGG"}