@minion-stack/shared 0.1.0 → 0.2.0

package/dist/gateway/client.d.ts

@@ -0,0 +1,73 @@
+import type { EventFrame } from './types.js';
+export declare const PROTOCOL_VERSION = 3;
+export interface GatewayClientOptions {
+    /** WebSocket URL to connect to. */
+    url: string;
+    /**
+     * Optional WebSocket constructor injection (defaults to globalThis.WebSocket).
+     * Pass ws's WebSocket class when running in Node.
+     */
+    WebSocketImpl?: any;
+    /** Second arg to WebSocket constructor (Node ws accepts headers/maxPayload record). */
+    wsConstructorArgs?: [] | [Record<string, unknown>];
+    /**
+     * Called when server sends connect.challenge.
+     * Must return the params object to send with the 'connect' request.
+     */
+    onChallenge: (nonce: string) => Promise<Record<string, unknown>>;
+    /** Called for every inbound event frame except connect.challenge. */
+    onEvent?: (frame: EventFrame) => void | Promise<void>;
+    /** Called when the socket opens (before challenge handshake completes). */
+    onOpen?: () => void;
+    /** Called when the socket closes. */
+    onClose?: (code: number, reason: string) => void;
+    /** Called just before a reconnect delay starts (useful for UI toasts). */
+    onReconnectScheduled?: (delayMs: number) => void;
+    /**
+     * true  = exponential backoff auto-reconnect (browser UX).
+     * false = single-shot; close() is final (Node adapter default).
+     * Default: false.
+     */
+    autoReconnect?: boolean;
+    /** Timeout for the connect() promise (ms). Default: 10000. */
+    connectTimeoutMs?: number;
+    /** Default timeout for request<T>() (ms). Default: 15000. */
+    requestTimeoutMs?: number;
+}
+export declare class GatewayClient {
+    private readonly opts;
+    private ws;
+    /** Increments per connect() call to fence stale socket event handlers. */
+    private generation;
+    private pending;
+    private connectNonce;
+    private connectSent;
+    private reconnectTimer;
+    private backoffMs;
+    private closed;
+    private helloResolve;
+    private helloReject;
+    constructor(opts: GatewayClientOptions);
+    /**
+     * Open the WebSocket and complete the connect.challenge handshake.
+     * Resolves with the HelloOk payload from the server.
+     */
+    connect(): Promise<unknown>;
+    /**
+     * Send a gateway request and resolve with the response payload.
+     * Rejects if not connected or if the request times out.
+     */
+    request<T>(method: string, params?: unknown, opts?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * Gracefully close the connection and cancel any pending reconnect timers.
+     * All pending requests are rejected.
+     */
+    close(code?: number, reason?: string): void;
+    private wireEvents;
+    private handleMessage;
+    private sendConnect;
+    private scheduleReconnect;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/gateway/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/gateway/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IAEH,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjE,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,qCAAqC;IACrC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,aAAa;IAcZ,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZjC,OAAO,CAAC,EAAE,CAAa;IACvB,0EAA0E;IAC1E,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,SAAS,CAAO;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAA2C;IAC/D,OAAO,CAAC,WAAW,CAAuC;gBAE7B,IAAI,EAAE,oBAAoB;IAEvD;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAgDjC;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAmB7F;;;OAGG;IACH,KAAK,CAAC,IAAI,SAAO,EAAE,MAAM,SAAiB,GAAG,IAAI;IAkBjD,OAAO,CAAC,UAAU;IAwElB,OAAO,CAAC,aAAa;YAyBP,WAAW;IAkBzB,OAAO,CAAC,iBAAiB;CAW1B"}

package/dist/gateway/client.js

@@ -0,0 +1,244 @@
+// packages/shared/src/gateway/client.ts
+// Runtime-agnostic GatewayClient — browser uses globalThis.WebSocket, Node uses ws via ./node subpath.
+import { flushPending, handleResponseFrame } from './protocol.js';
+import { uuid } from '../utils/uuid.js';
+export const PROTOCOL_VERSION = 3;
+export class GatewayClient {
+    opts;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ws = null;
+    /** Increments per connect() call to fence stale socket event handlers. */
+    generation = 0;
+    pending = new Map();
+    connectNonce = null;
+    connectSent = false;
+    reconnectTimer = null;
+    backoffMs = 800;
+    closed = false;
+    helloResolve = null;
+    helloReject = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Open the WebSocket and complete the connect.challenge handshake.
+     * Resolves with the HelloOk payload from the server.
+     */
+    async connect() {
+        this.closed = false;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const Impl = this.opts.WebSocketImpl ?? globalThis.WebSocket;
+        if (!Impl)
+            throw new Error('No WebSocket implementation available. Pass WebSocketImpl or run in a browser.');
+        const args = this.opts.wsConstructorArgs ?? [];
+        const gen = ++this.generation;
+        this.connectSent = false;
+        this.connectNonce = null;
+        return new Promise((resolve, reject) => {
+            this.helloResolve = resolve;
+            this.helloReject = reject;
+            let connectTimer = null;
+            const connectTimeoutMs = this.opts.connectTimeoutMs ?? 10000;
+            connectTimer = setTimeout(() => {
+                connectTimer = null;
+                if (this.generation === gen) {
+                    this.helloReject?.(new Error(`connect timed out after ${connectTimeoutMs}ms`));
+                    this.helloResolve = this.helloReject = null;
+                    this.ws?.close();
+                }
+            }, connectTimeoutMs);
+            const origReject = reject;
+            this.helloReject = (err) => {
+                if (connectTimer) {
+                    clearTimeout(connectTimer);
+                    connectTimer = null;
+                }
+                origReject(err);
+            };
+            this.helloResolve = (value) => {
+                if (connectTimer) {
+                    clearTimeout(connectTimer);
+                    connectTimer = null;
+                }
+                resolve(value);
+            };
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                this.ws = new Impl(this.opts.url, ...args);
+                this.wireEvents(gen);
+            }
+            catch (err) {
+                if (connectTimer) {
+                    clearTimeout(connectTimer);
+                    connectTimer = null;
+                }
+                this.helloResolve = this.helloReject = null;
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+    }
+    /**
+     * Send a gateway request and resolve with the response payload.
+     * Rejects if not connected or if the request times out.
+     */
+    async request(method, params, opts) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ws = this.ws;
+        if (!ws || ws.readyState !== 1 /* OPEN */)
+            throw new Error('not connected');
+        const id = uuid();
+        const timeoutMs = opts?.timeoutMs ?? this.opts.requestTimeoutMs ?? 15000;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`request '${method}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => { clearTimeout(timer); resolve(v); },
+                reject: (e) => { clearTimeout(timer); reject(e); },
+            });
+            ws.send(JSON.stringify({ type: 'req', id, method, params }));
+        });
+    }
+    /**
+     * Gracefully close the connection and cancel any pending reconnect timers.
+     * All pending requests are rejected.
+     */
+    close(code = 1000, reason = 'client close') {
+        this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close(code, reason);
+            this.ws = null;
+        }
+        flushPending(this.pending, new Error('disconnected'));
+        this.backoffMs = 800;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    wireEvents(gen) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ws = this.ws;
+        // Normalize Node ws (.on) vs browser WebSocket (addEventListener).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const on = (ev, fn) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (typeof ws.on === 'function') {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                ws.on(ev, fn);
+            }
+            else {
+                ws.addEventListener(ev, (e) => fn(e));
+            }
+        };
+        on('open', () => {
+            if (this.generation !== gen)
+                return;
+            this.opts.onOpen?.();
+        });
+        on('message', (evOrData) => {
+            if (this.generation !== gen)
+                return;
+            // Node ws fires message(data, isBinary); browser fires MessageEvent.
+            let raw;
+            if (typeof evOrData === 'object' &&
+                evOrData !== null &&
+                'data' in evOrData) {
+                raw = String(evOrData.data ?? '');
+            }
+            else {
+                raw = String(evOrData ?? '');
+            }
+            this.handleMessage(raw);
+        });
+        on('close', (evOrCode, reasonBuf) => {
+            if (this.generation !== gen)
+                return;
+            // Node ws close(code, reason: Buffer); browser fires CloseEvent.
+            let code;
+            let reason;
+            if (typeof evOrCode === 'object' && evOrCode !== null && 'code' in evOrCode) {
+                const ev = evOrCode;
+                code = Number(ev.code);
+                reason = ev.reason != null ? String(ev.reason) : '';
+            }
+            else {
+                code = Number(evOrCode ?? 1006);
+                reason = reasonBuf != null ? String(reasonBuf) : '';
+            }
+            this.ws = null;
+            flushPending(this.pending, new Error(`closed (${code}): ${reason}`));
+            this.opts.onClose?.(code, reason);
+            // If connect() promise is still pending (closed before hello completed):
+            if (this.helloReject) {
+                this.helloReject(new Error(`closed before hello (${code})`));
+                this.helloResolve = this.helloReject = null;
+            }
+            if (this.opts.autoReconnect && !this.closed) {
+                this.scheduleReconnect();
+            }
+        });
+        on('error', () => {
+            // close handler fires next — no action needed here.
+        });
+    }
+    handleMessage(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            // Malformed JSON — silently discard (T-07-02 mitigation).
+            return;
+        }
+        if (frame['type'] === 'event') {
+            if (frame['event'] === 'connect.challenge') {
+                const payload = frame['payload'];
+                const nonce = payload && typeof payload.nonce === 'string' ? payload.nonce : null;
+                if (nonce) {
+                    void this.sendConnect(nonce);
+                }
+                return;
+            }
+            void Promise.resolve(this.opts.onEvent?.(frame)).catch(() => { });
+            return;
+        }
+        handleResponseFrame(frame, this.pending);
+    }
+    async sendConnect(nonce) {
+        if (this.connectSent)
+            return;
+        this.connectSent = true;
+        try {
+            const params = await this.opts.onChallenge(nonce);
+            const hello = await this.request('connect', params);
+            // Successful connect — reset backoff.
+            this.backoffMs = 800;
+            this.helloResolve?.(hello);
+            this.helloResolve = this.helloReject = null;
+        }
+        catch (err) {
+            this.helloReject?.(err instanceof Error ? err : new Error(String(err)));
+            this.helloResolve = this.helloReject = null;
+            // Close the socket to trigger reconnect logic if autoReconnect is true.
+            this.ws?.close(4008, 'connect failed');
+        }
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        const delay = this.backoffMs;
+        // Exponential backoff capped at 15000ms (T-07-04 mitigation).
+        this.backoffMs = Math.min(this.backoffMs * 1.7, 15000);
+        this.opts.onReconnectScheduled?.(delay);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.connect().catch(() => { });
+        }, delay);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/gateway/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/gateway/client.ts"],"names":[],"mappings":"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"}

package/dist/gateway/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/gateway/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../src/gateway/client.test.ts"],"names":[],"mappings":""}

package/dist/gateway/client.test.js

@@ -0,0 +1,235 @@
+// packages/shared/src/gateway/client.test.ts
+// Unit tests for GatewayClient using a hand-rolled mock WebSocket.
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { GatewayClient, PROTOCOL_VERSION } from './client.js';
+// ---------------------------------------------------------------------------
+// Mock WebSocket
+// Supports Node ws style (.on()) — that's what the client uses for the mock.
+// ---------------------------------------------------------------------------
+class MockWebSocket {
+    static CONNECTING = 0;
+    static OPEN = 1;
+    static CLOSING = 2;
+    static CLOSED = 3;
+    readyState = MockWebSocket.OPEN; // Start as OPEN so send() works immediately after construction
+    sentMessages = [];
+    listeners = {};
+    // Node ws API
+    on(event, fn) {
+        (this.listeners[event] ??= []).push(fn);
+        return this;
+    }
+    send(data) {
+        this.sentMessages.push(data);
+    }
+    close(code, reason) {
+        this.readyState = MockWebSocket.CLOSED;
+        this.__emit('close', code ?? 1000, reason ?? '');
+    }
+    __emit(event, ...args) {
+        for (const fn of this.listeners[event] ?? [])
+            fn(...args);
+    }
+    // Simulation helpers
+    __simulateOpen() {
+        this.readyState = MockWebSocket.OPEN;
+        this.__emit('open');
+    }
+    __simulateMessage(data) {
+        this.__emit('message', data);
+    }
+    __simulateClose(code, reason) {
+        this.readyState = MockWebSocket.CLOSED;
+        this.__emit('close', code, reason);
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory: build a GatewayClient with injected MockWebSocket
+// connectTimeoutMs set very high so fake timers don't fire the connect timeout.
+// requestTimeoutMs set high for the connect sub-request too.
+// ---------------------------------------------------------------------------
+function makeMockImpl(instance) {
+    return function MockImpl(_url, ..._args) {
+        return instance;
+    };
+}
+function makeClient(mockWs, opts = {}) {
+    return new GatewayClient({
+        url: 'ws://mock-host/gateway',
+        onChallenge: async (_nonce) => ({ token: 'test-token', minProtocol: 3, maxProtocol: 3 }),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        WebSocketImpl: makeMockImpl(mockWs),
+        connectTimeoutMs: 999_999,
+        requestTimeoutMs: 999_999,
+        ...opts,
+    });
+}
+// ---------------------------------------------------------------------------
+// Helper: perform the full connect handshake synchronously with fake timers
+// ---------------------------------------------------------------------------
+async function performConnect(client, mockWs) {
+    const connectPromise = client.connect();
+    // Simulate open + challenge
+    mockWs.__simulateOpen();
+    mockWs.__simulateMessage(JSON.stringify({ type: 'event', event: 'connect.challenge', payload: { nonce: 'test-nonce' } }));
+    // Let the onChallenge async callback resolve
+    await Promise.resolve();
+    await Promise.resolve();
+    // Find the connect request id from sent messages
+    const connectMsg = mockWs.sentMessages.find((m) => {
+        try {
+            return JSON.parse(m).method === 'connect';
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!connectMsg)
+        throw new Error('connect request not sent');
+    const connectReq = JSON.parse(connectMsg);
+    const helloPayload = { type: 'hello-ok', protocol: 3, server: { connId: 'conn-1' } };
+    mockWs.__simulateMessage(JSON.stringify({ type: 'res', id: connectReq.id, ok: true, payload: helloPayload }));
+    return connectPromise;
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('GatewayClient', () => {
+    let mockWs;
+    beforeEach(() => {
+        mockWs = new MockWebSocket();
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it('exports PROTOCOL_VERSION = 3', () => {
+        expect(PROTOCOL_VERSION).toBe(3);
+    });
+    it('resolves connect() with hello payload after challenge handshake', async () => {
+        const client = makeClient(mockWs);
+        const connectPromise = client.connect();
+        // Socket opens → server sends connect.challenge
+        mockWs.__simulateOpen();
+        mockWs.__simulateMessage(JSON.stringify({ type: 'event', event: 'connect.challenge', payload: { nonce: 'abc-nonce' } }));
+        // Let async onChallenge resolve
+        await Promise.resolve();
+        await Promise.resolve();
+        // The client should have sent the 'connect' request
+        const connectMsg = mockWs.sentMessages.find((m) => {
+            try {
+                return JSON.parse(m).method === 'connect';
+            }
+            catch {
+                return false;
+            }
+        });
+        expect(connectMsg).toBeDefined();
+        const connectReq = JSON.parse(connectMsg);
+        const helloPayload = { type: 'hello-ok', protocol: 3, server: { connId: 'conn-1' } };
+        mockWs.__simulateMessage(JSON.stringify({ type: 'res', id: connectReq.id, ok: true, payload: helloPayload }));
+        const result = await connectPromise;
+        expect(result).toEqual(helloPayload);
+    });
+    it('request<T>() matches response by id and resolves', async () => {
+        const client = makeClient(mockWs);
+        await performConnect(client, mockWs);
+        // Now send a real request
+        const reqPromise = client.request('agents.list', { page: 1 });
+        const lastMsg = mockWs.sentMessages.at(-1);
+        const sentReq = JSON.parse(lastMsg);
+        expect(sentReq.method).toBe('agents.list');
+        // Simulate matching response
+        mockWs.__simulateMessage(JSON.stringify({ type: 'res', id: sentReq.id, ok: true, payload: { value: 42 } }));
+        const result = await reqPromise;
+        expect(result).toEqual({ value: 42 });
+    });
+    it('request<T>() rejects after requestTimeoutMs', async () => {
+        // Use a short requestTimeoutMs for this specific test
+        const client = makeClient(mockWs, { requestTimeoutMs: 500 });
+        await performConnect(client, mockWs);
+        const reqPromise = client.request('slow.method');
+        // Advance timers past the request timeout (not connect timeout — that's 999999)
+        vi.advanceTimersByTime(600);
+        await expect(reqPromise).rejects.toThrow("request 'slow.method' timed out after 500ms");
+    });
+    it('close() flushes pending requests with disconnect error', async () => {
+        const client = makeClient(mockWs);
+        await performConnect(client, mockWs);
+        // Queue a request (no response will come)
+        const reqPromise = client.request('pending.method');
+        // close() should flush it immediately
+        client.close();
+        // Pending requests are flushed by the close event handler with the close code/reason.
+        // (MockWebSocket.close() fires synchronously, so the close handler runs before our explicit flush.)
+        await expect(reqPromise).rejects.toThrow(/closed|disconnected/);
+    });
+    it('does not reconnect when autoReconnect is false (default)', async () => {
+        const client = makeClient(mockWs); // autoReconnect not set → defaults to false
+        await performConnect(client, mockWs);
+        const sentCountBefore = mockWs.sentMessages.length;
+        // Simulate unexpected server close
+        mockWs.__simulateClose(1006, 'network gone');
+        // Advance timers — no reconnect should fire
+        vi.advanceTimersByTime(5000);
+        // No new messages on the same socket (reconnect would make a new socket)
+        expect(mockWs.sentMessages.length).toBe(sentCountBefore);
+    });
+    it('schedules reconnect with exponential backoff when autoReconnect is true', async () => {
+        const instances = [];
+        let instanceIdx = 0;
+        const ws1 = new MockWebSocket();
+        const ws2 = new MockWebSocket();
+        instances.push(ws1, ws2);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const MultiImpl = function (_url, ..._args) {
+            return instances[instanceIdx++];
+        };
+        const reconnectDelays = [];
+        const client = new GatewayClient({
+            url: 'ws://mock-host/gateway',
+            onChallenge: async (_nonce) => ({ token: 'x' }),
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            WebSocketImpl: MultiImpl,
+            autoReconnect: true,
+            connectTimeoutMs: 999_999,
+            requestTimeoutMs: 999_999,
+            onReconnectScheduled: (delay) => { reconnectDelays.push(delay); },
+        });
+        // --- First connect ---
+        await performConnect(client, ws1);
+        // --- Trigger close (unexpected) → should schedule reconnect at 800ms ---
+        ws1.__simulateClose(1006, 'gone');
+        expect(reconnectDelays).toEqual([800]);
+        // Advance 800ms → second connect() fires on ws2
+        vi.advanceTimersByTime(800);
+        // Let the reconnect's connect() promise start and its async onChallenge run
+        await Promise.resolve();
+        await Promise.resolve();
+        // ws2 should have been opened and gotten the challenge
+        ws2.__simulateOpen();
+        ws2.__simulateMessage(JSON.stringify({ type: 'event', event: 'connect.challenge', payload: { nonce: 'n2' } }));
+        await Promise.resolve();
+        await Promise.resolve();
+        const connectMsg2 = ws2.sentMessages.find((m) => {
+            try {
+                return JSON.parse(m).method === 'connect';
+            }
+            catch {
+                return false;
+            }
+        });
+        if (connectMsg2) {
+            const req2 = JSON.parse(connectMsg2);
+            ws2.__simulateMessage(JSON.stringify({ type: 'res', id: req2.id, ok: true, payload: { type: 'hello-ok' } }));
+            await Promise.resolve();
+        }
+        // --- Trigger close again → backoff should be ~1360ms (800 * 1.7) ---
+        ws2.__simulateClose(1006, 'gone again');
+        // The second reconnect delay should be 1360 (800 * 1.7)
+        expect(reconnectDelays.length).toBeGreaterThanOrEqual(2);
+        expect(reconnectDelays[1]).toBeCloseTo(1360, -1);
+    });
+});
+//# sourceMappingURL=client.test.js.map

package/dist/gateway/client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../src/gateway/client.test.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,mEAAmE;AACnE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE9D,8EAA8E;AAC9E,iBAAiB;AACjB,6EAA6E;AAC7E,8EAA8E;AAE9E,MAAM,aAAa;IACjB,MAAM,CAAU,UAAU,GAAG,CAAC,CAAC;IAC/B,MAAM,CAAU,IAAI,GAAG,CAAC,CAAC;IACzB,MAAM,CAAU,OAAO,GAAG,CAAC,CAAC;IAC5B,MAAM,CAAU,MAAM,GAAG,CAAC,CAAC;IAE3B,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,+DAA+D;IAChG,YAAY,GAAa,EAAE,CAAC;IAEpB,SAAS,GAAwD,EAAE,CAAC;IAE5E,cAAc;IACd,EAAE,CAAC,KAAa,EAAE,EAAgC;QAChD,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,IAAY;QACf,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,IAAa,EAAE,MAAe;QAClC,IAAI,CAAC,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;IAEO,MAAM,CAAC,KAAa,EAAE,GAAG,IAAe;QAC9C,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED,qBAAqB;IACrB,cAAc;QACZ,IAAI,CAAC,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC;IAED,iBAAiB,CAAC,IAAY;QAC5B,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,MAAc;QAC1C,IAAI,CAAC,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;;AAGH,8EAA8E;AAC9E,6DAA6D;AAC7D,gFAAgF;AAChF,6DAA6D;AAC7D,8EAA8E;AAE9E,SAAS,YAAY,CAAC,QAAuB;IAC3C,OAAO,SAAS,QAAQ,CAAC,IAAY,EAAE,GAAG,KAAgB;QACxD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,MAAqB,EACrB,OAAuF,EAAE;IAEzF,OAAO,IAAI,aAAa,CAAC;QACvB,GAAG,EAAE,wBAAwB;QAC7B,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;QACxF,8DAA8D;QAC9D,aAAa,EAAE,YAAY,CAAC,MAAM,CAAQ;QAC1C,gBAAgB,EAAE,OAAO;QACzB,gBAAgB,EAAE,OAAO;QACzB,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,KAAK,UAAU,cAAc,CAAC,MAAqB,EAAE,MAAqB;IACxE,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACxC,4BAA4B;IAC5B,MAAM,CAAC,cAAc,EAAE,CAAC;IACxB,MAAM,CAAC,iBAAiB,CACtB,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,CAAC,CAChG,CAAC;IACF,6CAA6C;IAC7C,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IACxB,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IACxB,iDAAiD;IACjD,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;QAChD,IAAI,CAAC;YAAC,OAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,CAAyB,CAAC,MAAM,KAAK,SAAS,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,KAAK,CAAC;QAAC,CAAC;IACrG,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAmB,CAAC;IAC5D,MAAM,YAAY,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC;IACrF,MAAM,CAAC,iBAAiB,CACtB,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CACpF,CAAC;IACF,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,IAAI,MAAqB,CAAC;IAE1B,UAAU,CAAC,GAAG,EAAE;QACd,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAC7B,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,aAAa,EAAE,CAAC;QACnB,EAAE,CAAC,eAAe,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;QAC/E,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;QAExC,gDAAgD;QAChD,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,MAAM,CAAC,iBAAiB,CACtB,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,CAC/F,CAAC;QAEF,gCAAgC;QAChC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAExB,oDAAoD;QACpD,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;YAChD,IAAI,CAAC;gBAAC,OAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,CAAyB,CAAC,MAAM,KAAK,SAAS,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,OAAO,KAAK,CAAC;YAAC,CAAC;QACrG,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QACjC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAW,CAAmB,CAAC;QAE7D,MAAM,YAAY,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC;QACrF,MAAM,CAAC,iBAAiB,CACtB,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CACpF,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QAChE,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAErC,0BAA0B;QAC1B,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAoB,aAAa,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QACjF,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAmC,CAAC;QACtE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAE3C,6BAA6B;QAC7B,MAAM,CAAC,iBAAiB,CACtB,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,CAClF,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC3D,sDAAsD;QACtD,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7D,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAErC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAU,aAAa,CAAC,CAAC;QAC1D,gFAAgF;QAChF,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAE5B,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,6CAA6C,CAAC,CAAC;IAC1F,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACtE,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAErC,0CAA0C;QAC1C,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAU,gBAAgB,CAAC,CAAC;QAC7D,sCAAsC;QACtC,MAAM,CAAC,KAAK,EAAE,CAAC;QAEf,sFAAsF;QACtF,oGAAoG;QACpG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,KAAK,IAAI,EAAE;QACxE,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,4CAA4C;QAC/E,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAErC,MAAM,eAAe,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC;QACnD,mCAAmC;QACnC,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAE7C,4CAA4C;QAC5C,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAE7B,yEAAyE;QACzE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yEAAyE,EAAE,KAAK,IAAI,EAAE;QACvF,MAAM,SAAS,GAAoB,EAAE,CAAC;QACtC,IAAI,WAAW,GAAG,CAAC,CAAC;QAEpB,MAAM,GAAG,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAEzB,8DAA8D;QAC9D,MAAM,SAAS,GAAG,UAAU,IAAY,EAAE,GAAG,KAAgB;YAC3D,OAAO,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAClC,CAAC,CAAC;QAEF,MAAM,eAAe,GAAa,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC;YAC/B,GAAG,EAAE,wBAAwB;YAC7B,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;YAC/C,8DAA8D;YAC9D,aAAa,EAAE,SAAgB;YAC/B,aAAa,EAAE,IAAI;YACnB,gBAAgB,EAAE,OAAO;YACzB,gBAAgB,EAAE,OAAO;YACzB,oBAAoB,EAAE,CAAC,KAAK,EAAE,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClE,CAAC,CAAC;QAEH,wBAAwB;QACxB,MAAM,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAElC,0EAA0E;QAC1E,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAClC,MAAM,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAEvC,gDAAgD;QAChD,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAC5B,4EAA4E;QAC5E,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAExB,uDAAuD;QACvD,GAAG,CAAC,cAAc,EAAE,CAAC;QACrB,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QAC/G,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAExB,MAAM,WAAW,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;YAC9C,IAAI,CAAC;gBAAC,OAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,CAAyB,CAAC,MAAM,KAAK,SAAS,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,OAAO,KAAK,CAAC;YAAC,CAAC;QACrG,CAAC,CAAC,CAAC;QACH,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAmB,CAAC;YACvD,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;YAC7G,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC;QAED,sEAAsE;QACtE,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAExC,wDAAwD;QACxD,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;QACzD,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/gateway/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
 export * from './protocol.js';
 export * from './connection.js';
+export * from './client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/gateway/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/gateway/index.js

@@ -1,4 +1,5 @@
 export * from './types.js';
 export * from './protocol.js';
 export * from './connection.js';
+export * from './client.js';
 //# sourceMappingURL=index.js.map

package/dist/gateway/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/node/index.d.ts

@@ -0,0 +1,20 @@
+import { GatewayClient, type GatewayClientOptions } from '../gateway/client.js';
+export interface NodeGatewayClientOptions extends Omit<GatewayClientOptions, 'WebSocketImpl' | 'wsConstructorArgs'> {
+    /** Additional HTTP headers to send during the WebSocket upgrade (Node ws feature). */
+    headers?: Record<string, string>;
+    /** Max message payload in bytes. Default: 25 MiB. */
+    maxPayload?: number;
+}
+/**
+ * Create a GatewayClient instance backed by the `ws` npm package.
+ *
+ * Use this in Node.js environments (paperclip adapter, scripts).
+ * Hub and site use `new GatewayClient(opts)` directly (browser globalThis.WebSocket).
+ */
+export declare function createNodeGatewayClient(options: NodeGatewayClientOptions): GatewayClient;
+export { GatewayClient, PROTOCOL_VERSION } from '../gateway/client.js';
+export type { GatewayClientOptions } from '../gateway/client.js';
+export * from '../gateway/types.js';
+export * from '../gateway/protocol.js';
+export * from '../utils/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAoB,MAAM,sBAAsB,CAAC;AAElG,MAAM,WAAW,wBACf,SAAQ,IAAI,CAAC,oBAAoB,EAAE,eAAe,GAAG,mBAAmB,CAAC;IACzE,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,aAAa,CAQxF;AAGD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC"}

package/dist/node/index.js

@@ -0,0 +1,28 @@
+// packages/shared/src/node/index.ts
+// Node-runtime entry point for the gateway client.
+// Consumers: paperclip-minion adapter (pnpm, Node 22+).
+// Browser consumers (hub, site) import from '@minion-stack/shared' (main entry) — NOT this file.
+// This file is the ONLY entry point in this package that imports 'ws'.
+import { WebSocket } from 'ws';
+import { GatewayClient } from '../gateway/client.js';
+/**
+ * Create a GatewayClient instance backed by the `ws` npm package.
+ *
+ * Use this in Node.js environments (paperclip adapter, scripts).
+ * Hub and site use `new GatewayClient(opts)` directly (browser globalThis.WebSocket).
+ */
+export function createNodeGatewayClient(options) {
+    const { headers, maxPayload, ...rest } = options;
+    return new GatewayClient({
+        ...rest,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        WebSocketImpl: WebSocket,
+        wsConstructorArgs: [{ headers: headers ?? {}, maxPayload: maxPayload ?? 25 * 1024 * 1024 }],
+    });
+}
+// Re-export shared surface so Node consumers can import everything from one subpath.
+export { GatewayClient, PROTOCOL_VERSION } from '../gateway/client.js';
+export * from '../gateway/types.js';
+export * from '../gateway/protocol.js';
+export * from '../utils/index.js';
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,mDAAmD;AACnD,wDAAwD;AACxD,iGAAiG;AACjG,uEAAuE;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,EAAE,aAAa,EAA+C,MAAM,sBAAsB,CAAC;AAUlG;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAiC;IACvE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACjD,OAAO,IAAI,aAAa,CAAC;QACvB,GAAG,IAAI;QACP,8DAA8D;QAC9D,aAAa,EAAE,SAA2B;QAC1C,iBAAiB,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,UAAU,EAAE,UAAU,IAAI,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;KAC5F,CAAC,CAAC;AACL,CAAC;AAED,qFAAqF;AACrF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEvE,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC"}

package/dist/node/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/node/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../src/node/index.test.ts"],"names":[],"mappings":""}

package/dist/node/index.test.js

@@ -0,0 +1,92 @@
+// packages/shared/src/node/index.test.ts
+// Integration smoke test: spin up a real ws WebSocketServer, connect via createNodeGatewayClient,
+// assert connect() resolves with canned helloOk payload.
+import { describe, it, expect, afterAll } from 'vitest';
+import { WebSocketServer } from 'ws';
+import { createNodeGatewayClient, PROTOCOL_VERSION, GatewayClient } from './index.js';
+let server;
+let port;
+// Spin up a minimal gateway mock server before tests.
+function startMockServer() {
+    return new Promise((resolve) => {
+        server = new WebSocketServer({ port: 0 }, () => {
+            const addr = server.address();
+            port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+            resolve();
+        });
+        server.on('connection', (ws) => {
+            // 1. Send connect.challenge immediately after connection.
+            ws.send(JSON.stringify({
+                type: 'event',
+                event: 'connect.challenge',
+                payload: { nonce: 'server-nonce-123' },
+            }));
+            // 2. Listen for client's 'connect' request and respond with helloOk.
+            ws.on('message', (data) => {
+                let frame;
+                try {
+                    frame = JSON.parse(data.toString());
+                }
+                catch {
+                    return;
+                }
+                if (frame['method'] === 'connect') {
+                    ws.send(JSON.stringify({
+                        type: 'res',
+                        id: frame['id'],
+                        ok: true,
+                        payload: {
+                            type: 'hello-ok',
+                            protocol: 3,
+                            server: { version: '1.0.0', connId: 'smoke-conn-1' },
+                            features: { methods: ['connect'], events: ['connect.challenge'] },
+                            snapshot: { presence: [], health: {}, stateVersion: { presence: 0, health: 0 }, uptimeMs: 0 },
+                            policy: { maxPayload: 1048576, maxBufferedBytes: 1048576, tickIntervalMs: 1000 },
+                        },
+                    }));
+                }
+            });
+        });
+    });
+}
+// Start server once for all tests in this file.
+await startMockServer();
+afterAll(() => {
+    server?.close();
+});
+describe('createNodeGatewayClient (integration smoke)', () => {
+    it('exports createNodeGatewayClient as a function', () => {
+        expect(typeof createNodeGatewayClient).toBe('function');
+    });
+    it('exports GatewayClient class', () => {
+        expect(typeof GatewayClient).toBe('function');
+    });
+    it('re-exports PROTOCOL_VERSION = 3', () => {
+        expect(PROTOCOL_VERSION).toBe(3);
+    });
+    it('connect() resolves with hello-ok payload from a real WebSocketServer', async () => {
+        const client = createNodeGatewayClient({
+            url: `ws://127.0.0.1:${port}`,
+            onChallenge: async (_nonce) => ({
+                token: 'smoke-token',
+                minProtocol: 3,
+                maxProtocol: 3,
+                client: { id: 'smoke-test', mode: 'backend' },
+            }),
+            autoReconnect: false,
+        });
+        const result = await client.connect();
+        expect(result).toMatchObject({ type: 'hello-ok', protocol: 3 });
+        client.close();
+    });
+    it('createNodeGatewayClient injects ws as WebSocketImpl (returns GatewayClient instance)', () => {
+        const client = createNodeGatewayClient({
+            url: `ws://127.0.0.1:${port}`,
+            onChallenge: async (_nonce) => ({}),
+            autoReconnect: false,
+        });
+        expect(client).toBeInstanceOf(GatewayClient);
+        client.close();
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/node/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/node/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minion-stack/shared",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared gateway protocol types and utilities for the Minion platform.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,18 @@
     "./utils": {
       "types": "./dist/utils/index.d.ts",
       "import": "./dist/utils/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
+    }
+  },
+  "peerDependencies": {
+    "ws": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
     }
   },
   "publishConfig": {
@@ -34,10 +46,15 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "tsc"
+    "prepublishOnly": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "devDependencies": {
     "@minion-stack/tsconfig": "workspace:*",
-    "typescript": "^5.7.0"
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.9",
+    "ws": "^8.19.0"
   }
 }