@clawchatsai/connector 0.0.1

package/dist/shim.d.ts

@@ -0,0 +1,61 @@
+/**
+ * HTTP Shim — translates DataChannel RPC messages into fake req/res
+ * objects compatible with server.js handleRequest().
+ *
+ * Per spec section 6.3.1:
+ * - Fake req: Readable stream with .url, .method, .headers
+ * - Fake res: Writable stream (required for pipe() in handleServeFile)
+ */
+import { Readable, Writable } from 'node:stream';
+import type { IncomingHttpHeaders } from 'node:http';
+export interface RpcRequest {
+    id: string;
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface RpcResponse {
+    id: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+type HandleRequestFn = (req: FakeReq, res: FakeRes) => void | Promise<void>;
+/**
+ * Fake IncomingMessage — a Readable stream with HTTP-like properties.
+ */
+declare class FakeReq extends Readable {
+    url: string;
+    method: string;
+    headers: IncomingHttpHeaders;
+    constructor(rpc: RpcRequest);
+    _read(): void;
+}
+/**
+ * Fake ServerResponse — a Writable stream that buffers output.
+ *
+ * Extends Writable so that fs.createReadStream(...).pipe(res) works
+ * (handleServeFile uses pipe()).
+ */
+declare class FakeRes extends Writable {
+    statusCode: number;
+    private _headers;
+    private _chunks;
+    private _resolvePromise;
+    readonly finished: Promise<{
+        status: number;
+        headers: Record<string, string>;
+        body: Buffer;
+    }>;
+    constructor();
+    _write(chunk: Buffer | string, _encoding: string, callback: (error?: Error | null) => void): void;
+    setHeader(name: string, value: string | number): void;
+    writeHead(statusCode: number, headers?: Record<string, string | number>): this;
+    end(chunk?: unknown, encoding?: unknown, _cb?: unknown): this;
+}
+/**
+ * Dispatch an RPC request through handleRequest and return the response.
+ */
+export declare function dispatchRpc(rpc: RpcRequest, handleRequest: HandleRequestFn): Promise<RpcResponse>;
+export {};

package/dist/shim.js

@@ -0,0 +1,154 @@
+/**
+ * HTTP Shim — translates DataChannel RPC messages into fake req/res
+ * objects compatible with server.js handleRequest().
+ *
+ * Per spec section 6.3.1:
+ * - Fake req: Readable stream with .url, .method, .headers
+ * - Fake res: Writable stream (required for pipe() in handleServeFile)
+ */
+import { Readable, Writable } from 'node:stream';
+/**
+ * Fake IncomingMessage — a Readable stream with HTTP-like properties.
+ */
+class FakeReq extends Readable {
+    url;
+    method;
+    headers;
+    constructor(rpc) {
+        super();
+        this.url = rpc.url;
+        this.method = rpc.method;
+        // Lowercase header keys to match Node's IncomingHttpHeaders convention.
+        // Browsers send 'Authorization' but Node expects 'authorization'.
+        const raw = rpc.headers ?? {};
+        const lowered = {};
+        for (const [k, v] of Object.entries(raw))
+            lowered[k.toLowerCase()] = v;
+        this.headers = lowered;
+        // Push body (if any) and signal end — reconstruct binary data from
+        // _blob / _multipart envelope sent by the browser's transport.js
+        if (rpc.body) {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(rpc.body);
+            }
+            catch { /* not JSON — treat as raw string */ }
+            if (parsed && parsed['_blob']) {
+                // Binary blob: { _blob: true, contentType: "audio/webm", data: "<base64>" }
+                const buf = Buffer.from(parsed['data'], 'base64');
+                this.headers['content-type'] = parsed['contentType'] || 'application/octet-stream';
+                this.headers['content-length'] = String(buf.length);
+                this.push(buf);
+            }
+            else if (parsed && parsed['_text']) {
+                // Raw text string (e.g. file content) — push as-is without JSON wrapping
+                this.push(parsed['data']);
+            }
+            else if (parsed && parsed['_multipart']) {
+                // Multipart form data: { _multipart: true, fields: { key: string | { filename, contentType, data } } }
+                const boundary = '----ShellChatBoundary' + Date.now();
+                this.headers['content-type'] = `multipart/form-data; boundary=${boundary}`;
+                const fields = parsed['fields'] || {};
+                const parts = [];
+                for (const [key, value] of Object.entries(fields)) {
+                    if (value && typeof value === 'object' && value['filename']) {
+                        const f = value;
+                        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${key}"; filename="${f.filename}"\r\nContent-Type: ${f.contentType}\r\n\r\n`));
+                        parts.push(Buffer.from(f.data, 'base64'));
+                        parts.push(Buffer.from('\r\n'));
+                    }
+                    else {
+                        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${key}"\r\n\r\n${String(value)}\r\n`));
+                    }
+                }
+                parts.push(Buffer.from(`--${boundary}--\r\n`));
+                const multipartBuf = Buffer.concat(parts);
+                this.headers['content-length'] = String(multipartBuf.length);
+                this.push(multipartBuf);
+            }
+            else {
+                this.push(rpc.body);
+            }
+        }
+        this.push(null);
+    }
+    _read() {
+        // No-op — data already pushed in constructor
+    }
+}
+/**
+ * Fake ServerResponse — a Writable stream that buffers output.
+ *
+ * Extends Writable so that fs.createReadStream(...).pipe(res) works
+ * (handleServeFile uses pipe()).
+ */
+class FakeRes extends Writable {
+    statusCode = 200;
+    _headers = {};
+    _chunks = [];
+    _resolvePromise = null;
+    finished;
+    constructor() {
+        super();
+        this.finished = new Promise((resolve) => {
+            this._resolvePromise = resolve;
+        });
+        // When the Writable stream finishes, resolve the promise
+        this.on('finish', () => {
+            this._resolvePromise?.({
+                status: this.statusCode,
+                headers: { ...this._headers },
+                body: Buffer.concat(this._chunks),
+            });
+        });
+    }
+    // Required by Writable
+    _write(chunk, _encoding, callback) {
+        this._chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        callback();
+    }
+    setHeader(name, value) {
+        this._headers[name.toLowerCase()] = String(value);
+    }
+    writeHead(statusCode, headers) {
+        this.statusCode = statusCode;
+        if (headers) {
+            for (const [k, v] of Object.entries(headers)) {
+                this._headers[k.toLowerCase()] = String(v);
+            }
+        }
+        return this;
+    }
+    // Override end() to handle the (data, encoding) signature used by send()
+    end(chunk, encoding, _cb) {
+        if (chunk != null && typeof chunk !== 'function') {
+            this._chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+        }
+        // Signal Writable stream finish
+        super.end();
+        return this;
+    }
+}
+function tryJsonParse(buf) {
+    try {
+        return buf.toString('utf8');
+    }
+    catch {
+        return buf.toString('base64');
+    }
+}
+/**
+ * Dispatch an RPC request through handleRequest and return the response.
+ */
+export async function dispatchRpc(rpc, handleRequest) {
+    const req = new FakeReq(rpc);
+    const res = new FakeRes();
+    await handleRequest(req, res);
+    const result = await res.finished;
+    return {
+        id: rpc.id,
+        status: result.status,
+        headers: result.headers,
+        body: tryJsonParse(result.body),
+    };
+}

package/dist/signaling-client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * SignalingClient — persistent WSS connection to the ShellChat signaling server.
+ *
+ * Responsibilities:
+ * - Authenticate with the signaling server on connect (gateway-auth)
+ * - Relay ICE offers/answers for WebRTC negotiation
+ * - Report active DataChannel connection count
+ * - Handle server push messages (force-update, account-suspended, device-limit-updated)
+ * - Reconnect with exponential backoff on unintentional disconnects
+ *
+ * Per spec: signaling server sends WS pings every 30s; the `ws` library
+ * handles pong automatically. If no ping is received for 90s (3 missed),
+ * the connection is considered dead and we reconnect.
+ */
+import { EventEmitter } from 'node:events';
+export declare class SignalingClient extends EventEmitter {
+    private readonly serverUrl;
+    private readonly userId;
+    private readonly apiKey;
+    private ws;
+    /** True only after gateway-auth-ok has been received. */
+    private _connected;
+    /**
+     * Set to true by disconnect() or after an auth rejection.
+     * Prevents reconnect loops when the close is intentional.
+     */
+    private intentionalClose;
+    /** Number of consecutive reconnect attempts (resets on successful auth). */
+    private reconnectAttempts;
+    /** Timer handle for the scheduled reconnect. */
+    private reconnectTimer;
+    /** Timer handle for ping-timeout watchdog. */
+    private pingWatchdog;
+    constructor(serverUrl: string, userId: string, apiKey: string);
+    /** Returns true when gateway-auth-ok has been received on the current socket. */
+    get isConnected(): boolean;
+    /**
+     * Open the WebSocket connection and perform the gateway-auth handshake.
+     * Resolves once the socket is open (not necessarily authenticated yet).
+     * Authentication outcome is signalled via 'connected' / 'auth-rejected' /
+     * 'version-rejected' events.
+     */
+    connect(): Promise<void>;
+    /**
+     * Intentionally close the connection. Suppresses reconnection.
+     */
+    disconnect(): void;
+    /**
+     * Send a connection-count report to the signaling server.
+     * Call whenever a DataChannel opens or closes.
+     */
+    reportConnectionCount(active: number): void;
+    /**
+     * Send an ICE answer back to the signaling server in response to an
+     * ice-offer that was forwarded to us by the server.
+     */
+    sendIceAnswer(connectionId: string, sdp: string, candidates: unknown[]): void;
+    /**
+     * Send a trickle ICE candidate from the plugin to a browser via signaling.
+     */
+    sendIceCandidate(connectionId: string, candidate: unknown): void;
+    private _openSocket;
+    private _handleMessage;
+    private _send;
+    private _scheduleReconnect;
+    private _clearReconnectTimer;
+    /**
+     * Restart the 90-second watchdog timer. Called on gateway-auth-ok and on
+     * every received ping frame. If the timer fires, the connection is dead
+     * and we force a reconnect.
+     */
+    private _resetPingWatchdog;
+    private _clearPingWatchdog;
+}

package/dist/signaling-client.js

@@ -0,0 +1,322 @@
+/**
+ * SignalingClient — persistent WSS connection to the ShellChat signaling server.
+ *
+ * Responsibilities:
+ * - Authenticate with the signaling server on connect (gateway-auth)
+ * - Relay ICE offers/answers for WebRTC negotiation
+ * - Report active DataChannel connection count
+ * - Handle server push messages (force-update, account-suspended, device-limit-updated)
+ * - Reconnect with exponential backoff on unintentional disconnects
+ *
+ * Per spec: signaling server sends WS pings every 30s; the `ws` library
+ * handles pong automatically. If no ping is received for 90s (3 missed),
+ * the connection is considered dead and we reconnect.
+ */
+import { EventEmitter } from 'node:events';
+import { WebSocket } from 'ws';
+import { PLUGIN_VERSION } from './index.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Backoff delays in ms: 1s, 2s, 4s, 8s, 16s, capped at 30s */
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+/**
+ * How long to wait without receiving a WS ping before declaring the
+ * connection dead. Signaling server pings every 30s; three missed = 90s.
+ */
+const PING_TIMEOUT_MS = 90_000;
+// ---------------------------------------------------------------------------
+// SignalingClient
+// ---------------------------------------------------------------------------
+export class SignalingClient extends EventEmitter {
+    serverUrl;
+    userId;
+    apiKey;
+    ws = null;
+    /** True only after gateway-auth-ok has been received. */
+    _connected = false;
+    /**
+     * Set to true by disconnect() or after an auth rejection.
+     * Prevents reconnect loops when the close is intentional.
+     */
+    intentionalClose = false;
+    /** Number of consecutive reconnect attempts (resets on successful auth). */
+    reconnectAttempts = 0;
+    /** Timer handle for the scheduled reconnect. */
+    reconnectTimer = null;
+    /** Timer handle for ping-timeout watchdog. */
+    pingWatchdog = null;
+    constructor(serverUrl, userId, apiKey) {
+        super();
+        this.serverUrl = serverUrl;
+        this.userId = userId;
+        this.apiKey = apiKey;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /** Returns true when gateway-auth-ok has been received on the current socket. */
+    get isConnected() {
+        return this._connected;
+    }
+    /**
+     * Open the WebSocket connection and perform the gateway-auth handshake.
+     * Resolves once the socket is open (not necessarily authenticated yet).
+     * Authentication outcome is signalled via 'connected' / 'auth-rejected' /
+     * 'version-rejected' events.
+     */
+    connect() {
+        this.intentionalClose = false;
+        return this._openSocket();
+    }
+    /**
+     * Intentionally close the connection. Suppresses reconnection.
+     */
+    disconnect() {
+        this.intentionalClose = true;
+        this._clearReconnectTimer();
+        this._clearPingWatchdog();
+        this._connected = false;
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    /**
+     * Send a connection-count report to the signaling server.
+     * Call whenever a DataChannel opens or closes.
+     */
+    reportConnectionCount(active) {
+        this._send({ type: 'connection-count', active });
+    }
+    /**
+     * Send an ICE answer back to the signaling server in response to an
+     * ice-offer that was forwarded to us by the server.
+     */
+    sendIceAnswer(connectionId, sdp, candidates) {
+        this._send({ type: 'ice-answer', connectionId, sdp, candidates });
+    }
+    /**
+     * Send a trickle ICE candidate from the plugin to a browser via signaling.
+     */
+    sendIceCandidate(connectionId, candidate) {
+        this._send({ type: 'ice-candidate', connectionId, candidate });
+    }
+    // -------------------------------------------------------------------------
+    // Internal — socket lifecycle
+    // -------------------------------------------------------------------------
+    _openSocket() {
+        return new Promise((resolve, reject) => {
+            // Guard: never open two sockets simultaneously
+            if (this.ws) {
+                this.ws.removeAllListeners();
+                this.ws.close();
+                this.ws = null;
+            }
+            let settled = false;
+            const settle = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            };
+            const socket = new WebSocket(this.serverUrl);
+            this.ws = socket;
+            socket.on('open', () => {
+                // Send gateway-auth as the first message
+                this._send({
+                    type: 'gateway-auth',
+                    userId: this.userId,
+                    apiKey: this.apiKey,
+                    pluginVersion: PLUGIN_VERSION,
+                });
+                // Resolve the connect() promise: the socket is open and auth is in flight
+                settle();
+            });
+            socket.on('ping', () => {
+                // ws library handles sending the pong automatically.
+                // We just need to reset our watchdog timer.
+                this._resetPingWatchdog();
+            });
+            socket.on('message', (raw) => {
+                this._handleMessage(raw);
+            });
+            socket.on('error', (err) => {
+                // Reject connect() if we haven't resolved yet; otherwise log only
+                if (!settled) {
+                    settle(err);
+                }
+                // The 'close' event will fire after 'error', so reconnection is
+                // handled there — no duplicate reconnect scheduling needed here.
+            });
+            socket.on('close', (_code, _reason) => {
+                this._connected = false;
+                this._clearPingWatchdog();
+                this.ws = null;
+                this.emit('disconnected');
+                if (!settled) {
+                    // connect() is still pending — reject it
+                    settle(new Error('WebSocket closed before open'));
+                    return;
+                }
+                if (!this.intentionalClose) {
+                    this._scheduleReconnect();
+                }
+            });
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Internal — message handling
+    // -------------------------------------------------------------------------
+    _handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch {
+            console.error('[SignalingClient] Received non-JSON message, ignoring');
+            return;
+        }
+        const type = msg['type'];
+        switch (type) {
+            case 'gateway-auth-ok': {
+                this._connected = true;
+                this.reconnectAttempts = 0;
+                this._resetPingWatchdog();
+                this.emit('connected');
+                break;
+            }
+            case 'gateway-auth-rejected': {
+                const reason = msg['reason'] ?? 'unknown';
+                console.error(`[SignalingClient] Auth rejected: ${reason}`);
+                // Do not reconnect after auth rejection — the API key is invalid
+                this.intentionalClose = true;
+                this.emit('auth-rejected', reason);
+                break;
+            }
+            case 'version-rejected': {
+                const current = msg['current'] ?? PLUGIN_VERSION;
+                const minimum = msg['minimum'] ?? '';
+                console.error(`[SignalingClient] Version rejected: current=${current}, minimum=${minimum}`);
+                // Do not reconnect — must upgrade first; auto-update logic is in updater.ts
+                this.intentionalClose = true;
+                this.emit('version-rejected', current, minimum);
+                break;
+            }
+            case 'ice-offer': {
+                const offer = {
+                    connectionId: msg['connectionId'] ?? '',
+                    sdp: msg['sdp'] ?? '',
+                    candidates: msg['candidates'] ?? [],
+                };
+                this.emit('ice-offer', offer);
+                break;
+            }
+            case 'ice-servers': {
+                // ICE server config (STUN/TURN) arrives before the offer for a connection.
+                const connectionId = msg['connectionId'] ?? '';
+                const iceServers = msg['iceServers'] ?? [];
+                this.emit('ice-servers', { connectionId, iceServers });
+                break;
+            }
+            case 'ice-candidate': {
+                // Trickle ICE candidate from browser, relayed by signaling server.
+                const connectionId = msg['connectionId'] ?? '';
+                const candidate = msg['candidate'] ?? null;
+                this.emit('ice-candidate', { connectionId, candidate });
+                break;
+            }
+            case 'force-update': {
+                const targetVersion = msg['targetVersion'] ?? '';
+                const reason = msg['reason'] ?? '';
+                this.emit('force-update', targetVersion, reason);
+                break;
+            }
+            case 'account-suspended': {
+                const reason = msg['reason'] ?? '';
+                // Stop reconnecting — account is suspended
+                this.intentionalClose = true;
+                this.emit('account-suspended', reason);
+                break;
+            }
+            case 'device-limit-updated': {
+                const deviceLimit = msg['deviceLimit'] ?? 0;
+                this.emit('device-limit-updated', deviceLimit);
+                break;
+            }
+            default: {
+                // Unknown messages are silently ignored to allow forward compatibility
+                break;
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal — send helper
+    // -------------------------------------------------------------------------
+    _send(payload) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        try {
+            this.ws.send(JSON.stringify(payload));
+        }
+        catch (err) {
+            console.error('[SignalingClient] Send error:', err);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal — reconnection
+    // -------------------------------------------------------------------------
+    _scheduleReconnect() {
+        if (this.intentionalClose)
+            return;
+        // Exponential backoff: 1s * 2^attempt, capped at BACKOFF_MAX_MS
+        const delay = Math.min(BACKOFF_BASE_MS * Math.pow(2, this.reconnectAttempts), BACKOFF_MAX_MS);
+        this.reconnectAttempts++;
+        console.log(`[SignalingClient] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.intentionalClose)
+                return;
+            this._openSocket().catch((err) => {
+                console.error('[SignalingClient] Reconnect failed:', err);
+                // The 'close' event will have already scheduled the next attempt
+            });
+        }, delay);
+    }
+    _clearReconnectTimer() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal — ping watchdog
+    // -------------------------------------------------------------------------
+    /**
+     * Restart the 90-second watchdog timer. Called on gateway-auth-ok and on
+     * every received ping frame. If the timer fires, the connection is dead
+     * and we force a reconnect.
+     */
+    _resetPingWatchdog() {
+        this._clearPingWatchdog();
+        this.pingWatchdog = setTimeout(() => {
+            console.warn('[SignalingClient] No ping received for 90s — connection presumed dead, reconnecting');
+            // Force-close the socket; the 'close' handler will schedule reconnect
+            if (this.ws) {
+                this.ws.terminate();
+                this.ws = null;
+            }
+        }, PING_TIMEOUT_MS);
+    }
+    _clearPingWatchdog() {
+        if (this.pingWatchdog !== null) {
+            clearTimeout(this.pingWatchdog);
+            this.pingWatchdog = null;
+        }
+    }
+}

package/dist/updater.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Auto-update checker for the @clawchatsai/connector plugin.
+ *
+ * Checks the npm registry for newer versions and can trigger
+ * an in-place update via the OpenClaw plugin CLI.
+ */
+export interface UpdateInfo {
+    current: string;
+    latest: string;
+}
+/**
+ * Check npm registry for updates.
+ * Returns UpdateInfo if a newer version is available, null otherwise.
+ * Silently returns null on any network or parse error.
+ */
+export declare function checkForUpdates(): Promise<UpdateInfo | null>;
+/**
+ * Run the OpenClaw plugin update command.
+ * Throws an Error if the command exits with a non-zero code or times out.
+ */
+export declare function performUpdate(): Promise<void>;