@vdoninja/ninja-p2p 0.1.0

package/dist/message-bus.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Message Bus
+ *
+ * Pub/sub messaging layer with:
+ * - Topic-based subscriptions
+ * - Ring buffer message history
+ * - Offline queue for disconnected peers
+ * - Keyword triggers for async bot wakeup
+ *
+ * Zero dependencies on stevesbot internals.
+ */
+import { EventEmitter } from "node:events";
+import type { PeerRegistry } from "./peer-registry.js";
+import { type MessageEnvelope, type MessageType, type PeerIdentity } from "./protocol.js";
+export type KeywordTrigger = {
+    pattern: RegExp;
+    handler: (msg: MessageEnvelope) => void;
+};
+export type SendDataFn = (data: object, target?: unknown) => void;
+export type MessageBusOptions = {
+    /** Max messages kept in history ring buffer. Default: 200. */
+    historySize?: number;
+    /** Max messages queued per offline peer. Default: 50. */
+    offlineQueueSize?: number;
+};
+export declare class MessageBus extends EventEmitter {
+    private readonly identity;
+    private readonly peers;
+    private sendDataFn;
+    /** Our own topic subscriptions. */
+    private readonly subscriptions;
+    /** Ring buffer of recent messages. */
+    private readonly history;
+    private readonly historySize;
+    /** Per-peer offline message queues. Map<streamId, MessageEnvelope[]>. */
+    private readonly offlineQueues;
+    private readonly offlineQueueSize;
+    /** Registered keyword triggers. */
+    private readonly triggers;
+    constructor(identity: PeerIdentity, peers: PeerRegistry, options?: MessageBusOptions);
+    /** Set the low-level send function (provided by VDOBridge after SDK connects). */
+    setSendDataFn(fn: SendDataFn): void;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+    isSubscribed(topic: string): boolean;
+    getSubscriptions(): string[];
+    /** Broadcast a message to all connected peers. */
+    broadcast(type: MessageType, payload: unknown, topic?: string): MessageEnvelope;
+    /** Send a message to a specific peer (by streamId). */
+    send(targetStreamId: string, type: MessageType, payload: unknown): MessageEnvelope;
+    /** Publish a message to a topic (only peers subscribed to that topic receive it).
+     *  Since we can't know remote subscriptions at this layer, we broadcast and let
+     *  receivers filter. The envelope carries the topic for filtering. */
+    publish(topic: string, type: MessageType, payload: unknown): MessageEnvelope;
+    /** Called by VDOBridge when a message arrives. Routes and emits events. */
+    handleIncoming(envelope: MessageEnvelope): void;
+    /** Get the most recent N messages from history. */
+    getHistory(count?: number): MessageEnvelope[];
+    /** Get messages from/to a specific peer. */
+    getHistoryForPeer(streamId: string, count?: number): MessageEnvelope[];
+    /** Get message count. */
+    get historyCount(): number;
+    /** Flush queued messages to a peer that just reconnected. */
+    flushOfflineQueue(streamId: string): MessageEnvelope[];
+    /** Get the number of queued messages for a peer. */
+    getOfflineQueueSize(streamId: string): number;
+    /** Get all peers that have queued messages. */
+    getOfflineQueuePeers(): string[];
+    /** Register a keyword trigger. Returns an ID for removal. */
+    onKeyword(pattern: string | RegExp, handler: (msg: MessageEnvelope) => void): number;
+    /** Remove a trigger by index. */
+    removeTrigger(index: number): void;
+    private rawSend;
+    private addToHistory;
+    private enqueueOffline;
+    private checkTriggers;
+    /** Clear all state. */
+    clear(): void;
+}

package/dist/message-bus.js

