doover-js 0.2.0-alpha.0 → 0.2.0

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,15 +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;
@@ -34,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[]>;

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

@@ -11,6 +11,13 @@ const errors_1 = require("../http/errors");
 const rest_client_1 = require("../http/rest-client");
 const snowflake_1 = require("../utils/snowflake");
 const path_parsing_1 = require("./path-parsing");
+function isRpcMessageData(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        "status" in data &&
+        "method" in data &&
+        "request" in data);
+}
 class DooverDataProvider {
     constructor(config, auth) {
         this.config = config;
@@ -27,6 +34,11 @@ class DooverDataProvider {
             const identifier = this.toIdentifier(message.channel.agent_id, message.channel.name);
             this.subscriptions.get(key)?.forEach((entry) => entry.messageCallback(identifier, message));
         });
+        this.gateway.on("messageUpdate", (message) => {
+            const key = this.channelKey(message.channel.agent_id, message.channel.name);
+            const identifier = this.toIdentifier(message.channel.agent_id, message.channel.name);
+            this.subscriptions.get(key)?.forEach((entry) => entry.messageUpdateCallback?.(identifier, message));
+        });
         this.gateway.on("channelSync", (event) => {
             const key = this.channelKey(event.channel.agent_id, event.channel.name);
             const identifier = this.toIdentifier(event.channel.agent_id, event.channel.name);
@@ -78,11 +90,15 @@ class DooverDataProvider {
         }
         return this.channelsApi.getChannel(identifier.agentId, identifier.channelName);
     }
-    async subscribeToChannel(identifier, callback, aggregateCallback) {
+    async subscribeToChannel(identifier, callback, aggregateCallback, messageUpdateCallback) {
         const validated = this.requireChannel(identifier);
         const key = this.channelKey(validated.agentId, validated.channelName);
         const entries = this.subscriptions.get(key) ?? [];
-        entries.push({ messageCallback: callback, aggregateCallback });
+        entries.push({
+            messageCallback: callback,
+            aggregateCallback,
+            messageUpdateCallback,
+        });
         this.subscriptions.set(key, entries);
         await this.gateway.connect();
         this.gateway.subscribe({
@@ -121,13 +137,27 @@ class DooverDataProvider {
         }
         return this.aggregatesApi.getAggregate(identifier.agentId, identifier.channelName);
     }
-    async getMessages(identifier, beforeId) {
+    /**
+     * 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.
+     */
+    async getMessages(identifier, optionsOrBefore) {
         if (!identifier.agentId || !identifier.channelName) {
             return undefined;
         }
+        const options = typeof optionsOrBefore === "string"
+            ? { before: optionsOrBefore }
+            : (optionsOrBefore ?? {});
         const messages = await this.messagesApi.listMessages(identifier.agentId, identifier.channelName, {
-            before: beforeId ?? (0, snowflake_1.generateSnowflakeIdAtTime)(new Date()),
-            limit: 10,
+            before: options.before ?? (0, snowflake_1.generateSnowflakeIdAtTime)(new Date()),
+            limit: options.limit ?? 10,
+            ...(options.after !== undefined ? { after: options.after } : {}),
+            ...(options.field_name !== undefined ? { field_name: options.field_name } : {}),
         });
         return messages.reverse();
     }
@@ -141,6 +171,63 @@ class DooverDataProvider {
             data: message,
         });
     }
+    /**
+     * 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(identifier, rpcRequest, options) {
+        return new Promise((resolve, reject) => {
+            let rpcMessageId;
+            let settled = false;
+            const onUpdate = (_identifier, message) => {
+                if (settled)
+                    return;
+                if (rpcMessageId === undefined || message.id !== rpcMessageId)
+                    return;
+                if (!isRpcMessageData(message.data))
+                    return;
+                const rpcMessage = message.data;
+                options?.onStatus?.(rpcMessage.status);
+                if (rpcMessage.status.code === "success") {
+                    settled = true;
+                    void this.unsubscribeFromChannel(identifier, noopMessageCallback);
+                    resolve(rpcMessage.response);
+                }
+                else if (rpcMessage.status.code === "error") {
+                    settled = true;
+                    void this.unsubscribeFromChannel(identifier, noopMessageCallback);
+                    reject(rpcMessage.status.message);
+                }
+            };
+            // noopMessageCallback is used as the identity handle for this
+            // subscription — subscribe/unsubscribe pair matches by reference.
+            const noopMessageCallback = () => { };
+            const noopAggregateCallback = () => { };
+            this.subscribeToChannel(identifier, noopMessageCallback, noopAggregateCallback, onUpdate)
+                .then(() => this.sendMessage(identifier, { type: "rpc", ...rpcRequest }))
+                .then((message) => {
+                rpcMessageId = message.id;
+            })
+                .catch((error) => {
+                if (settled)
+                    return;
+                settled = true;
+                void this.unsubscribeFromChannel(identifier, noopMessageCallback);
+                reject(error);
+            });
+        });
+    }
     updateAggregate(identifier, message) {
         const validated = this.requireChannel(identifier);
         return this.aggregatesApi.patchAggregate(validated.agentId, validated.channelName, message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.0",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,10 @@
     "./node": {
       "types": "./dist/node/index.d.ts",
       "default": "./dist/node/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
     }
   },
   "repository": {
@@ -29,21 +33,43 @@
     "build": "tsc",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build",
-    "test": "mocha --require tsx/cjs \"src/test/**/*.test.ts\""
+    "test:node": "mocha --exit --require tsx/cjs \"src/test/**/*.test.ts\"",
+    "test:react": "mocha --exit --require global-jsdom/register --require tsx/cjs \"src/test/**/*.test.tsx\"",
+    "test": "npm run test:node && npm run test:react"
   },
   "keywords": [
     "doover"
   ],
   "license": "Apache-2.0",
+  "peerDependencies": {
+    "@tanstack/react-query": "^5",
+    "react": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@tanstack/react-query": "^5.90.2",
+    "@testing-library/react": "^16.1.0",
     "@types/chai": "^5.2.2",
     "@types/chai-as-promised": "^7.1.8",
     "@types/mocha": "^10.0.10",
     "@types/node": "^25.6.0",
+    "@types/react": "^18.3.17",
+    "@types/react-dom": "^18.3.5",
     "@types/sinon": "^17.0.4",
     "chai": "^5.2.1",
     "chai-as-promised": "^8.0.2",
+    "global-jsdom": "^25.0.0",
+    "jsdom": "^25.0.1",
     "mocha": "^11.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "sinon": "^21.0.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3"