doover-js 0.2.0-alpha.0 → 0.3.0

package/dist/test/doover-data-provider.test.js

@@ -104,6 +104,23 @@ const helpers_1 = require("./helpers");
         (0, chai_1.expect)(messages?.map((message) => message.id)).to.deep.equal([oldId, newId]);
         (0, chai_1.expect)(fetchMock.getCall(0).args[0]).to.equal("https://api.example.com/agents/a1/channels/c1/messages?before=cursor&limit=10");
     });
+    (0, mocha_1.it)("forwards listMessages options (limit, after, field_name)", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)([]));
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        await provider.getMessages({ agentId: "a1", channelName: "c1" }, { before: "b1", after: "a1", limit: 50, field_name: ["x", "y"] });
+        const url = fetchMock.getCall(0).args[0];
+        (0, chai_1.expect)(url).to.include("before=b1");
+        (0, chai_1.expect)(url).to.include("after=a1");
+        (0, chai_1.expect)(url).to.include("limit=50");
+        (0, chai_1.expect)(url).to.include("field_name=x");
+        (0, chai_1.expect)(url).to.include("field_name=y");
+    });
     (0, mocha_1.it)("prefers channel aggregate data and falls back to the aggregate endpoint", async () => {
         const fetchMock = (0, helpers_1.createFetchMock)((url) => {
             if (url.endsWith("/channels/c1")) {
@@ -227,4 +244,142 @@ const helpers_1 = require("./helpers");
             aggregatePath: "path/to/value",
         });
     });
+    (0, mocha_1.it)("sendRPC posts an rpc message, correlates the response by id, and resolves on success", async () => {
+        const rpcId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00.000Z"));
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.endsWith("/messages")) {
+                return (0, helpers_1.createJsonResponse)({
+                    id: rpcId,
+                    author_id: "u1",
+                    channel: { agent_id: "a1", name: "c1" },
+                    data: {
+                        type: "rpc",
+                        method: "ping",
+                        request: {},
+                        status: { code: "sent" },
+                        response: {},
+                    },
+                    attachments: [],
+                });
+            }
+            return (0, helpers_1.createJsonResponse)({});
+        });
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        const statuses = [];
+        const promise = provider.sendRPC({ agentId: "a1", channelName: "c1" }, { method: "ping", request: {} }, { onStatus: (status) => statuses.push(status.code) });
+        // Let subscribe + POST resolve.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        const ws = helpers_1.MockWebSocket.instances[0];
+        ws.open();
+        ws.receive({ op: 0, t: "Hello", d: {} });
+        ws.receive({
+            op: 0,
+            t: "Ready",
+            d: { session_id: "s1", session_token: "t1", subscriptions: [] },
+        });
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        // Progress updates.
+        ws.receive({
+            op: 0,
+            t: "MessageUpdate",
+            d: {
+                id: rpcId,
+                author_id: "u1",
+                channel: { agent_id: "a1", name: "c1" },
+                data: {
+                    type: "rpc",
+                    method: "ping",
+                    request: {},
+                    status: { code: "acknowledged", message: { timestamp: 1 } },
+                    response: {},
+                },
+                attachments: [],
+                request_data: {},
+            },
+        });
+        ws.receive({
+            op: 0,
+            t: "MessageUpdate",
+            d: {
+                id: rpcId,
+                author_id: "u1",
+                channel: { agent_id: "a1", name: "c1" },
+                data: {
+                    type: "rpc",
+                    method: "ping",
+                    request: {},
+                    status: { code: "success" },
+                    response: { pong: true },
+                },
+                attachments: [],
+                request_data: {},
+            },
+        });
+        await (0, chai_1.expect)(promise).to.eventually.deep.equal({ pong: true });
+        (0, chai_1.expect)(statuses).to.deep.equal(["acknowledged", "success"]);
+    });
+    (0, mocha_1.it)("sendRPC rejects with the status message on error", async () => {
+        const rpcId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00.000Z"));
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.endsWith("/messages")) {
+                return (0, helpers_1.createJsonResponse)({
+                    id: rpcId,
+                    author_id: "u1",
+                    channel: { agent_id: "a1", name: "c1" },
+                    data: {
+                        type: "rpc",
+                        method: "ping",
+                        request: {},
+                        status: { code: "sent" },
+                        response: {},
+                    },
+                    attachments: [],
+                });
+            }
+            return (0, helpers_1.createJsonResponse)({});
+        });
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        const promise = provider.sendRPC({ agentId: "a1", channelName: "c1" }, { method: "ping", request: {} });
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        const ws = helpers_1.MockWebSocket.instances[0];
+        ws.open();
+        ws.receive({ op: 0, t: "Hello", d: {} });
+        ws.receive({
+            op: 0,
+            t: "Ready",
+            d: { session_id: "s1", session_token: "t1", subscriptions: [] },
+        });
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        ws.receive({
+            op: 0,
+            t: "MessageUpdate",
+            d: {
+                id: rpcId,
+                author_id: "u1",
+                channel: { agent_id: "a1", name: "c1" },
+                data: {
+                    type: "rpc",
+                    method: "ping",
+                    request: {},
+                    status: { code: "error", message: "boom" },
+                    response: {},
+                },
+                attachments: [],
+                request_data: {},
+            },
+        });
+        await (0, chai_1.expect)(promise).to.eventually.be.rejectedWith("boom");
+    });
 });

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

