@kynesyslabs/demosdk 2.1.15 → 2.2.1

package/build/instant_messaging/index.d.ts

@@ -0,0 +1,300 @@
+/**
+ * MessagingPeer class for peer-to-peer communication through a signaling server
+ *
+ * This class handles:
+ * - Connection to signaling server
+ * - Peer registration with public key
+ * - Peer discovery
+ * - Message exchange with other peers
+ * - Public key requests
+ * - Automatic reconnection with exponential backoff
+ *
+ * Message Handling:
+ * - Messages are automatically encrypted when sent and decrypted when received
+ * - To handle incoming messages with type "message", register a handler using onMessage:
+ *   ```typescript
+ *   peer.onMessage((message, fromId) => {
+ *     // Handle the decrypted message here
+ *     console.log(`Message from ${fromId}:`, message);
+ *   });
+ *   ```
+ * - You can register multiple handlers for different purposes (each handler will receive the decrypted message and sender's ID)
+ * - Handlers are executed in the order they are registered
+ * - If no handlers are registered, messages will be silently ignored
+ * - For request-response patterns (like getting a peer's public key), use the Promise-based methods
+ *   that handle the response matching automatically
+ *
+ * Request-Response Pattern:
+ * - The class provides a robust request-response pattern through the sendToServerAndWait method
+ * - This method sends a message to the server and waits for a specific response type
+ * - It supports custom error handling, retry logic, and filtering by additional criteria
+ * - Example usage:
+ *   ```typescript
+ *   // Basic usage
+ *   const response = await peer.sendToServerAndWait(
+ *     {
+ *       type: "custom_action",
+ *       payload: { someData: "value" }
+ *     },
+ *     "custom_action_success"
+ *   );
+ *
+ *   // With retry logic
+ *   const response = await peer.sendToServerAndWait(
+ *     {
+ *       type: "custom_action",
+ *       payload: { someData: "value" }
+ *     },
+ *     "custom_action_success",
+ *     {
+ *       retryCount: 3,
+ *       timeout: 5000
+ *     }
+ *   );
+ *   ```
+ *
+ * Message Types:
+ * - "message": Encrypted peer-to-peer messages
+ *   ```typescript
+ *   // Example of a received message payload
+ *   {
+ *     type: "message",
+ *     payload: {
+ *       message: {
+ *         algorithm: "ml-kem-aes",
+ *         encryptedData: Uint8Array,
+ *         cipherText: Uint8Array
+ *       },
+ *       fromId: "sender-peer-id"
+ *     }
+ *   }
+ *
+ *   // After decryption, handlers receive:
+ *   // message = "Hello, this is the decrypted message"
+ *   // fromId = "sender-peer-id"
+ *   ```
+ *
+ * Complete Example: Building a barebone messenger app and handling incoming messages
+ * ```typescript
+ * // In your application file (e.g., myMessenger.ts)
+ * import { MessagingPeer } from './path/to/instant_messaging';
+ *
+ * // Create a peer instance
+ * const peer = new MessagingPeer({
+ *   serverUrl: 'ws://your-signaling-server:3000',
+ *   clientId: 'your-unique-id',
+ *   publicKey: yourPublicKey // Your ml-kem public key
+ * });
+ *
+ * // Connect to the server
+ * await peer.connect();
+ *
+ * // Register a handler for incoming messages
+ * peer.onMessage((message, fromId) => {
+ *   // Print the message to the console
+ *   console.log(`Message from ${fromId}:`, message);
+ *
+ *   // If you're building a UI, you might update the DOM:
+ *   const messageElement = document.createElement('div');
+ *   messageElement.textContent = `${fromId}: ${message}`;
+ *   document.getElementById('messages-container').appendChild(messageElement);
+ * });
+ *
+ * // Discover other peers
+ * const peers = await peer.discoverPeers();
+ * console.log('Available peers:', peers);
+ *
+ * // Send a message to a specific peer
+ * await peer.sendMessage('target-peer-id', 'Hello from me!');
+ * ```
+ *
+ * Usage:
+ * ```typescript
+ * const peer = new MessagingPeer({
+ *   serverUrl: 'ws://localhost:3000',
+ *   clientId: 'unique-id',
+ *   publicKey: a ml-kem public key
+ * });
+ *
+ * // Connect and register
+ * await peer.connect();
+ *
+ * // Discover other peers
+ * const peers = await peer.discoverPeers();
+ *
+ * // Send a message
+ * await peer.sendMessage('target-peer-id', 'Hello!');
+ *
+ * // Listen for messages
+ * peer.onMessage((message, fromId) => {
+ *   console.log(`Message from ${fromId}:`, message);
+ * });
+ * ```
+ */
+export interface MessagingPeerConfig {
+    serverUrl: string;
+    clientId: string;
+    publicKey: Uint8Array;
+}
+export interface Message {
+    type: "register" | "discover" | "message" | "peer_disconnected" | "request_public_key" | "public_key_response" | "error";
+    payload: any;
+}
+type MessageHandler = (message: any, fromId: string) => void;
+type ErrorHandler = (error: {
+    type: string;
+    details: string;
+}) => void;
+type PeerDisconnectedHandler = (peerId: string) => void;
+type ConnectionStateHandler = (state: "connected" | "disconnected" | "reconnecting") => void;
+export declare class MessagingPeer {
+    ws: WebSocket | null;
+    private config;
+    private messageHandlers;
+    private errorHandlers;
+    private peerDisconnectedHandlers;
+    private connectionStateHandlers;
+    private connectedPeers;
+    private messageQueue;
+    isConnected: boolean;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private baseReconnectDelay;
+    private reconnectTimeout;
+    private isReconnecting;
+    constructor(config: MessagingPeerConfig);
+    /**
+     * Connects to the signaling server and registers the peer
+     * @returns Promise that resolves when connected and registered
+     */
+    connect(): Promise<void>;
+    /**
+     * Establishes WebSocket connection and sets up event handlers
+     */
+    private connectWebSocket;
+    /**
+     * Attempts to reconnect to the server with exponential backoff
+     */
+    private attemptReconnect;
+    /**
+     * Awaits a response for a specific message type
+     * @param messageType - The type of message to wait for
+     * @param filterFn - Optional function to filter messages by additional criteria
+     * @param timeout - Optional timeout in milliseconds (default: 10000)
+     * @returns Promise that resolves with the message payload or rejects with an error
+     */
+    awaitResponse<T = any>(messageType: Message["type"], filterFn?: (message: Message) => boolean, timeout?: number): Promise<T>;
+    /**
+     * Registers the peer with the signaling server
+     */
+    register(): void;
+    /**
+     * Registers the peer with the signaling server and waits for confirmation
+     * @returns Promise that resolves when registration is confirmed
+     */
+    registerAndWait(): Promise<void>;
+    /**
+     * Discovers all connected peers
+     * @returns Promise that resolves with an array of peer IDs
+     */
+    discoverPeers(): Promise<string[]>;
+    /**
+     * Sends a message to a specific peer
+     * @param targetId - The ID of the target peer
+     * @param message - The message to send
+     */
+    sendMessage(targetId: string, message: string): Promise<void>;
+    /**
+     * Requests a peer's public key
+     * @param peerId - The ID of the peer whose public key to request
+     * @returns Promise that resolves with the peer's public key
+     */
+    requestPublicKey(peerId: string): Promise<Uint8Array>;
+    /**
+     * Adds a handler for incoming messages
+     * @param handler - Function to call when a message is received
+     */
+    onMessage(handler: MessageHandler): void;
+    /**
+     * Adds a handler for errors
+     * @param handler - Function to call when an error occurs
+     */
+    onError(handler: ErrorHandler): void;
+    /**
+     * Adds a handler for peer disconnection events
+     * @param handler - Function to call when a peer disconnects
+     */
+    onPeerDisconnected(handler: PeerDisconnectedHandler): void;
+    /**
+     * Adds a handler for connection state changes
+     * @param handler - Function to call when connection state changes
+     */
+    onConnectionStateChange(handler: ConnectionStateHandler): void;
+    /**
+     * Removes a message handler
+     * @param handler - The handler to remove
+     */
+    removeMessageHandler(handler: MessageHandler): void;
+    /**
+     * Removes an error handler
+     * @param handler - The handler to remove
+     */
+    removeErrorHandler(handler: ErrorHandler): void;
+    /**
+     * Removes a peer disconnected handler
+     * @param handler - The handler to remove
+     */
+    removePeerDisconnectedHandler(handler: PeerDisconnectedHandler): void;
+    /**
+     * Removes a connection state change handler
+     * @param handler - The handler to remove
+     */
+    removeConnectionStateHandler(handler: ConnectionStateHandler): void;
+    /**
+     * Closes the connection to the signaling server
+     */
+    disconnect(): void;
+    /**
+     * Sends a message to the signaling server
+     * @param message - The message to send
+     */
+    private sendToServer;
+    /**
+     * Sends a message to the server and waits for a specific response type
+     * @param message - The message to send
+     * @param expectedResponseType - The type of response to wait for
+     * @param options - Additional options for handling the response
+     * @returns Promise that resolves with the response payload or rejects with an error
+     */
+    sendToServerAndWait<T = any>(message: Message, expectedResponseType: Message["type"], options?: {
+        timeout?: number;
+        errorHandler?: (error: any) => void;
+        retryCount?: number;
+        filterFn?: (message: Message) => boolean;
+    }): Promise<T>;
+    /**
+     * Handles incoming messages from the signaling server
+     * @param message - The received message
+     */
+    private handleMessage;
+    /**
+     * Handles errors
+     * @param error - The error to handle
+     */
+    private handleError;
+    /**
+     * Notifies connection state change handlers
+     * @param state - The new connection state
+     */
+    private notifyConnectionState;
+    /**
+     * Adds a temporary message handler that will be removed after handling one message
+     * @param handler - The temporary handler to add
+     */
+    private addTemporaryMessageHandler;
+    /**
+     * Process queued messages
+     */
+    private processMessageQueue;
+}
+export {};