@@ -0,0 +1,234 @@
+/**
+ * Message Bus
+ *
+ * Pub/sub messaging layer with:
+ * - Topic-based subscriptions
+ * - Ring buffer message history
+ * - Offline queue for disconnected peers
+ * - Keyword triggers for async bot wakeup
+ *
+ * Zero dependencies on stevesbot internals.
+ */
+import { EventEmitter } from "node:events";
+import { createEnvelope, envelopeToWire, } from "./protocol.js";
+// ── Class ────────────────────────────────────────────────────────────────────
+export class MessageBus extends EventEmitter {
+    identity;
+    peers;
+    sendDataFn = null;
+    /** Our own topic subscriptions. */
+    subscriptions = new Set();
+    /** Ring buffer of recent messages. */
+    history = [];
+    historySize;
+    /** Per-peer offline message queues. Map<streamId, MessageEnvelope[]>. */
+    offlineQueues = new Map();
+    offlineQueueSize;
+    /** Registered keyword triggers. */
+    triggers = [];
+    constructor(identity, peers, options) {
+        super();
+        this.identity = identity;
+        this.peers = peers;
+        this.historySize = options?.historySize ?? 200;
+        this.offlineQueueSize = options?.offlineQueueSize ?? 50;
+    }
+    /** Set the low-level send function (provided by VDOBridge after SDK connects). */
+    setSendDataFn(fn) {
+        this.sendDataFn = fn;
+    }
+    // ── Subscriptions ────────────────────────────────────────────────────────
+    subscribe(topic) {
+        this.subscriptions.add(topic);
+    }
+    unsubscribe(topic) {
+        this.subscriptions.delete(topic);
+    }
+    isSubscribed(topic) {
+        return this.subscriptions.has(topic);
+    }
+    getSubscriptions() {
+        return [...this.subscriptions];
+    }
+    // ── Sending ──────────────────────────────────────────────────────────────
+    /** Broadcast a message to all connected peers. */
+    broadcast(type, payload, topic) {
+        const envelope = createEnvelope(this.identity, type, payload, { topic: topic ?? null });
+        this.addToHistory(envelope);
+        this.rawSend(envelope, null);
+        return envelope;
+    }
+    /** Send a message to a specific peer (by streamId). */
+    send(targetStreamId, type, payload) {
+        const envelope = createEnvelope(this.identity, type, payload, { to: targetStreamId });
+        this.addToHistory(envelope);
+        if (this.peers.isConnected(targetStreamId)) {
+            this.rawSend(envelope, targetStreamId);
+        }
+        else {
+            this.enqueueOffline(targetStreamId, envelope);
+        }
+        return envelope;
+    }
+    /** Publish a message to a topic (only peers subscribed to that topic receive it).
+     *  Since we can't know remote subscriptions at this layer, we broadcast and let
+     *  receivers filter. The envelope carries the topic for filtering. */
+    publish(topic, type, payload) {
+        const envelope = createEnvelope(this.identity, type, payload, { topic });
+        this.addToHistory(envelope);
+        this.rawSend(envelope, null);
+        return envelope;
+    }
+    // ── Receiving ────────────────────────────────────────────────────────────
+    /** Called by VDOBridge when a message arrives. Routes and emits events. */
+    handleIncoming(envelope) {
+        // Skip messages from ourselves
+        if (envelope.from.streamId === this.identity.streamId &&
+            envelope.from.instanceId === this.identity.instanceId) {
+            return;
+        }
+        // Topic filtering: if a topic is set and we're not subscribed, skip
+        // (except announce/ping/pong/history which are always delivered)
+        const alwaysDeliver = new Set(["announce", "skill_update", "ping", "pong", "history_replay", "history_request"]);
+        if (envelope.topic && !alwaysDeliver.has(envelope.type) && !this.subscriptions.has(envelope.topic)) {
+            return;
+        }
+        // Targeted message: only process if addressed to us (or broadcast)
+        if (envelope.to && envelope.to !== this.identity.streamId) {
+            return;
+        }
+        // Update peer last-seen
+        this.peers.touch(envelope.from.streamId);
+        // Store in history
+        this.addToHistory(envelope);
+        // Fire keyword triggers for chat messages
+        if (envelope.type === "chat") {
+            this.checkTriggers(envelope);
+        }
+        // Emit typed event
+        this.emit("message", envelope);
+        this.emit(`message:${envelope.type}`, envelope);
+        if (envelope.topic) {
+            this.emit(`topic:${envelope.topic}`, envelope);
+        }
+    }
+    // ── History ──────────────────────────────────────────────────────────────
+    /** Get the most recent N messages from history. */
+    getHistory(count) {
+        const n = count ?? this.historySize;
+        return this.history.slice(-n);
+    }
+    /** Get messages from/to a specific peer. */
+    getHistoryForPeer(streamId, count) {
+        const n = count ?? 50;
+        return this.history
+            .filter((m) => m.from.streamId === streamId || m.to === streamId)
+            .slice(-n);
+    }
+    /** Get message count. */
+    get historyCount() {
+        return this.history.length;
+    }
+    // ── Offline Queue ────────────────────────────────────────────────────────
+    /** Flush queued messages to a peer that just reconnected. */
+    flushOfflineQueue(streamId) {
+        const queue = this.offlineQueues.get(streamId);
+        if (!queue || queue.length === 0)
+            return [];
+        this.offlineQueues.delete(streamId);
+        // Send each queued message wrapped as history_replay
+        for (const msg of queue) {
+            const replay = createEnvelope(this.identity, "history_replay", msg, { to: streamId });
+            this.rawSend(replay, streamId);
+        }
+        return queue;
+    }
+    /** Get the number of queued messages for a peer. */
+    getOfflineQueueSize(streamId) {
+        return this.offlineQueues.get(streamId)?.length ?? 0;
+    }
+    /** Get all peers that have queued messages. */
+    getOfflineQueuePeers() {
+        return [...this.offlineQueues.keys()].filter((k) => (this.offlineQueues.get(k)?.length ?? 0) > 0);
+    }
+    // ── Keyword Triggers ─────────────────────────────────────────────────────
+    /** Register a keyword trigger. Returns an ID for removal. */
+    onKeyword(pattern, handler) {
+        const re = typeof pattern === "string" ? new RegExp(pattern, "i") : pattern;
+        this.triggers.push({ pattern: re, handler });
+        return this.triggers.length - 1;
+    }
+    /** Remove a trigger by index. */
+    removeTrigger(index) {
+        if (index >= 0 && index < this.triggers.length) {
+            this.triggers.splice(index, 1);
+        }
+    }
+    // ── Internals ────────────────────────────────────────────────────────────
+    rawSend(envelope, target) {
+        if (!this.sendDataFn)
+            return;
+        const wire = envelopeToWire(envelope);
+        if (target) {
+            // Prefer uuid targeting once we know it; streamID targeting can be ambiguous
+            // before announce/rekey completes on some SDK connection paths.
+            const peer = this.peers.getPeer(target);
+            if (peer?.uuid) {
+                this.sendDataFn(wire, { uuid: peer.uuid });
+            }
+            else {
+                this.sendDataFn(wire, { streamID: target });
+            }
+        }
+        else {
+            // Broadcast to all
+            this.sendDataFn(wire);
+        }
+    }
+    addToHistory(envelope) {
+        // Don't store pings/pongs in history
+        if (envelope.type === "ping" || envelope.type === "pong")
+            return;
+        this.history.push(envelope);
+        while (this.history.length > this.historySize) {
+            this.history.shift();
+        }
+    }
+    enqueueOffline(streamId, envelope) {
+        let queue = this.offlineQueues.get(streamId);
+        if (!queue) {
+            queue = [];
+            this.offlineQueues.set(streamId, queue);
+        }
+        queue.push(envelope);
+        while (queue.length > this.offlineQueueSize) {
+            queue.shift();
+        }
+    }
+    checkTriggers(envelope) {
+        const text = typeof envelope.payload === "string"
+            ? envelope.payload
+            : typeof envelope.payload === "object" && envelope.payload !== null
+                ? envelope.payload.text ?? envelope.payload.message ?? ""
+                : "";
+        if (!text)
+            return;
+        for (const trigger of this.triggers) {
+            if (trigger.pattern.test(text)) {
+                try {
+                    trigger.handler(envelope);
+                }
+                catch (err) {
+                    this.emit("error", err);
+                }
+            }
+        }
+    }
+    /** Clear all state. */
+    clear() {
+        this.history.length = 0;
+        this.offlineQueues.clear();
+        this.triggers.length = 0;
+        this.subscriptions.clear();
+    }
+}