@@ -203,16 +203,14 @@ const helpers_1 = require("./helpers");
         (0, chai_1.expect)(unsubscribed.calledOnce).to.equal(true);
         (0, chai_1.expect)(wssError.calledWith({ message: "boom" })).to.equal(true);
     });
-    (0, mocha_1.it)("sends heartbeats, measures latency, and handles session cancellation", () => {
+    (0, mocha_1.it)("handles session cancellation (op 3)", () => {
         const client = new gateway_client_1.GatewayClient({
             dataRestUrl: "https://api.example.com",
             controlApiUrl: "https://control.example.com",
             dataWssUrl: "wss://ws.example.com",
             webSocketImpl: helpers_1.MockWebSocket,
         });
-        const ack = sinon_1.default.spy();
         const cancelled = sinon_1.default.spy();
-        client.on("heartbeatAck", ack);
         client.on("sessionCancelled", cancelled);
         client.connect();
         const ws = helpers_1.MockWebSocket.instances[0];
@@ -223,13 +221,129 @@ const helpers_1 = require("./helpers");
             t: "Ready",
             d: { session_id: "s1", session_token: "token", subscriptions: [] },
         });
-        sinon_1.default.clock.tick(20000);
-        (0, chai_1.expect)(JSON.parse(ws.sent[ws.sent.length - 1])).to.deep.equal({ op: 1, d: {} });
-        sinon_1.default.clock.tick(10);
-        ws.receive({ op: 2, d: {} });
-        (0, chai_1.expect)(ack.calledWith(10)).to.equal(true);
         ws.receive({ op: 3, d: {} });
         (0, chai_1.expect)(cancelled.calledOnce).to.equal(true);
         (0, chai_1.expect)(client.getSession()).to.equal(null);
     });
