Skip to main content

​
API Reference

The MessagingPeer class is the core component of the Instant Messaging Protocol. It handles connection to the signaling server, peer discovery, message exchange, and encryption/decryption.

​
Constructor

constructor(config: MessagingPeerConfig)
Creates a new MessagingPeer instance. Parameters:
  • config: Configuration object containing:
    • serverUrl: WebSocket URL of the signaling server (the Demos Node managing the messenger instance)
    • clientId: Unique identifier for this peer
    • publicKey: Public key for encryption/decryption
Example: 
const peer = new MessagingPeer({
    serverUrl: "ws://your-signaling-server:3005",
    clientId: "your-unique-id",
    publicKey: mlKemAes.publicKey,
})

​
Methods

connect 
async connect(): Promise<void>
Connects to the signaling server and registers the peer. Returns: Promise that resolves when connected and registered Example: 
await peer.connect()
disconnect 
disconnect(): void
Disconnects from the signaling server. Example: 
peer.disconnect()
register 
register(): void
Registers the peer with the signaling server. Example: 
peer.register()
registerAndWait 
async registerAndWait(): Promise<void>
Registers the peer with the signaling server and waits for confirmation. Returns: Promise that resolves when registration is confirmed Example: 
await peer.registerAndWait()
discoverPeers 
async discoverPeers(): Promise<string[]>
Discovers all connected peers. Returns: Array of peer IDs Example: 
const peers = await peer.discoverPeers()
console.log("Available peers:", peers)
sendMessage 
async sendMessage(targetId: string, message: string): Promise<void>
Sends an encrypted message to a specific peer. Parameters:
  • targetId: ID of the target peer
  • message: Message to send
Example: 
await peer.sendMessage("target-peer-id", "Hello from me!")
requestPublicKey 
async requestPublicKey(peerId: string): Promise<Uint8Array>
Requests a peer’s public key. Parameters:
  • peerId: ID of the peer whose public key to request
Returns: The peer’s public key as a Uint8Array Example: 
const publicKey = await peer.requestPublicKey("target-peer-id")
respondToServer 
respondToServer(questionId: string, response: any): void
Responds to a server question. Parameters:
  • questionId: ID of the question to respond to
  • response: Response to send back to the server
Example: 
peer.respondToServer("question-123", { answer: "This is my answer" })
sendToServerAndWait 
async sendToServerAndWait<T = any>(
    message: Message,
    expectedResponseType: Message["type"],
    options: {
        timeout?: number
        errorHandler?: (error: any) => void
        retryCount?: number
        filterFn?: (message: Message) => boolean
    } = {},
): Promise<T>
Sends a message to the server and waits for a specific response type. Parameters:
  • message: Message to send
  • expectedResponseType: Type of response to wait for
  • options: Additional options:
    • timeout: Timeout in milliseconds (default: 10000)
    • errorHandler: Custom error handler
    • retryCount: Number of retry attempts
    • filterFn: Function to filter messages by additional criteria
Returns: The response payload Example: 
// 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,
    },
)

// With custom error handling
const response = await peer.sendToServerAndWait(
    {
        type: "custom_action",
        payload: { someData: "value" },
    },
    "custom_action_success",
    {
        errorHandler: error => {
            console.error("Custom error handling:", error)
        },
    },
)

// With filtering
const response = await peer.sendToServerAndWait(
    {
        type: "custom_action",
        payload: { someData: "value" },
    },
    "custom_action_success",
    {
        filterFn: message => message.payload.someProperty === expectedValue,
    },
)

​
Event Handlers

onMessage 
onMessage(handler: (message: any, fromId: string) => void): void
Registers a handler for incoming messages. Parameters:
  • handler: Function to call when a message is received
Example: 
peer.onMessage((message, fromId) => {
    console.log(`Message from ${fromId}:`, message)
})
onServerQuestion 
onServerQuestion(handler: (question: any, questionId: string) => void): void
Registers a handler for server questions. Parameters:
  • handler: Function to call when a server question is received
Example: 
peer.onServerQuestion((question, questionId) => {
    console.log("Server asked:", question)

    // Process the question and prepare a response
    const response = { answer: "This is my answer" }

    // Send the response back to the server
    peer.respondToServer(questionId, response)
})
onError 
onError(handler: (error: { type: string; details: string }) => void): void
Registers a handler for errors. Parameters:
  • handler: Function to call when an error occurs
Example: 
peer.onError(error => {
    console.error(`Error: ${error.type} - ${error.details}`)
})
onPeerDisconnected 
onPeerDisconnected(handler: (peerId: string) => void): void
Registers a handler for peer disconnection events. Parameters:
  • handler: Function to call when a peer disconnects
Example: 
peer.onPeerDisconnected(peerId => {
    console.log(`Peer disconnected: ${peerId}`)
})
onConnectionStateChange 
onConnectionStateChange(handler: (state: "connected" | "disconnected" | "reconnecting") => void): void
Registers a handler for connection state changes. Parameters:
  • handler: Function to call when the connection state changes
Example: 
peer.onConnectionStateChange(state => {
    console.log(`Connection state changed: ${state}`)
})

​
Message Types

The Instant Messaging Protocol supports various message types:
  • “register”: Register a new peer with the server
  • “discover”: Request a list of all connected peers
  • “message”: Encrypted peer-to-peer messages
  • “peer_disconnected”: Notification when a peer disconnects
  • “request_public_key”: Request a peer’s public key
  • “public_key_response”: Response containing a peer’s public key
  • “server_question”: Question from the server to a peer
  • “peer_response”: Response from a peer to a server question
  • “debug_question”: Debug message to trigger a server question
  • “error”: Error notification with details

​
Message Interface

export interface Message {
    type:
        | "register"
        | "discover"
        | "message"
        | "peer_disconnected"
        | "request_public_key"
        | "public_key_response"
        | "server_question"
        | "peer_response"
        | "debug_question"
        | "error"
    payload: any
}

​
MessagingPeerConfig Interface

export interface MessagingPeerConfig {
    serverUrl: string
    clientId: string
    publicKey: Uint8Array