package/dist/peer-registry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Peer Registry
+ *
+ * Tracks all known peers in the VDO.Ninja room: their identity, skills,
+ * status, and connection state. Emits events on changes so other layers
+ * (MessageBus, dashboard) can react.
+ *
+ * Zero dependencies on stevesbot internals.
+ */
+import { EventEmitter } from "node:events";
+import type { AnnouncePayload, PeerIdentity, SkillUpdatePayload } from "./protocol.js";
+export type PeerRecord = {
+    streamId: string;
+    uuid: string;
+    identity: PeerIdentity | null;
+    skills: string[];
+    status: string;
+    statusDetail: string;
+    topics: string[];
+    version: string;
+    connectedAt: number;
+    lastSeenAt: number;
+    connected: boolean;
+};
+export interface PeerRegistryEvents {
+    "peer:join": (peer: PeerRecord) => void;
+    "peer:leave": (peer: PeerRecord) => void;
+    "peer:update": (peer: PeerRecord, field: string) => void;
+}
+export declare class PeerRegistry extends EventEmitter {
+    /** streamId -> PeerRecord */
+    private readonly peers;
+    /** uuid -> streamId (reverse lookup, filled after announce) */
+    private readonly uuidToStream;
+    /** Add or re-activate a peer when a WebRTC connection opens. */
+    addPeer(streamId: string, uuid: string): PeerRecord;
+    /** Mark a peer as disconnected but keep its record (for offline queueing). */
+    markDisconnected(identifier: string): PeerRecord | undefined;
+    /** Fully remove a peer record. */
+    removePeer(identifier: string): boolean;
+    /** Rename a temporary uuid-keyed peer record once the real streamId is known. */
+    rekeyPeer(identifier: string, streamId: string): PeerRecord | undefined;
+    /** Update identity and skills from an announce message. */
+    updateFromAnnounce(identifier: string, identity: PeerIdentity, announce: AnnouncePayload): PeerRecord | undefined;
+    /** Update skills/status from a skill_update message. */
+    updateFromSkillUpdate(identifier: string, update: SkillUpdatePayload): PeerRecord | undefined;
+    /** Record a heartbeat (ping/pong/any message). */
+    touch(identifier: string): void;
+    /** Get a peer by streamId or uuid. */
+    getPeer(identifier: string): PeerRecord | undefined;
+    /** Resolve a streamId or uuid to a PeerRecord. */
+    private resolve;
+    /** Check if a peer is connected. */
+    isConnected(identifier: string): boolean;
+    /** Get all currently connected peers. */
+    getConnectedPeers(): PeerRecord[];
+    /** Get all known peers (including disconnected). */
+    getAllPeers(): PeerRecord[];
+    /** Get the number of connected peers. */
+    get connectedCount(): number;
+    /** Get streamId from a uuid. */
+    streamIdForUuid(uuid: string): string | undefined;
+    /** Prune peers that haven't been seen for longer than staleness threshold. */
+    pruneStale(maxAgeMs: number): PeerRecord[];
+    /** Clear all records. */
+    clear(): void;
+    /** Snapshot for serialization (dashboard, status tools). */
+    toJSON(): object[];
+}

