@swarmroom/sdk 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+import type { Agent } from '@swarmroom/shared';
+import type { SwarmRoomClientOptions, MessageHandler, QueryHandler, StatusChangeHandler, SendMessageOptions } from './types.js';
+export declare class SwarmRoomClient {
+    private readonly hubUrl;
+    private readonly _agentName;
+    private readonly agentCardPayload?;
+    private readonly autoHeartbeat;
+    private readonly autoReconnect;
+    private readonly heartbeatInterval;
+    private readonly reconnectDelay;
+    private ws;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private intentionalDisconnect;
+    private _agentId;
+    private _status;
+    private messageHandlers;
+    private queryHandlers;
+    private statusChangeHandlers;
+    get isConnected(): boolean;
+    get agentId(): string | null;
+    get agentName(): string;
+    constructor(options: SwarmRoomClientOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    sendMessage(opts: SendMessageOptions): Promise<unknown>;
+    listAgents(): Promise<Agent[]>;
+    getAgent(id: string): Promise<Agent>;
+    onMessage(handler: MessageHandler): () => void;
+    onQuery(handler: QueryHandler): () => void;
+    onStatusChange(handler: StatusChangeHandler): () => void;
+    private registerAgent;
+    private connectWebSocket;
+    private sendWsRegister;
+    private handleWsMessage;
+    private dispatchMessage;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private setStatus;
+    private httpRequest;
+}

package/dist/client.js

@@ -0,0 +1,258 @@
+import WebSocket from 'ws';
+import { HEARTBEAT_INTERVAL_MS, WS_RECONNECT_DELAY_MS, } from '@swarmroom/shared';
+const MAX_RECONNECT_DELAY_MS = 30_000;
+export class SwarmRoomClient {
+    hubUrl;
+    _agentName;
+    agentCardPayload;
+    autoHeartbeat;
+    autoReconnect;
+    heartbeatInterval;
+    reconnectDelay;
+    ws = null;
+    heartbeatTimer = null;
+    reconnectTimer = null;
+    reconnectAttempts = 0;
+    intentionalDisconnect = false;
+    _agentId = null;
+    _status = 'disconnected';
+    messageHandlers = [];
+    queryHandlers = [];
+    statusChangeHandlers = [];
+    get isConnected() {
+        return this._status === 'connected';
+    }
+    get agentId() {
+        return this._agentId;
+    }
+    get agentName() {
+        return this._agentName;
+    }
+    constructor(options) {
+        this.hubUrl = options.hubUrl.replace(/\/+$/, '');
+        this._agentName = options.name;
+        this.agentCardPayload = options.agentCard;
+        this.autoHeartbeat = options.autoHeartbeat ?? true;
+        this.autoReconnect = options.autoReconnect ?? true;
+        this.heartbeatInterval = options.heartbeatInterval ?? HEARTBEAT_INTERVAL_MS;
+        this.reconnectDelay = options.reconnectDelay ?? WS_RECONNECT_DELAY_MS;
+    }
+    async connect() {
+        this.intentionalDisconnect = false;
+        this.setStatus('connecting');
+        const agent = await this.registerAgent();
+        this._agentId = agent.id;
+        this.connectWebSocket();
+        this.startHeartbeat();
+    }
+    async disconnect() {
+        this.intentionalDisconnect = true;
+        this.stopHeartbeat();
+        this.clearReconnectTimer();
+        if (this._agentId) {
+            try {
+                await this.httpRequest('DELETE', `/api/agents/${this._agentId}`);
+            }
+            catch {
+            }
+        }
+        if (this.ws) {
+            this.ws.close(1000, 'client disconnect');
+            this.ws = null;
+        }
+        this._agentId = null;
+        this.setStatus('disconnected');
+    }
+    async sendMessage(opts) {
+        if (!this._agentId) {
+            throw new Error('Client not connected. Call connect() first.');
+        }
+        const body = {
+            from: this._agentId,
+            to: opts.to,
+            senderType: 'agent',
+            content: opts.content,
+            type: opts.type ?? 'notification',
+        };
+        return this.httpRequest('POST', '/api/messages', body);
+    }
+    async listAgents() {
+        const response = await this.httpRequest('GET', '/api/agents');
+        return response.data;
+    }
+    async getAgent(id) {
+        const response = await this.httpRequest('GET', `/api/agents/${id}`);
+        return response.data;
+    }
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+        return () => {
+            this.messageHandlers = this.messageHandlers.filter((h) => h !== handler);
+        };
+    }
+    onQuery(handler) {
+        this.queryHandlers.push(handler);
+        return () => {
+            this.queryHandlers = this.queryHandlers.filter((h) => h !== handler);
+        };
+    }
+    onStatusChange(handler) {
+        this.statusChangeHandlers.push(handler);
+        return () => {
+            this.statusChangeHandlers = this.statusChangeHandlers.filter((h) => h !== handler);
+        };
+    }
+    async registerAgent() {
+        const body = { name: this._agentName };
+        if (this.agentCardPayload) {
+            body.agentCard = this.agentCardPayload;
+        }
+        const response = await this.httpRequest('POST', '/api/agents', body);
+        return response.data;
+    }
+    connectWebSocket() {
+        const wsUrl = this.hubUrl.replace(/^http/, 'ws') + '/ws';
+        this.ws = new WebSocket(wsUrl);
+        this.ws.on('open', () => {
+            this.reconnectAttempts = 0;
+            this.sendWsRegister();
+            this.setStatus('connected');
+        });
+        this.ws.on('message', (data) => {
+            this.handleWsMessage(String(data));
+        });
+        this.ws.on('close', () => {
+            if (!this.intentionalDisconnect && this.autoReconnect) {
+                this.scheduleReconnect();
+            }
+        });
+        this.ws.on('error', () => {
+            // Error is followed by close event, which handles reconnection
+        });
+    }
+    sendWsRegister() {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this._agentId)
+            return;
+        const msg = {
+            type: 'register',
+            payload: { agentId: this._agentId },
+            timestamp: new Date().toISOString(),
+        };
+        this.ws.send(JSON.stringify(msg));
+    }
+    handleWsMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        switch (msg.type) {
+            case 'message': {
+                const message = msg.payload;
+                this.dispatchMessage(message);
+                break;
+            }
+            case 'heartbeat': {
+                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                    const pong = {
+                        type: 'heartbeat',
+                        payload: { pong: true },
+                        timestamp: new Date().toISOString(),
+                    };
+                    this.ws.send(JSON.stringify(pong));
+                }
+                break;
+            }
+            case 'register':
+            case 'agent_online':
+            case 'agent_offline':
+            case 'error':
+                break;
+        }
+    }
+    dispatchMessage(message) {
+        if (message.type === 'query' && this.queryHandlers.length > 0) {
+            const handler = this.queryHandlers[0];
+            handler(message)
+                .then((responseContent) => {
+                this.sendMessage({
+                    to: message.from,
+                    content: responseContent,
+                    type: 'response',
+                }).catch(() => { });
+            })
+                .catch(() => { });
+            return;
+        }
+        for (const handler of this.messageHandlers) {
+            handler(message);
+        }
+    }
+    startHeartbeat() {
+        if (!this.autoHeartbeat)
+            return;
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(async () => {
+            if (!this._agentId)
+                return;
+            try {
+                await this.httpRequest('POST', `/api/agents/${this._agentId}/heartbeat`, {});
+            }
+            catch {
+            }
+        }, this.heartbeatInterval);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    scheduleReconnect() {
+        this.clearReconnectTimer();
+        this.setStatus('reconnecting');
+        const delay = Math.min(this.reconnectDelay * Math.pow(2, this.reconnectAttempts), MAX_RECONNECT_DELAY_MS);
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(() => {
+            this.connectWebSocket();
+        }, delay);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    setStatus(status) {
+        if (this._status === status)
+            return;
+        this._status = status;
+        for (const handler of this.statusChangeHandlers) {
+            handler(status);
+        }
+    }
+    async httpRequest(method, path, body) {
+        const url = `${this.hubUrl}${path}`;
+        const headers = { 'Content-Type': 'application/json' };
+        const init = { method, headers };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+        const response = await fetch(url, init);
+        if (!response.ok) {
+            let errorMessage = `HTTP ${response.status} ${response.statusText}`;
+            try {
+                const errorBody = (await response.json());
+                if (errorBody.error?.message) {
+                    errorMessage = errorBody.error.message;
+                }
+            }
+            catch {
+            }
+            throw new Error(errorMessage);
+        }
+        return (await response.json());
+    }
+}

package/dist/discovery.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Discover a SwarmRoom hub via mDNS (_swarmroom._tcp).
+ * Requires `@homebridge/ciao` as optional peer dependency — returns null if unavailable.
+ */
+export declare function discoverHub(timeoutMs?: number): Promise<string | null>;

package/dist/discovery.js

@@ -0,0 +1,50 @@
+import { MDNS_SERVICE_TYPE, DEFAULT_PORT } from '@swarmroom/shared';
+/**
+ * Discover a SwarmRoom hub via mDNS (_swarmroom._tcp).
+ * Requires `@homebridge/ciao` as optional peer dependency — returns null if unavailable.
+ */
+export async function discoverHub(timeoutMs = 5000) {
+    let ciao;
+    try {
+        ciao = await import('@homebridge/ciao');
+    }
+    catch {
+        return null;
+    }
+    return new Promise((resolve) => {
+        let resolved = false;
+        const done = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const responder = ciao.getResponder();
+        const timer = setTimeout(() => {
+            responder.shutdown();
+            done(null);
+        }, timeoutMs);
+        try {
+            const service = responder.createService({
+                name: 'swarmroom-browser',
+                type: MDNS_SERVICE_TYPE,
+                port: DEFAULT_PORT,
+            });
+            service.on('name-change', () => {
+                const port = service.port;
+                service.destroy();
+                responder.shutdown();
+                done(`http://localhost:${port}`);
+            });
+            service.advertise().catch(() => {
+                responder.shutdown();
+                done(null);
+            });
+        }
+        catch {
+            responder.shutdown();
+            done(null);
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SwarmRoomClient } from './client.js';
+export { discoverHub } from './discovery.js';
+export type { SwarmRoomClientOptions, ConnectionStatus, MessageHandler, QueryHandler, StatusChangeHandler, IncomingMessage, SendMessageOptions, Agent, AgentStatus, AgentCard, Skill, Message, MessageType, SenderType, WSMessage, WSMessageType, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SwarmRoomClient } from './client.js';
+export { discoverHub } from './discovery.js';

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+export type { Agent, AgentStatus, AgentCard, Skill, RegisterAgentRequest, HeartbeatRequest, Message, MessageType, SenderType, SendMessageRequest, WSMessage, WSMessageType, ApiResponse, } from '@swarmroom/shared';
+export interface SwarmRoomClientOptions {
+    /** Hub URL, e.g. 'http://localhost:3000' */
+    hubUrl: string;
+    /** Agent name for registration */
+    name: string;
+    /** Optional agent card metadata */
+    agentCard?: {
+        description?: string;
+        skills?: Array<{
+            id: string;
+            name: string;
+            description: string;
+            tags: string[];
+        }>;
+    };
+    /** Send heartbeats automatically (default: true) */
+    autoHeartbeat?: boolean;
+    /** Reconnect WebSocket on close (default: true) */
+    autoReconnect?: boolean;
+    /** Heartbeat interval in ms (default: 30000) */
+    heartbeatInterval?: number;
+    /** Initial reconnect delay in ms (default: 3000) */
+    reconnectDelay?: number;
+}
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+export type MessageHandler = (message: IncomingMessage) => void;
+export type QueryHandler = (query: IncomingMessage) => Promise<string>;
+export type StatusChangeHandler = (status: ConnectionStatus) => void;
+export interface IncomingMessage {
+    id: string;
+    from: string;
+    to: string;
+    senderType: string;
+    content: string;
+    type: string;
+    replyTo?: string;
+    metadata?: Record<string, unknown>;
+    read: boolean;
+    createdAt: string;
+}
+export interface SendMessageOptions {
+    to: string;
+    content: string;
+    type?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@swarmroom/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "TypeScript SDK for SwarmRoom - connect AI agents to the SwarmRoom hub",
+  "keywords": ["swarmroom", "sdk", "agent", "mcp", "ai", "client"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/visual-z/swarm.git",
+    "directory": "packages/sdk"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./dist/*": "./dist/*"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@swarmroom/shared": "^0.1.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1"
+  }
+}