nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/nips/nip-28.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @file NIP-28: Public Chat
+ * @module nips/nip-28
+ * @see https://github.com/nostr-protocol/nips/blob/master/28.md
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Chat event kinds
+ */
+export declare const ChatEventKinds: {
+    readonly CHANNEL_CREATION: 40;
+    readonly CHANNEL_METADATA: 41;
+    readonly CHANNEL_MESSAGE: 42;
+    readonly CHANNEL_HIDE_MESSAGE: 43;
+    readonly CHANNEL_MUTE_USER: 44;
+    readonly USER_MUTE: 45;
+};
+/**
+ * Channel metadata structure
+ */
+export interface ChannelMetadata {
+    name: string;
+    about?: string;
+    picture?: string;
+    rules?: string[];
+    moderators?: string[];
+    pinned?: string[];
+}
+/**
+ * Creates a channel creation message
+ * @param metadata - Channel metadata
+ * @returns {NostrWSMessage} Channel creation event
+ */
+export declare function createChannelCreationEvent(metadata: ChannelMetadata): NostrWSMessage;
+/**
+ * Creates a channel message
+ * @param channelId - Channel ID
+ * @param content - Message content
+ * @param replyTo - Optional ID of message being replied to
+ * @returns {NostrWSMessage} Channel message event
+ */
+export declare function createChannelMessage(channelId: string, content: string, replyTo?: string): NostrWSMessage;
+/**
+ * Creates a message moderation event
+ * @param channelId - Channel ID
+ * @param messageId - Message ID to moderate
+ * @param reason - Moderation reason
+ * @returns {NostrWSMessage} Hide message event
+ */
+export declare function createHideMessageEvent(channelId: string, messageId: string, reason: string): NostrWSMessage;
+/**
+ * Chat message handler interface
+ */
+export interface ChatMessageHandler {
+    /**
+     * Handles incoming chat message
+     * @param message - Chat message
+     * @returns {Promise<void>}
+     */
+    handleMessage(message: NostrWSMessage): Promise<void>;
+    /**
+     * Handles message moderation
+     * @param message - Moderation message
+     * @returns {Promise<void>}
+     */
+    handleModeration(message: NostrWSMessage): Promise<void>;
+}
+/**
+ * Creates a chat message handler
+ * @param logger - Logger instance
+ * @returns {ChatMessageHandler} Message handler
+ */
+export declare function createChatMessageHandler(logger: Logger): ChatMessageHandler;
+/**
+ * Channel subscription manager interface
+ */
+export interface ChannelSubscriptionManager {
+    /**
+     * Subscribes to a channel
+     * @param channelId - Channel ID
+     * @returns {NostrWSMessage} Subscription message
+     */
+    subscribe(channelId: string): NostrWSMessage;
+    /**
+     * Unsubscribes from a channel
+     * @param channelId - Channel ID
+     * @returns {NostrWSMessage} Unsubscribe message
+     */
+    unsubscribe(channelId: string): NostrWSMessage;
+    /**
+     * Gets channel metadata
+     * @param channelId - Channel ID
+     * @returns {Promise<ChannelMetadata | undefined>} Channel metadata
+     */
+    getMetadata(channelId: string): Promise<ChannelMetadata | undefined>;
+}
+/**
+ * Creates a channel subscription manager
+ * @param logger - Logger instance
+ * @returns {ChannelSubscriptionManager} Subscription manager
+ */
+export declare function createChannelSubscriptionManager(logger: Logger): ChannelSubscriptionManager;

package/dist/nips/nip-28.js

