doover-js 0.1.2 → 0.2.0

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 {};

package/dist/test/singleton.test.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const sinon_1 = __importDefault(require("sinon"));
+const doover_client_1 = require("../client/doover-client");
+const singleton_1 = require("../client/singleton");
+const helpers_1 = require("./helpers");
+(0, mocha_1.describe)("getDooverClient", () => {
+    (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, singleton_1.resetDooverClient)();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+        (0, singleton_1.resetDooverClient)();
+    });
+    const config = {
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    };
+    (0, mocha_1.it)("creates a client on first call and returns the same instance after", () => {
+        const a = (0, singleton_1.getDooverClient)(config);
+        const b = (0, singleton_1.getDooverClient)(config);
+        (0, chai_1.expect)(a).to.be.instanceOf(doover_client_1.DooverClient);
+        (0, chai_1.expect)(a).to.equal(b);
+    });
+    (0, mocha_1.it)("peekDooverClient returns null until the first call, then the instance", () => {
+        (0, chai_1.expect)((0, singleton_1.peekDooverClient)()).to.equal(null);
+        const a = (0, singleton_1.getDooverClient)(config);
+        (0, chai_1.expect)((0, singleton_1.peekDooverClient)()).to.equal(a);
+    });
+    (0, mocha_1.it)("resetDooverClient clears the singleton so the next call creates a new one", () => {
+        const a = (0, singleton_1.getDooverClient)(config);
+        (0, singleton_1.resetDooverClient)();
+        const b = (0, singleton_1.getDooverClient)(config);
+        (0, chai_1.expect)(a).to.not.equal(b);
+    });
+    (0, mocha_1.it)("warns and reuses the existing client when a later caller differs in config", () => {
+        const warn = sinon_1.default.stub(console, "warn");
+        const a = (0, singleton_1.getDooverClient)(config);
+        const b = (0, singleton_1.getDooverClient)({
+            ...config,
+            dataRestUrl: "https://other.example.com",
+        });
+        (0, chai_1.expect)(b).to.equal(a);
+        (0, chai_1.expect)(warn.calledOnce).to.equal(true);
+        (0, chai_1.expect)(warn.getCall(0).args[0]).to.match(/differs from the already-initialised singleton/);
+    });
+});

package/dist/types/common.d.ts

@@ -128,3 +128,43 @@ export interface DataSeries {
     count: number;
     results: DataSeriesResult[];
 }
+/**
+ * Lifecycle status for an RPC. `pending` carries arbitrary intermediate
+ * payloads (progress updates) emitted by the server while the request is
+ * in flight.
+ */
+export type RpcStatus<TPending = undefined> = {
+    code: "awaiting_confirmation";
+} | {
+    code: "sent";
+} | {
+    code: "acknowledged";
+    message: {
+        timestamp: number;
+    };
+} | {
+    code: "error";
+    message: string | object;
+} | {
+    code: "deferred";
+    message: {
+        until: number;
+        at: number;
+    };
+} | {
+    code: "pending";
+    message: TPending;
+} | {
+    code: "success";
+};
+/** Shape a consumer posts to initiate an RPC. */
+export interface RpcRequest<TRequest = object> {
+    app_key?: string;
+    method: string;
+    request: TRequest;
+}
+/** Shape of the message the server maintains as the RPC progresses. */
+export interface RpcMessageData<TRequest = object, TResponse = object, TPending = undefined> extends RpcRequest<TRequest> {
+    status: RpcStatus<TPending>;
+    response: TResponse;
+}

package/dist/viewer/doover-data-provider.d.ts

@@ -2,14 +2,16 @@ import { AgentsApi } from "../apis/agents-api";
 import { AggregatesApi } from "../apis/aggregates-api";
 import { ChannelsApi } from "../apis/channels-api";
 import { ConnectionsApi } from "../apis/connections-api";
-import { MessagesApi } from "../apis/messages-api";
+import { MessagesApi, type ListMessagesParams } from "../apis/messages-api";
+import type { DooverAuth } from "../auth/doover-auth";
 import { GatewayClient } from "../gateway/gateway-client";
 import { RestClient, type DooverClientConfig } from "../http/rest-client";