package/dist/peer-registry.js

@@ -0,0 +1,200 @@
+/**
+ * Peer Registry
+ *
+ * Tracks all known peers in the VDO.Ninja room: their identity, skills,
+ * status, and connection state. Emits events on changes so other layers
+ * (MessageBus, dashboard) can react.
+ *
+ * Zero dependencies on stevesbot internals.
+ */
+import { EventEmitter } from "node:events";
+// ── Class ────────────────────────────────────────────────────────────────────
+export class PeerRegistry extends EventEmitter {
+    /** streamId -> PeerRecord */
+    peers = new Map();
+    /** uuid -> streamId (reverse lookup, filled after announce) */
+    uuidToStream = new Map();
+    /** Add or re-activate a peer when a WebRTC connection opens. */
+    addPeer(streamId, uuid) {
+        const existing = this.peers.get(streamId);
+        if (existing) {
+            existing.uuid = uuid;
+            existing.connected = true;
+            existing.connectedAt = Date.now();
+            existing.lastSeenAt = Date.now();
+            this.uuidToStream.set(uuid, streamId);
+            this.emit("peer:join", existing);
+            return existing;
+        }
+        const existingByUuid = this.resolve(uuid);
+        if (existingByUuid) {
+            existingByUuid.connected = true;
+            existingByUuid.connectedAt = Date.now();
+            existingByUuid.lastSeenAt = Date.now();
+            this.uuidToStream.set(uuid, existingByUuid.streamId);
+            this.emit("peer:join", existingByUuid);
+            return existingByUuid;
+        }
+        const peer = {
+            streamId,
+            uuid,
+            identity: null,
+            skills: [],
+            status: "online",
+            statusDetail: "",
+            topics: [],
+            version: "",
+            connectedAt: Date.now(),
+            lastSeenAt: Date.now(),
+            connected: true,
+        };
+        this.peers.set(streamId, peer);
+        this.uuidToStream.set(uuid, streamId);
+        this.emit("peer:join", peer);
+        return peer;
+    }
+    /** Mark a peer as disconnected but keep its record (for offline queueing). */
+    markDisconnected(identifier) {
+        const peer = this.resolve(identifier);
+        if (!peer)
+            return undefined;
+        peer.connected = false;
+        peer.lastSeenAt = Date.now();
+        this.emit("peer:leave", peer);
+        return peer;
+    }
+    /** Fully remove a peer record. */
+    removePeer(identifier) {
+        const peer = this.resolve(identifier);
+        if (!peer)
+            return false;
+        this.peers.delete(peer.streamId);
+        this.uuidToStream.delete(peer.uuid);
+        this.emit("peer:leave", peer);
+        return true;
+    }
+    /** Rename a temporary uuid-keyed peer record once the real streamId is known. */
+    rekeyPeer(identifier, streamId) {
+        const peer = this.resolve(identifier);
+        if (!peer)
+            return undefined;
+        if (peer.streamId === streamId)
+            return peer;
+        const existing = this.peers.get(streamId);
+        if (existing && existing !== peer) {
+            this.peers.delete(peer.streamId);
+            this.uuidToStream.set(peer.uuid, existing.streamId);
+            return existing;
+        }
+        this.peers.delete(peer.streamId);
+        peer.streamId = streamId;
+        this.peers.set(streamId, peer);
+        this.uuidToStream.set(peer.uuid, streamId);
+        this.emit("peer:update", peer, "rekey");
+        return peer;
+    }
+    /** Update identity and skills from an announce message. */
+    updateFromAnnounce(identifier, identity, announce) {
+        const peer = this.resolve(identifier);
+        if (!peer)
+            return undefined;
+        peer.identity = identity;
+        peer.skills = announce.skills ?? [];
+        peer.status = announce.status ?? "online";
+        peer.statusDetail = announce.statusDetail ?? "";
+        peer.topics = announce.topics ?? [];
+        peer.version = announce.version ?? "";
+        peer.lastSeenAt = Date.now();
+        this.emit("peer:update", peer, "announce");
+        return peer;
+    }
+    /** Update skills/status from a skill_update message. */
+    updateFromSkillUpdate(identifier, update) {
+        const peer = this.resolve(identifier);
+        if (!peer)
+            return undefined;
+        peer.skills = update.skills ?? peer.skills;
+        peer.status = update.status ?? peer.status;
+        peer.statusDetail = update.statusDetail ?? peer.statusDetail;
+        peer.lastSeenAt = Date.now();
+        this.emit("peer:update", peer, "skill_update");
+        return peer;
+    }
+    /** Record a heartbeat (ping/pong/any message). */
+    touch(identifier) {
+        const peer = this.resolve(identifier);
+        if (peer)
+            peer.lastSeenAt = Date.now();
+    }
+    /** Get a peer by streamId or uuid. */
+    getPeer(identifier) {
+        return this.resolve(identifier);
+    }
+    /** Resolve a streamId or uuid to a PeerRecord. */
+    resolve(identifier) {
+        const direct = this.peers.get(identifier);
+        if (direct)
+            return direct;
+        const streamId = this.uuidToStream.get(identifier);
+        if (streamId)
+            return this.peers.get(streamId);
+        return undefined;
+    }
+    /** Check if a peer is connected. */
+    isConnected(identifier) {
+        return this.resolve(identifier)?.connected ?? false;
+    }
+    /** Get all currently connected peers. */
+    getConnectedPeers() {
+        return [...this.peers.values()].filter((p) => p.connected);
+    }
+    /** Get all known peers (including disconnected). */
+    getAllPeers() {
+        return [...this.peers.values()];
+    }
+    /** Get the number of connected peers. */
+    get connectedCount() {
+        let count = 0;
+        for (const p of this.peers.values()) {
+            if (p.connected)
+                count++;
+        }
+        return count;
+    }
+    /** Get streamId from a uuid. */
+    streamIdForUuid(uuid) {
+        return this.uuidToStream.get(uuid);
+    }
+    /** Prune peers that haven't been seen for longer than staleness threshold. */
+    pruneStale(maxAgeMs) {
+        const now = Date.now();
+        const pruned = [];
+        for (const peer of this.peers.values()) {
+            if (!peer.connected && now - peer.lastSeenAt > maxAgeMs) {
+                this.peers.delete(peer.streamId);
+                this.uuidToStream.delete(peer.uuid);
+                pruned.push(peer);
+            }
+        }
+        return pruned;
+    }
+    /** Clear all records. */
+    clear() {
+        this.peers.clear();
+        this.uuidToStream.clear();
+    }
+    /** Snapshot for serialization (dashboard, status tools). */
+    toJSON() {
+        return [...this.peers.values()].map((p) => ({
+            streamId: p.streamId,
+            name: p.identity?.name ?? p.streamId,
+            role: p.identity?.role ?? "unknown",
+            skills: p.skills,
+            status: p.status,
+            statusDetail: p.statusDetail,
+            connected: p.connected,
+            connectedAt: p.connectedAt,
+            lastSeenAt: p.lastSeenAt,
+        }));
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,57 @@
+/**
+ * P2P Message Protocol
+ *
+ * Defines the wire format for all messages exchanged over VDO.Ninja
+ * WebRTC data channels. This module has zero dependencies on stevesbot
+ * internals — it can be extracted and reused by any bot.
+ */
+export type MessageType = "chat" | "announce" | "skill_update" | "command" | "command_response" | "event" | "ping" | "pong" | "ack" | "history_replay" | "history_request";
+export type PeerIdentity = {
+    streamId: string;
+    role: string;
+    name: string;
+    instanceId: string;
+};
+export type MessageEnvelope = {
+    v: 1;
+    id: string;
+    type: MessageType;
+    from: PeerIdentity;
+    to: string | null;
+    topic: string | null;
+    ts: number;
+    payload: unknown;
+};
+export type AnnouncePayload = {
+    skills: string[];
+    status: string;
+    statusDetail?: string;
+    version: string;
+    topics: string[];
+};
+export type SkillUpdatePayload = {
+    skills: string[];
+    status: string;
+    statusDetail?: string;
+};
+/** Generate a short unique message ID. */
+export declare function createMessageId(): string;
+/** Generate a unique instance ID (per-process, distinguishes restarts). */
+export declare function createInstanceId(): string;
+/** Generate a cryptographically random room name. */
+export declare function generateRoomName(): string;
+/** Create a full message envelope. */
+export declare function createEnvelope(from: PeerIdentity, type: MessageType, payload: unknown, options?: {
+    to?: string | null;
+    topic?: string | null;
+}): MessageEnvelope;
+/** Validate that a received object looks like a MessageEnvelope. */
+export declare function isValidEnvelope(data: unknown): data is MessageEnvelope;
+/** Parse raw data received from a data channel into an envelope. Returns null on failure. */
+export declare function parseEnvelope(raw: unknown): MessageEnvelope | null;
+/**
+ * Wrap a payload into a sendable JSON object.
+ * The VDO.Ninja SDK sends objects via sendData — this ensures our envelope
+ * is the top-level object sent over the wire.
+ */
+export declare function envelopeToWire(envelope: MessageEnvelope): object;