@@ -0,0 +1,170 @@
+/**
+ * @file NIP-28: Public Chat
+ * @module nips/nip-28
+ * @see https://github.com/nostr-protocol/nips/blob/master/28.md
+ */
+/**
+ * Chat event kinds
+ */
+export const ChatEventKinds = {
+    CHANNEL_CREATION: 40,
+    CHANNEL_METADATA: 41,
+    CHANNEL_MESSAGE: 42,
+    CHANNEL_HIDE_MESSAGE: 43,
+    CHANNEL_MUTE_USER: 44,
+    USER_MUTE: 45
+};
+/**
+ * Creates a channel creation message
+ * @param metadata - Channel metadata
+ * @returns {NostrWSMessage} Channel creation event
+ */
+export function createChannelCreationEvent(metadata) {
+    return {
+        type: 'EVENT',
+        data: {
+            kind: ChatEventKinds.CHANNEL_CREATION,
+            content: JSON.stringify(metadata),
+            tags: []
+        }
+    };
+}
+/**
+ * Creates a channel message
+ * @param channelId - Channel ID
+ * @param content - Message content
+ * @param replyTo - Optional ID of message being replied to
+ * @returns {NostrWSMessage} Channel message event
+ */
+export function createChannelMessage(channelId, content, replyTo) {
+    const tags = [['e', channelId, '', 'root']];
+    if (replyTo) {
+        tags.push(['e', replyTo, '', 'reply']);
+    }
+    return {
+        type: 'EVENT',
+        data: {
+            kind: ChatEventKinds.CHANNEL_MESSAGE,
+            content,
+            tags
+        }
+    };
+}
+/**
+ * Creates a message moderation event
+ * @param channelId - Channel ID
+ * @param messageId - Message ID to moderate
+ * @param reason - Moderation reason
+ * @returns {NostrWSMessage} Hide message event
+ */
+export function createHideMessageEvent(channelId, messageId, reason) {
+    return {
+        type: 'EVENT',
+        data: {
+            kind: ChatEventKinds.CHANNEL_HIDE_MESSAGE,
+            content: reason,
+            tags: [
+                ['e', channelId, '', 'root'],
+                ['e', messageId, '', 'reply']
+            ]
+        }
+    };
+}
+/**
+ * Creates a chat message handler
+ * @param logger - Logger instance
+ * @returns {ChatMessageHandler} Message handler
+ */
+export function createChatMessageHandler(logger) {
+    return {
+        async handleMessage(message) {
+            try {
+                if (message.type !== 'EVENT' || !message.data)
+                    return;
+                const event = message.data;
+                if (event.kind !== ChatEventKinds.CHANNEL_MESSAGE)
+                    return;
+                // Extract channel ID and reply ID from tags
+                const tags = event.tags;
+                const channelId = tags.find(tag => tag[0] === 'e' && tag[3] === 'root')?.[1];
+                const replyId = tags.find(tag => tag[0] === 'e' && tag[3] === 'reply')?.[1];
+                // Process message
+                logger.debug('Processing chat message', {
+                    channelId,
+                    replyId,
+                    content: event.content
+                });
+                // Additional message processing logic here
+            }
+            catch (error) {
+                logger.error('Error handling chat message:', error);
+            }
+        },
+        async handleModeration(message) {
+            try {
+                if (message.type !== 'EVENT' || !message.data)
+                    return;
+                const event = message.data;
+                if (event.kind !== ChatEventKinds.CHANNEL_HIDE_MESSAGE)
+                    return;
+                // Extract channel and message IDs
+                const tags = event.tags;
+                const channelId = tags.find(tag => tag[0] === 'e' && tag[3] === 'root')?.[1];
+                const messageId = tags.find(tag => tag[0] === 'e' && tag[3] === 'reply')?.[1];
+                // Process moderation
+                logger.debug('Processing message moderation', {
+                    channelId,
+                    messageId,
+                    reason: event.content
+                });
+                // Additional moderation logic here
+            }
+            catch (error) {
+                logger.error('Error handling message moderation:', error);
+            }
+        }
+    };
+}
+/**
+ * Creates a channel subscription manager
+ * @param logger - Logger instance
+ * @returns {ChannelSubscriptionManager} Subscription manager
+ */
+export function createChannelSubscriptionManager(logger) {
+    const subscriptions = new Map(); // channelId -> subscriptionId
+    const metadata = new Map();
+    return {
+        subscribe(channelId) {
+            const subscriptionId = `chat:${channelId}:${Date.now()}`;
+            subscriptions.set(channelId, subscriptionId);
+            return {
+                type: 'REQ',
+                data: {
+                    subscription_id: subscriptionId,
+                    filter: {
+                        kinds: [
+                            ChatEventKinds.CHANNEL_MESSAGE,
+                            ChatEventKinds.CHANNEL_HIDE_MESSAGE
+                        ],
+                        '#e': [channelId]
+                    }
+                }
+            };
+        },
+        unsubscribe(channelId) {
+            const subscriptionId = subscriptions.get(channelId);
+            if (!subscriptionId) {
+                logger.debug(`No subscription found for channel ${channelId}`);
+                return { type: 'CLOSE', data: { subscription_id: '' } };
+            }
+            subscriptions.delete(channelId);
+            return {
+                type: 'CLOSE',
+                data: { subscription_id: subscriptionId }
+            };
+        },
+        async getMetadata(channelId) {
+            return metadata.get(channelId);
+        }
+    };
+}