+    (0, mocha_1.it)("reconnects with exponential backoff + jitter on unexpected close", () => {
+        // Make jitter deterministic: Math.random() → 1 means "wait the full backoff window".
+        const randomStub = sinon_1.default.stub(Math, "random").returns(1);
+        const client = new gateway_client_1.GatewayClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        client.connect();
+        helpers_1.MockWebSocket.instances[0].open();
+        helpers_1.MockWebSocket.instances[0].close(1006, "transport closed");
+        // 1st attempt: ~1s window
+        sinon_1.default.clock.tick(999);
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(1);
+        sinon_1.default.clock.tick(1);
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(2);
+        helpers_1.MockWebSocket.instances[1].open();
+        helpers_1.MockWebSocket.instances[1].close(1006, "transport closed");
+        // 2nd attempt: ~2s window
+        sinon_1.default.clock.tick(1999);
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(2);
+        sinon_1.default.clock.tick(1);
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(3);
+        // Successful Ready should reset the attempt counter.
+        helpers_1.MockWebSocket.instances[2].open();
+        helpers_1.MockWebSocket.instances[2].receive({ op: 0, t: "Hello", d: {} });
+        helpers_1.MockWebSocket.instances[2].receive({
+            op: 0,
+            t: "Ready",
+            d: { session_id: "s1", session_token: "token", subscriptions: [] },
+        });
+        helpers_1.MockWebSocket.instances[2].close(1006, "transport closed");
+        sinon_1.default.clock.tick(999);
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(3);
+        sinon_1.default.clock.tick(1);
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(4);
+        randomStub.restore();
+    });
+    (0, mocha_1.it)("reconnects immediately on visibilitychange → visible", () => {
+        const listeners = new Map();
+        const fakeDocument = {
+            visibilityState: "hidden",
+            addEventListener: (event, handler) => {
+                listeners.set(event, handler);
+            },
+            removeEventListener: (event) => {
+                listeners.delete(event);
+            },
+        };
+        Object.defineProperty(globalThis, "document", {
+            value: fakeDocument,
+            configurable: true,
+            writable: true,
+        });
+        sinon_1.default.stub(Math, "random").returns(1);
+        const client = new gateway_client_1.GatewayClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        client.connect();
+        helpers_1.MockWebSocket.instances[0].open();
+        helpers_1.MockWebSocket.instances[0].close(1006, "transport closed");
+        // Pending backoff would wait up to 1s.
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(1);
+        // Tab returns to visible — bypass backoff, reconnect now.
+        fakeDocument.visibilityState = "visible";
+        listeners.get("visibilitychange")?.(new Event("visibilitychange"));
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(2);
+        // @ts-expect-error — cleanup test global
+        delete globalThis.document;
+    });
+    (0, mocha_1.it)("skips lifecycle listeners when disableBrowserLifecycleHooks is true", () => {
+        const addSpy = sinon_1.default.spy();
+        const fakeDocument = {
+            visibilityState: "visible",
+            addEventListener: addSpy,
+            removeEventListener: sinon_1.default.spy(),
+        };
+        Object.defineProperty(globalThis, "document", {
+            value: fakeDocument,
+            configurable: true,
+            writable: true,
+        });
+        new gateway_client_1.GatewayClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            webSocketImpl: helpers_1.MockWebSocket,
+            disableBrowserLifecycleHooks: true,
+        });
+        (0, chai_1.expect)(addSpy.called).to.equal(false);
+        // @ts-expect-error — cleanup test global
+        delete globalThis.document;
+    });
+    (0, mocha_1.it)("caps backoff at 30s and does not reconnect after explicit disconnect", () => {
+        const randomStub = sinon_1.default.stub(Math, "random").returns(1);
+        const client = new gateway_client_1.GatewayClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        client.connect();
+        // Force many failed attempts to push backoff past the cap.
+        for (let i = 0; i < 10; i += 1) {
+            const ws = helpers_1.MockWebSocket.instances[i];
+            ws.open();
+            ws.close(1006, "transport closed");
+            sinon_1.default.clock.tick(30000);
+        }
+        // After 10 attempts we should have 11 sockets, and the delay never exceeds 30s.
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(11);
+        // Explicit disconnect must not schedule a further reconnect.
+        client.disconnect();
+        sinon_1.default.clock.tick(60000);
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(11);
+        randomStub.restore();
+    });
 });

package/dist/test/react.test.d.ts

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

package/dist/test/react.test.js

