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