package/dist/nips/nip-33.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @file NIP-33: Parameterized Replaceable Events
+ * @module nips/nip-33
+ * @see https://github.com/nostr-protocol/nips/blob/master/33.md
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Parameterized replaceable event kinds (30000-39999)
+ */
+export declare const PARAMETERIZED_REPLACEABLE_KINDS: {
+    CATEGORIZED_BOOKMARK: number;
+    CATEGORIZED_HIGHLIGHT: number;
+    CATEGORIZED_PEOPLE_LIST: number;
+    PROFILE_BADGES: number;
+    BADGE_DEFINITION: number;
+    CUSTOM_START: number;
+    CUSTOM_END: number;
+};
+/**
+ * Creates a parameterized replaceable event
+ * @param kind - Event kind
+ * @param content - Event content
+ * @param identifier - Unique identifier for the parameter
+ * @param additionalTags - Additional tags
+ * @returns {NostrWSMessage} Parameterized replaceable event
+ */
+export declare function createParameterizedEvent(kind: number, content: string, identifier: string, additionalTags?: string[][]): NostrWSMessage;
+/**
+ * Validates a parameterized replaceable event
+ * @param message - Message to validate
+ * @param _logger - Logger instance
+ * @returns {boolean} True if valid
+ */
+export declare function validateParameterizedEvent(message: NostrWSMessage, _logger: Logger): boolean;
+/**
+ * Parameterized event manager interface
+ */
+export interface ParameterizedEventManager {
+    /**
+     * Creates a new parameterized event
+     * @param kind - Event kind
+     * @param content - Event content
+     * @param identifier - Parameter identifier
+     * @param tags - Additional tags
+     * @returns {NostrWSMessage} Created event
+     */
+    createEvent(kind: number, content: string, identifier: string, tags?: string[][]): NostrWSMessage;
+    /**
+     * Updates an existing parameterized event
+     * @param kind - Event kind
+     * @param identifier - Parameter identifier
+     * @param content - New content
+     * @returns {NostrWSMessage} Update event
+     */
+    updateEvent(kind: number, identifier: string, content: string): NostrWSMessage;
+    /**
+     * Subscribes to parameterized events
+     * @param kinds - Event kinds to subscribe to
+     * @param identifiers - Parameter identifiers
+     * @returns {NostrWSMessage} Subscription message
+     */
+    subscribe(kinds: number[], identifiers: string[]): NostrWSMessage;
+}
+/**
+ * Creates a parameterized event manager
+ * @param _logger - Logger instance
+ * @returns {ParameterizedEventManager} Event manager
+ */
+export declare function createParameterizedEventManager(_logger: Logger): ParameterizedEventManager;
+/**
+ * Event replacement handler interface
+ */
+export interface EventReplacementHandler {
+    /**
+     * Checks if an event should replace another
+     * @param newEvent - New event
+     * @param existingEvent - Existing event
+     * @returns {boolean} True if should replace
+     */
+    shouldReplace(newEvent: Record<string, unknown>, existingEvent: Record<string, unknown>): boolean;
+    /**
+     * Gets replacement key for an event
+     * @param event - Event to get key for
+     * @returns {string} Replacement key
+     */
+    getReplacementKey(event: Record<string, unknown>): string;
+}
+/**
+ * Creates an event replacement handler
+ * @param _logger - Logger instance
+ * @returns {EventReplacementHandler} Replacement handler
+ */
+export declare function createEventReplacementHandler(_logger: Logger): EventReplacementHandler;

package/dist/nips/nip-33.js