@@ -0,0 +1,353 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const sinon_1 = __importDefault(require("sinon"));
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const helpers_1 = require("./helpers");
+const snowflake_1 = require("../utils/snowflake");
+function makeClient() {
+    const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+        if (url.endsWith("/wss_connections")) {
+            return (0, helpers_1.createJsonResponse)([{ address: "x", agent_id: "a1" }]);
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, fetchMock };
+}
+function wrapper(client) {
+    const queryClient = new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+(0, mocha_1.describe)("react bindings", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        helpers_1.MockWebSocket.reset();
+        Object.defineProperty(globalThis, "WebSocket", {
+            value: helpers_1.MockWebSocket,
+            configurable: true,
+            writable: true,
+        });
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("useDooverClient returns the injected client", () => {
+        const { client } = makeClient();
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useDooverClient)(), {
+            wrapper: wrapper(client),
+        });
+        (0, chai_1.expect)(result.current).to.equal(client);
+    });
+    (0, mocha_1.it)("useDooverClient throws outside of a provider", () => {
+        // Suppress React's expected error-boundary log for the unmounted throw.
+        sinon_1.default.stub(console, "error");
+        (0, chai_1.expect)(() => (0, react_1.renderHook)(() => (0, react_2.useDooverClient)())).to.throw(/DooverProvider/);
+    });
+    (0, mocha_1.it)("useConnectionState reports connecting initially and flips to open on Ready", async () => {
+        const { client } = makeClient();
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useConnectionState)(), {
+            wrapper: wrapper(client),
+        });
+        (0, chai_1.expect)(result.current.status).to.equal("connecting");
+        (0, chai_1.expect)(result.current.lastOpenedAt).to.equal(null);
+        // Drive the gateway through a real connect.
+        await (0, react_1.act)(async () => {
+            await client.gateway.connect();
+        });
+        const ws = helpers_1.MockWebSocket.instances[0];
+        (0, react_1.act)(() => {
+            ws.open();
+            ws.receive({ op: 0, t: "Hello", d: {} });
+            ws.receive({
+                op: 0,
+                t: "Ready",
+                d: { session_id: "s1", session_token: "t1", subscriptions: [] },
+            });
+        });
+        await (0, react_1.waitFor)(() => {
+            (0, chai_1.expect)(result.current.status).to.equal("open");
+            (0, chai_1.expect)(result.current.lastOpenedAt).to.be.a("number");
+        });
+    });
+    (0, mocha_1.it)("useAgentConnections fetches via ConnectionsApi", async () => {
+        const { client, fetchMock } = makeClient();
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useAgentConnections)("a1"), {
+            wrapper: wrapper(client),
+        });
+        await (0, react_1.waitFor)(() => {
+            (0, chai_1.expect)(result.current.isSuccess).to.equal(true);
+        });
+        (0, chai_1.expect)(result.current.data).to.deep.equal([{ address: "x", agent_id: "a1" }]);
+        (0, chai_1.expect)(fetchMock.getCall(0).args[0]).to.equal("https://api.example.com/agents/a1/wss_connections");
+    });
+    (0, mocha_1.it)("useAgentConnections stays disabled when agentId is undefined", () => {
+        const { client, fetchMock } = makeClient();
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useAgentConnections)(undefined), {
+            wrapper: wrapper(client),
+        });
+        (0, chai_1.expect)(result.current.fetchStatus).to.equal("idle");
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(0);
+    });
+    (0, mocha_1.it)("useAgentChannel fetches the aggregate and patches cache on gateway events", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.endsWith("/channels/ui_state")) {
+                return (0, helpers_1.createJsonResponse)({
+                    name: "ui_state",
+                    owner_id: "a1",
+                    is_private: false,
+                    aggregate: { data: { x: 1 }, attachments: [] },
+                });
+            }
+            return (0, helpers_1.createJsonResponse)({});
+        });
+        const client = new doover_client_1.DooverClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+            disableBrowserLifecycleHooks: true,
+        });
+        const Wrapper = wrapper(client);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useAgentChannel)("a1", "ui_state"), {
+            wrapper: Wrapper,
+        });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.isSuccess).to.equal(true));
+        (0, chai_1.expect)(result.current.data?.data).to.deep.equal({ x: 1 });
+        // Drive a live aggregate update.
+        await (0, react_1.act)(async () => {
+            const ws = helpers_1.MockWebSocket.instances[0];
+            ws.open();
+            ws.receive({ op: 0, t: "Hello", d: {} });
+            ws.receive({
+                op: 0,
+                t: "Ready",
+                d: { session_id: "s1", session_token: "t1", subscriptions: [] },
+            });
+            ws.receive({
+                op: 0,
+                t: "AggregateUpdate",
+                d: {
+                    author_id: "u1",
+                    channel: { agent_id: "a1", name: "ui_state" },
+                    aggregate: { data: { x: 2 }, attachments: [] },
+                    request_data: {},
+                    organisation_id: "org-1",
+                },
+            });
+        });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.data?.data).to.deep.equal({ x: 2 }));
+    });
+    (0, mocha_1.it)("useSendMessage posts via MessagesApi", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.endsWith("/messages")) {
+                return (0, helpers_1.createJsonResponse)({
+                    id: (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00.000Z")),
+                    author_id: "u1",
+                    channel: { agent_id: "a1", name: "notes" },
+                    data: { text: "hi" },
+                    attachments: [],
+                });
+            }
+            return (0, helpers_1.createJsonResponse)({});
+        });
+        const client = new doover_client_1.DooverClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+            disableBrowserLifecycleHooks: true,
+        });
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useSendMessage)({ agentId: "a1", channelName: "notes" }), { wrapper: wrapper(client) });
+        let mutationResult;
+        await (0, react_1.act)(async () => {
+            mutationResult = await result.current.mutateAsync({ text: "hi" });
+        });
+        (0, chai_1.expect)(mutationResult?.data).to.deep.equal({ text: "hi" });
+    });
+    (0, mocha_1.it)("useUpdateAggregate patches and writes back to the channel aggregate cache", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({ data: { y: 2 }, attachments: [] }));
+        const client = new doover_client_1.DooverClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+            disableBrowserLifecycleHooks: true,
+        });
+        const queryClient = new react_query_1.QueryClient({
+            defaultOptions: { queries: { retry: false } },
+        });
+        function Wrapper({ children }) {
+            return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+        }
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useUpdateAggregate)({ agentId: "a1", channelName: "ui_cmds" }), { wrapper: Wrapper });
+        await (0, react_1.act)(async () => {
+            await result.current.mutateAsync({ y: 2 });
+        });
+        const cached = queryClient.getQueryData((0, react_2.channelAggregateQueryKey)("a1", "ui_cmds"));
+        (0, chai_1.expect)(cached).to.deep.equal({ data: { y: 2 }, attachments: [] });
+    });
+    (0, mocha_1.it)("useChannelMessages paginates and prepends on live messageCreate", async () => {
+        const oldId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2025-12-31T23:59:00.000Z"));
+        const newId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:01.000Z"));
+        const liveId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:02.000Z"));
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)([
+            {
+                id: newId,
+                author_id: "u1",
+                channel: { agent_id: "a1", name: "notes" },
+                data: { v: 2 },
+                attachments: [],
+            },
+            {
+                id: oldId,
+                author_id: "u1",
+                channel: { agent_id: "a1", name: "notes" },
+                data: { v: 1 },
+                attachments: [],
+            },
+        ]));
+        const client = new doover_client_1.DooverClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+            disableBrowserLifecycleHooks: true,
+        });
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: "a1", channelName: "notes" }, { limit: 10 }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.isSuccess).to.equal(true));
+        (0, chai_1.expect)(result.current.messages.map((m) => m.id)).to.deep.equal([
+            oldId,
+            newId,
+        ]);
+        // Gateway MessageCreate — should append to the first (newest) page.
+        await (0, react_1.act)(async () => {
+            const ws = helpers_1.MockWebSocket.instances[0];
+            ws.open();
+            ws.receive({ op: 0, t: "Hello", d: {} });
+            ws.receive({
+                op: 0,
+                t: "Ready",
+                d: { session_id: "s1", session_token: "t1", subscriptions: [] },
+            });
+            ws.receive({
+                op: 0,
+                t: "MessageCreate",
+                d: {
+                    id: liveId,
+                    author_id: "u1",
+                    channel: { agent_id: "a1", name: "notes" },
+                    data: { v: 3 },
+                    attachments: [],
+                },
+            });
+        });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages.map((m) => m.id)).to.deep.equal([
+            oldId,
+            newId,
+            liveId,
+        ]));
+    });
+    (0, mocha_1.it)("getSharedQueryClient returns the same QueryClient across callers", () => {
+        (0, react_2.resetSharedQueryClient)();
+        const a = (0, react_2.getSharedQueryClient)();
+        const b = (0, react_2.getSharedQueryClient)();
+        (0, chai_1.expect)(a).to.equal(b);
+        (0, react_2.resetSharedQueryClient)();
+        const c = (0, react_2.getSharedQueryClient)();
+        (0, chai_1.expect)(c).to.not.equal(a);
+        (0, react_2.resetSharedQueryClient)();
+    });
+    (0, mocha_1.it)("useSendRpc tracks status history and resolves via sendRPC", async () => {
+        const rpcId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00.000Z"));
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.endsWith("/messages")) {
+                return (0, helpers_1.createJsonResponse)({
+                    id: rpcId,
+                    author_id: "u1",
+                    channel: { agent_id: "a1", name: "ui_cmds" },
+                    data: {
+                        type: "rpc",
+                        method: "ping",
+                        request: {},
+                        status: { code: "sent" },
+                        response: {},
+                    },
+                    attachments: [],
+                });
+            }
+            return (0, helpers_1.createJsonResponse)({});
+        });
+        const client = new doover_client_1.DooverClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+            disableBrowserLifecycleHooks: true,
+        });
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useSendRpc)({ agentId: "a1", channelName: "ui_cmds" }, { method: "ping" }), { wrapper: wrapper(client) });
+        // Kick off the mutation.
+        const pending = (0, react_1.act)(async () => {
+            const promise = result.current.mutateAsync({ commandId: "c1", request: {} });
+            // Give the mutation a tick to register the command in state before we
+            // drive the gateway, so onStatus updates land against a known command.
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            const ws = helpers_1.MockWebSocket.instances[0];
+            ws.open();
+            ws.receive({ op: 0, t: "Hello", d: {} });
+            ws.receive({
+                op: 0,
+                t: "Ready",
+                d: { session_id: "s1", session_token: "t1", subscriptions: [] },
+            });
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            ws.receive({
+                op: 0,
+                t: "MessageUpdate",
+                d: {
+                    id: rpcId,
+                    author_id: "u1",
+                    channel: { agent_id: "a1", name: "ui_cmds" },
+                    data: {
+                        type: "rpc",
+                        method: "ping",
+                        request: {},
+                        status: { code: "success" },
+                        response: { pong: true },
+                    },
+                    attachments: [],
+                    request_data: {},
+                },
+            });
+            return promise;
+        });
+        const response = await pending;
+        (0, chai_1.expect)(response).to.deep.equal({ pong: true });
+        (0, chai_1.expect)(result.current.getStatus("c1")?.code).to.equal("success");
+        (0, chai_1.expect)(result.current.isPending("c1")).to.equal(false);
+    });
+});
+// Keep `render` imported so tsc doesn't drop it; we use renderHook everywhere.
+void react_1.render;

package/dist/test/singleton.test.d.ts

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