-import type { Aggregate, Channel, ConnectionDetails, MessageStructure } from "../types/common";
+import type { Aggregate, Channel, ConnectionDetails, MessageStructure, RpcRequest, RpcStatus } from "../types/common";
 import type { Agent, AgentsResponse, ChannelIdentifier, ChannelsDataProvider, SubscriptionDetails, User } from "../types/viewer";
 interface SubscriptionEntry {
     messageCallback: (identifier: ChannelIdentifier, message: MessageStructure) => void;
     aggregateCallback: (identifier: ChannelIdentifier, aggregate: Aggregate) => void;
+    messageUpdateCallback?: (identifier: ChannelIdentifier, message: MessageStructure) => void;
 }
 export declare class DooverDataProvider implements ChannelsDataProvider<ChannelIdentifier> {
     private readonly config;
@@ -21,7 +23,7 @@ export declare class DooverDataProvider implements ChannelsDataProvider<ChannelI
     readonly aggregatesApi: AggregatesApi;
     readonly connectionsApi: ConnectionsApi;
     private readonly subscriptions;
-    constructor(config: DooverClientConfig);
+    constructor(config: DooverClientConfig, auth?: DooverAuth);
     getMe(): Promise<User>;
     getAgents(): Promise<AgentsResponse>;
     getChannels(identifier: ChannelIdentifier, options?: {
@@ -33,12 +35,39 @@ export declare class DooverDataProvider implements ChannelsDataProvider<ChannelI
     archiveChannel(identifier: ChannelIdentifier): Promise<unknown>;
     unarchiveChannel(identifier: ChannelIdentifier): Promise<unknown>;
     getChannel(identifier: ChannelIdentifier): Promise<Channel | undefined>;
-    subscribeToChannel(identifier: ChannelIdentifier, callback: SubscriptionEntry["messageCallback"], aggregateCallback: SubscriptionEntry["aggregateCallback"]): Promise<void>;
+    subscribeToChannel(identifier: ChannelIdentifier, callback: SubscriptionEntry["messageCallback"], aggregateCallback: SubscriptionEntry["aggregateCallback"], messageUpdateCallback?: SubscriptionEntry["messageUpdateCallback"]): Promise<void>;
     unsubscribeFromChannel(identifier: ChannelIdentifier, callback: SubscriptionEntry["messageCallback"]): Promise<void>;
     getAggregate(identifier: ChannelIdentifier): Promise<Aggregate | undefined>;
-    getMessages(identifier: ChannelIdentifier, beforeId?: string): Promise<MessageStructure[] | undefined>;
+    /**
+     * Fetch a page of messages for a channel.
+     *
+     * Accepts either a cursor string (legacy — shorthand for `{ before }`)
+     * or a `ListMessagesParams` options object.
+     *
+     * Default limit is 10 for backwards compatibility; pass `limit` explicitly
+     * for larger pages.
+     */
+    getMessages(identifier: ChannelIdentifier, optionsOrBefore?: string | ListMessagesParams): Promise<MessageStructure[] | undefined>;
     deleteMessage(identifier: ChannelIdentifier, messageId: string): Promise<unknown>;
     sendMessage(identifier: ChannelIdentifier, message: object): Promise<MessageStructure>;
+    /**
+     * Send a message-based RPC to a channel and await a settled response.
+     *
+     * Wire protocol: POST a message with `{ type: "rpc", ...rpcRequest }`; the
+     * server echoes progress via `MessageUpdate` events keyed by the message id,
+     * carrying a `status` envelope. Resolves on `success` with the `response`
+     * payload, rejects on `error` with the status message.
+     *
+     * For low-latency ephemeral commands (camera PTZ etc.), use
+     * `gateway.sendOneShotMessage` directly instead — that path is not persisted
+     * to the database.
+     *
+     * `onStatus` fires on every intermediate status (`sent`, `acknowledged`,
+     * `deferred`, `pending`) and once more on terminal states.
+     */
+    sendRPC<TRequest = object, TResponse = object, TPending = undefined>(identifier: ChannelIdentifier, rpcRequest: RpcRequest<TRequest>, options?: {
+        onStatus?: (status: RpcStatus<TPending>) => void;
+    }): Promise<TResponse>;
     updateAggregate(identifier: ChannelIdentifier, message: object): Promise<Aggregate>;
     putAggregate(identifier: ChannelIdentifier, message: object): Promise<Aggregate>;
     getChannelSubscriptions(identifier: ChannelIdentifier): Promise<SubscriptionDetails[]>;