@@ -0,0 +1,133 @@
+/**
+ * @file NIP-33: Parameterized Replaceable Events
+ * @module nips/nip-33
+ * @see https://github.com/nostr-protocol/nips/blob/master/33.md
+ */
+/**
+ * Parameterized replaceable event kinds (30000-39999)
+ */
+export const PARAMETERIZED_REPLACEABLE_KINDS = {
+    CATEGORIZED_BOOKMARK: 30000,
+    CATEGORIZED_HIGHLIGHT: 30001,
+    CATEGORIZED_PEOPLE_LIST: 30002,
+    PROFILE_BADGES: 30008,
+    BADGE_DEFINITION: 30009,
+    CUSTOM_START: 31000,
+    CUSTOM_END: 39999
+};
+/**
+ * Creates a parameterized replaceable event
+ * @param kind - Event kind
+ * @param content - Event content
+ * @param identifier - Unique identifier for the parameter
+ * @param additionalTags - Additional tags
+ * @returns {NostrWSMessage} Parameterized replaceable event
+ */
+export function createParameterizedEvent(kind, content, identifier, additionalTags = []) {
+    return {
+        type: 'EVENT',
+        data: {
+            kind,
+            content,
+            tags: [
+                ['d', identifier],
+                ...additionalTags
+            ]
+        }
+    };
+}
+/**
+ * Validates a parameterized replaceable event
+ * @param message - Message to validate
+ * @param _logger - Logger instance
+ * @returns {boolean} True if valid
+ */
+export function validateParameterizedEvent(message, _logger) {
+    try {
+        if (message.type !== 'EVENT' || !message.data) {
+            return false;
+        }
+        const event = message.data;
+        const kind = event.kind;
+        // Check if kind is in valid range
+        if (kind < 30000 || kind > 39999) {
+            _logger.debug('Invalid kind for parameterized replaceable event');
+            return false;
+        }
+        // Must have exactly one 'd' tag
+        if (!Array.isArray(event.tags)) {
+            _logger.debug('Missing tags array');
+            return false;
+        }
+        const dTags = event.tags.filter(tag => Array.isArray(tag) && tag[0] === 'd' && tag[1]);
+        if (dTags.length !== 1) {
+            _logger.debug('Must have exactly one d tag');
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        _logger.error('Error validating parameterized event:', error);
+        return false;
+    }
+}
+/**
+ * Creates a parameterized event manager
+ * @param _logger - Logger instance
+ * @returns {ParameterizedEventManager} Event manager
+ */
+export function createParameterizedEventManager(_logger) {
+    return {
+        createEvent(kind, content, identifier, tags = []) {
+            return createParameterizedEvent(kind, content, identifier, tags);
+        },
+        updateEvent(kind, identifier, content) {
+            return createParameterizedEvent(kind, content, identifier);
+        },
+        subscribe(kinds, identifiers) {
+            return {
+                type: 'REQ',
+                data: {
+                    filter: {
+                        kinds,
+                        '#d': identifiers
+                    }
+                }
+            };
+        }
+    };
+}
+/**
+ * Creates an event replacement handler
+ * @param _logger - Logger instance
+ * @returns {EventReplacementHandler} Replacement handler
+ */
+export function createEventReplacementHandler(_logger) {
+    return {
+        shouldReplace(newEvent, existingEvent) {
+            try {
+                // Must be same kind
+                if (newEvent.kind !== existingEvent.kind)
+                    return false;
+                // Must have same 'd' tag value
+                const newTags = newEvent.tags;
+                const existingTags = existingEvent.tags;
+                const newDTag = newTags?.find(tag => tag[0] === 'd')?.[1];
+                const existingDTag = existingTags?.find(tag => tag[0] === 'd')?.[1];
+                if (newDTag !== existingDTag)
+                    return false;
+                // Replace if newer
+                return newEvent.created_at > existingEvent.created_at;
+            }
+            catch (error) {
+                _logger.error('Error checking event replacement:', error);
+                return false;
+            }
+        },
+        getReplacementKey(event) {
+            const kind = event.kind;
+            const dTag = event.tags?.find(tag => tag[0] === 'd')?.[1];
+            return `${kind}:${dTag}`;
+        }
+    };
+}

package/dist/nostr-server.d.ts

@@ -1,8 +1,31 @@
 import { NostrWSServerOptions } from './types/nostr';
+/**
+ * Represents a Nostr WebSocket server
+ */
 export declare class NostrWSServer {
+    /**
+     * The underlying WebSocket server instance
+     */
     private server;
+    /**
+     * Logger instance for this server
+     */
     private logger;
+    /**
+     * Creates a new Nostr WebSocket server instance
+     *
+     * @param {NostrWSServerOptions} options - Server configuration options
+     */
     constructor(options: NostrWSServerOptions);
+    /**
+     * Closes the WebSocket server
+     */
     close(): void;
 }
+/**
+ * Creates a new Nostr WebSocket server instance
+ *
+ * @param {NostrWSServerOptions} options - Server configuration options
+ * @returns {NostrWSServer} The created server instance
+ */
 export declare function createWSServer(options: NostrWSServerOptions): NostrWSServer;

package/dist/nostr-server.js

@@ -1,15 +1,36 @@
 import { Server as WebSocketServer } from 'ws';
 import { getLogger } from './utils/logger';
+/**
+ * Represents a Nostr WebSocket server
+ */
 export class NostrWSServer {
+    /**
+     * Creates a new Nostr WebSocket server instance
+     *
+     * @param {NostrWSServerOptions} options - Server configuration options
+     */
     constructor(options) {
+        /**
+         * Logger instance for this server
+         */
         this.logger = getLogger('NostrWSServer');
         this.server = new WebSocketServer({ port: options.port });
+        /**
+         * Handles incoming WebSocket connections
+         *
+         * @param {NostrWSSocket} socket - The connected WebSocket client
+         */
         this.server.on('connection', (socket) => {
             socket.subscriptions = new Set();
             socket.isAlive = true;
             if (options.onConnection) {
                 options.onConnection(socket);
             }
+            /**
+             * Handles incoming messages from the client
+             *
+             * @param {Buffer | ArrayBuffer | Buffer[]} data - The incoming message data
+             */
             const handleMessage = async (data) => {
                 try {
                     const message = JSON.parse(data.toString());
@@ -24,11 +45,19 @@ export class NostrWSServer {
                 }
             };
             socket.on('message', handleMessage);
+            /**
+             * Handles client disconnections
+             */
             socket.on('close', () => {
                 if (options.handlers?.close) {
                     options.handlers.close(socket);
                 }
             });
+            /**
+             * Handles WebSocket errors
+             *
+             * @param {Error} error - The error that occurred
+             */
             socket.on('error', (error) => {
                 if (options.handlers?.error) {
                     options.handlers.error(socket, error);
@@ -45,19 +74,34 @@ export class NostrWSServer {
                     socket.isAlive = false;
                     socket.ping();
                 }, options.heartbeatInterval);
+                /**
+                 * Handles WebSocket pong responses
+                 */
                 socket.on('pong', () => {
                     socket.isAlive = true;
                 });
+                /**
+                 * Handles client disconnections (again, to clear the interval)
+                 */
                 socket.on('close', () => {
                     clearInterval(interval);
                 });
             }
         });
     }
+    /**
+     * Closes the WebSocket server
+     */
     close() {
         this.server.close();
     }
 }
+/**
+ * Creates a new Nostr WebSocket server instance
+ *
+ * @param {NostrWSServerOptions} options - Server configuration options
+ * @returns {NostrWSServer} The created server instance
+ */
 export function createWSServer(options) {
     return new NostrWSServer(options);
 }

package/dist/server.d.ts

@@ -1,12 +1,16 @@
 /// <reference types="node" />
-import { EventEmitter } from 'events';
 import { WebSocketServer } from 'ws';
-import type { NostrWSOptions, NostrWSMessage, ExtendedWebSocket } from './types/index.js';
+import { EventEmitter } from 'events';
+import type { NostrWSOptions, NostrWSMessage } from './types/index.js';
+/**
+ * WebSocket server implementation for Nostr protocol
+ * Extends EventEmitter to provide event-based message handling
+ */
 export declare class NostrWSServer extends EventEmitter {
     private wss;
     private options;
+    private clients;
     private heartbeatInterval;
-    clients: Map<string, ExtendedWebSocket>;
     constructor(wss: WebSocketServer, options?: Partial<NostrWSOptions>);
     private setupServer;
     private handleConnection;
@@ -14,4 +18,10 @@ export declare class NostrWSServer extends EventEmitter {
     broadcast(message: NostrWSMessage): void;
     broadcastToChannel(channel: string, message: NostrWSMessage): void;
     close(): void;
+    /**
+     * Check if a client with the given ID exists
+     * @param clientId - The ID of the client to check
+     * @returns boolean indicating if the client exists
+     */
+    hasClient(clientId: string): boolean;
 }