doover-js 0.9.0 → 0.10.0

package/dist/react/messageRangeStore.d.ts

@@ -65,6 +65,12 @@ export declare class ChannelRangeStore {
      * between them, and claiming coverage across it would hide messages forever.
      */
     recordLive(message: MessageStructure): void;
+    /**
+     * Replace a message already held by one or more proven ranges. MessageUpdate
+     * carries the complete server representation, so both data and attachments
+     * supersede the cached create-time copy without changing range coverage.
+     */
+    recordUpdate(message: MessageStructure): void;
     /**
      * Stop trusting the live feed to extend coverage — call when the socket drops.
      * Messages sent while disconnected would leave a hole, so segments go back to

package/dist/react/messageRangeStore.js

@@ -69,6 +69,18 @@ class ChannelRangeStore {
         if (id >= tip.hi)
             tip.hi = id + 1n;
     }
+    /**
+     * Replace a message already held by one or more proven ranges. MessageUpdate
+     * carries the complete server representation, so both data and attachments
+     * supersede the cached create-time copy without changing range coverage.
+     */
+    recordUpdate(message) {
+        for (const segment of this.segments) {
+            const index = segment.messages.findIndex((item) => item.id === message.id);
+            if (index >= 0)
+                segment.messages[index] = message;
+        }
+    }
     /**
      * Stop trusting the live feed to extend coverage — call when the socket drops.
      * Messages sent while disconnected would leave a hole, so segments go back to

package/dist/react/useChannelMessages.d.ts

@@ -75,8 +75,9 @@ export interface UseChannelMessagesResult<TData> extends Omit<UseInfiniteQueryRe
 }
 /**
  * Paginated infinite query over `DooverDataProvider.getMessages`, with live
- * `messageCreate` pushes prepended/appended to the newest page. The "next"
- * page fetches older messages (cursor = oldest-loaded message id).
+ * `messageCreate` pushes are appended to the newest page and `messageUpdate`
+ * pushes replace matching cached messages. The "next" page fetches older
+ * messages (cursor = oldest-loaded message id).
  */
 export declare function useChannelMessages<TData = unknown>(identifier: ChannelIdentifier, options?: UseChannelMessagesOptions): UseChannelMessagesResult<TData>;
 export {};

package/dist/react/useChannelMessages.js

@@ -33,8 +33,9 @@ function channelMessagesQueryKey(agentId, channelName, fields, sources, anchor)
 const DEFAULT_PAGE_LIMIT = 10;
 /**
  * Paginated infinite query over `DooverDataProvider.getMessages`, with live
- * `messageCreate` pushes prepended/appended to the newest page. The "next"
- * page fetches older messages (cursor = oldest-loaded message id).
+ * `messageCreate` pushes are appended to the newest page and `messageUpdate`
+ * pushes replace matching cached messages. The "next" page fetches older
+ * messages (cursor = oldest-loaded message id).
  */
 function useChannelMessages(identifier, options) {
     const client = (0, context_1.useDooverClient)();
@@ -94,7 +95,40 @@ function useChannelMessages(identifier, options) {
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [queryClient, agentId, channelName, fields?.join(","), sources?.join(",")]);
-    (0, useChannelSubscription_1.useChannelSubscription)(liveUpdates ? identifier : undefined, { onMessage });
+    const onMessageUpdate = (0, react_1.useCallback)((message) => {
+        // A filtered stream must not accept an update that does not belong to it.
+        // Newly qualifying messages are left for a refetch because inserting one
+        // into an arbitrary cursor page could invalidate that page's boundaries.
+        if (fields && fields.length > 0) {
+            const data = message.data;
+            if (!data ||
+                typeof data !== "object" ||
+                !fields.some((field) => field in data)) {
+                return;
+            }
+        }
+        if (rangeCacheable)
+            store.recordUpdate(message);
+        queryClient.setQueryData(key, (current) => {
+            if (!current)
+                return current;
+            let changed = false;
+            const typed = message;
+            const pages = current.pages.map((page) => page.map((item) => {
+                if (item.id !== typed.id)
+                    return item;
+                changed = true;
+                return typed;
+            }));
+            return changed ? { ...current, pages } : current;
+        });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName, fields?.join(","), sources?.join(",")]);
+    (0, useChannelSubscription_1.useChannelSubscription)(liveUpdates ? identifier : undefined, {
+        onMessage,
+        onMessageUpdate,
+    });
     const query = (0, react_query_1.useInfiniteQuery)({
         queryKey: key,
         enabled: !!agentId && !!channelName,

package/dist/react/useSendRpc.d.ts

@@ -32,6 +32,13 @@ export interface UseSendRpcOptions {
      * `["doover", "agent", agentId, "channel", channelName, "rpc", method]`.
      */
     mutationKey?: readonly unknown[];
+    /** How long to wait to hear from the device at all. See `SendRpcOptions`. */
+    timeoutMs?: number;
+    /**
+     * How long the command may then stay in flight once the device has answered,
+     * re-armed on every progress report. See `SendRpcOptions`.
+     */
+    pendingTimeoutMs?: number;
 }
 export interface UseSendRpcResult<TRequest, TResponse, TPending> extends Omit<UseMutationResult<TResponse, unknown, SendRpcVariables<TRequest>, void>, "isPending" | "mutate" | "mutateAsync"> {
     /** Most recent status across all commands (by `submittedAt`). */

package/dist/react/useSendRpc.js

@@ -120,6 +120,12 @@ function useSendRpc(identifier, options) {
             }
             return client.rpc.send({ agentId: identifier.agentId, channelName: identifier.channelName }, rpcRequest, {
                 onStatus: (status) => appendStatus(commandId, status),
+                ...(options.timeoutMs !== undefined
+                    ? { timeoutMs: options.timeoutMs }
+                    : {}),
+                ...(options.pendingTimeoutMs !== undefined
+                    ? { pendingTimeoutMs: options.pendingTimeoutMs }
+                    : {}),
             });
         },
         onSuccess: (data, variables) => settleCommand(variables.commandId, {

package/dist/rpc/rpc-dispatcher.d.ts

@@ -5,7 +5,20 @@ import type { RpcRequest, RpcStatus } from "../types/common";
 export interface SendRpcOptions<TPending = undefined> {
     onStatus?: (status: RpcStatus<TPending>) => void;
     signal?: AbortSignal;
+    /**
+     * How long to wait to hear from the device at all. A healthy device answers
+     * within seconds however long the work then takes, so keep this short and
+     * use `pendingTimeoutMs` for the work itself.
+     */
     timeoutMs?: number;
+    /**
+     * How long the command may then stay in flight once the device has answered
+     * it — acknowledged it, or reported progress. Re-armed on every subsequent
+     * status update, so a device that keeps reporting keeps its command alive,
+     * while one that answers and then dies still fails. Without this, a handler
+     * that legitimately runs longer than `timeoutMs` is killed mid-flight.
+     */
+    pendingTimeoutMs?: number;
 }
 interface ChannelIdentifierLike {
     agentId: string;

package/dist/rpc/rpc-dispatcher.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RpcDispatcher = void 0;
 const errors_1 = require("./errors");
+/** Whether the device has answered this command, rather than only received it. */
+function hasDeviceAnswered(status) {
+    return status.code === "acknowledged" || status.code === "pending";
+}
 function isRpcMessageData(data) {
     return (typeof data === "object" &&
         data !== null &&
@@ -45,6 +49,7 @@ class RpcDispatcher {
                     channelKey,
                     channel: channelRef,
                     startedAt,
+                    pendingTimeoutMs: options?.pendingTimeoutMs,
                 };
                 if (options?.signal) {
                     const onAbort = () => this.settle(message.id, "abort", undefined, options.signal?.reason);
@@ -109,6 +114,15 @@ class RpcDispatcher {
         else if (status.code === "error") {
             this.settle(msg.id, "error", undefined, new errors_1.DooverRpcError(status, pending.request));
         }
+        else if (hasDeviceAnswered(status) && pending.pendingTimeoutMs !== undefined) {
+            // The device is alive and working: swap the "no response" deadline for
+            // the pending budget, and re-arm it on every report that follows.
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.timer = setTimeout(() => {
+                this.settle(msg.id, "timeout", undefined, new Error("Device stopped reporting progress"));
+            }, pending.pendingTimeoutMs);
+        }
     }
     settle(messageId, outcome, response, rejection) {
         const pending = this.pending.get(messageId);

package/dist/test/message-range-store.test.js

@@ -95,6 +95,22 @@ const ids = (messages) => (messages ?? []).map((m) => m.id);
         (0, chai_1.expect)(store.snapshot()).to.have.length(1);
         (0, chai_1.expect)(ids(store.read(idAt(0), 10))).to.deep.equal(ids(page));
     });
+    (0, mocha_1.it)("replaces an updated message without changing range coverage", () => {
+        const page = makeMessages(5, 20);
+        store.record({ before: idAt(0), limit: 5, page });
+        const before = store.snapshot();
+        const updated = {
+            ...page[2],
+            data: { i: 2, analysed_by: "detector" },
+            attachments: [{ id: "updated-image" }],
+        };
+        store.recordUpdate(updated);
+        const read = store.read(idAt(0), 5);
+        (0, chai_1.expect)(read[2]).to.equal(updated);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page));
+        (0, chai_1.expect)(store.snapshot().map(({ lo, hi, atStart }) => ({ lo, hi, atStart })))
+            .to.deep.equal(before.map(({ lo, hi, atStart }) => ({ lo, hi, atStart })));
+    });
     (0, mocha_1.it)("keeps disjoint ranges apart rather than claiming the gap", () => {
         const ancient = makeMessages(5, 500);
         const recent = makeMessages(5, 20);

package/dist/test/react.test.js

@@ -208,7 +208,7 @@ function wrapper(client) {
         const cached = queryClient.getQueryData((0, react_2.channelAggregateQueryKey)("a1", "ui_cmds"));
         (0, chai_1.expect)(cached).to.deep.include({ data: { y: 2 }, attachments: [] });
     });
-    (0, mocha_1.it)("useChannelMessages paginates and prepends on live messageCreate", async () => {
+    (0, mocha_1.it)("useChannelMessages applies live creates and updates", 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"));
@@ -269,6 +269,28 @@ function wrapper(client) {
             newId,
             liveId,
         ]));
+        await (0, react_1.act)(async () => {
+            helpers_1.MockWebSocket.instances[0].receive({
+                op: 0,
+                t: "MessageUpdate",
+                d: {
+                    message: {
+                        id: newId,
+                        author_id: "u1",
+                        channel: { agent_id: "a1", name: "notes" },
+                        data: { v: 22, analysed_by: "detector" },
+                        attachments: [{ id: "analysed-image" }],
+                    },
+                    request_data: {},
+                },
+            });
+        });
+        await (0, react_1.waitFor)(() => {
+            const updated = result.current.messages.find((message) => message.id === newId);
+            (0, chai_1.expect)(updated?.data).to.deep.equal({ v: 22, analysed_by: "detector" });
+            (0, chai_1.expect)(updated?.attachments).to.have.length(1);
+            (0, chai_1.expect)(updated?.attachments?.[0]).to.deep.include({ id: "analysed-image" });
+        });
     });
     (0, mocha_1.it)("useChannelMessage seeds via REST and patches on MessageUpdate", async () => {
         const messageId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00.000Z"));

package/dist/test/rpc-dispatcher.test.js

@@ -188,3 +188,64 @@ describe("RpcDispatcher stats integration", () => {
         (0, chai_1.expect)(snap.rpc.peakPendingRpcs).to.equal(1);
     });
 });
+describe("RpcDispatcher pending timeout", () => {
+    const setup = (id) => {
+        const gw = makeFakeGateway();
+        const messages = makeFakeMessagesApi();
+        messages.setNextId(id);
+        const dispatcher = new rpc_dispatcher_1.RpcDispatcher(gw, messages);
+        return { gw, dispatcher, channel: { agent_id: "a1", name: "c1" } };
+    };
+    it("replaces the initial timeout once the device answers", async () => {
+        const { gw, dispatcher, channel } = setup("rpc-p1");
+        const promise = dispatcher.send({ agentId: "a1", channelName: "c1" }, { method: "do", request: {} }, { timeoutMs: 10, pendingTimeoutMs: 200 });
+        await new Promise((r) => setImmediate(r));
+        // Acknowledged before the 10ms deadline: the command must survive well past
+        // it, because the device has proven it is working.
+        gw.emitMessageUpdate(rpcMessage("rpc-p1", channel, { code: "acknowledged", message: { timestamp: 1 } }, {}));
+        await new Promise((r) => setTimeout(r, 60));
+        gw.emitMessageUpdate(rpcMessage("rpc-p1", channel, { code: "success" }, {}, { ok: true }));
+        (0, chai_1.expect)(await promise).to.deep.equal({ ok: true });
+    });
+    it("re-arms the pending budget on every progress report", async () => {
+        const { gw, dispatcher, channel } = setup("rpc-p2");
+        const promise = dispatcher.send({ agentId: "a1", channelName: "c1" }, { method: "do", request: {} }, { timeoutMs: 10, pendingTimeoutMs: 50 });
+        await new Promise((r) => setImmediate(r));
+        // Four reports, each well inside the 50ms budget but cumulatively past it.
+        for (let i = 0; i < 4; i += 1) {
+            gw.emitMessageUpdate(rpcMessage("rpc-p2", channel, { code: "pending", message: { text: `step ${i}` } }, {}));
+            await new Promise((r) => setTimeout(r, 30));
+        }
+        gw.emitMessageUpdate(rpcMessage("rpc-p2", channel, { code: "success" }, {}, { ok: 1 }));
+        (0, chai_1.expect)(await promise).to.deep.equal({ ok: 1 });
+    });
+    it("fails a device that answers and then goes quiet", async () => {
+        const { gw, dispatcher, channel } = setup("rpc-p3");
+        const promise = dispatcher.send({ agentId: "a1", channelName: "c1" }, { method: "do", request: {} }, { timeoutMs: 1000, pendingTimeoutMs: 20 });
+        await new Promise((r) => setImmediate(r));
+        gw.emitMessageUpdate(rpcMessage("rpc-p3", channel, { code: "acknowledged", message: { timestamp: 1 } }, {}));
+        let caught;
+        try {
+            await promise;
+        }
+        catch (e) {
+            caught = e;
+        }
+        // Distinct from "RPC timed out": it answered, then stopped.
+        (0, chai_1.expect)(caught?.message).to.equal("Device stopped reporting progress");
+    });
+    it("keeps the flat deadline when no pending budget is given", async () => {
+        const { gw, dispatcher, channel } = setup("rpc-p4");
+        const promise = dispatcher.send({ agentId: "a1", channelName: "c1" }, { method: "do", request: {} }, { timeoutMs: 20 });
+        await new Promise((r) => setImmediate(r));
+        gw.emitMessageUpdate(rpcMessage("rpc-p4", channel, { code: "acknowledged", message: { timestamp: 1 } }, {}));
+        let caught;
+        try {
+            await promise;
+        }
+        catch (e) {
+            caught = e;
+        }
+        (0, chai_1.expect)(caught?.message).to.equal("RPC timed out");
+    });
+});

package/dist/test/utils.test.js

@@ -12,6 +12,16 @@ const path_parsing_1 = require("../viewer/path-parsing");
         (0, chai_1.expect)(extracted.timestamp).to.equal(date.getTime());
         (0, chai_1.expect)(id).to.match(/^\d+$/);
     });
+    (0, mocha_1.it)("floors a pre-epoch time at the oldest addressable id", () => {
+        // Ids are unsigned; the API rejects a negative one outright and fails the whole
+        // request, so a caller reaching further back than 2025-01-01 gets the epoch.
+        (0, chai_1.expect)((0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2023-11-18T02:58:19.326Z"))).to.equal("0");
+        (0, chai_1.expect)((0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2025-01-01T00:00:00.000Z"))).to.equal("0");
+        (0, chai_1.expect)((0, snowflake_1.generateSnowflakeIdAtTime)(new Date(0))).to.equal("0");
+    });
+    (0, mocha_1.it)("rejects an invalid time rather than emitting a garbage id", () => {
+        (0, chai_1.expect)(() => (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("nonsense"))).to.throw(TypeError);
+    });
     (0, mocha_1.it)("adds an epoch-ms timestamp to messages", () => {
         const date = new Date("2026-01-02T03:04:05.000Z");
         const id = (0, snowflake_1.generateSnowflakeIdAtTime)(date);

package/dist/types/common.d.ts

@@ -146,9 +146,18 @@ export interface DataSeries {
     __source?: SourceProvenance;
 }
 /**
- * Lifecycle status for an RPC. `pending` carries arbitrary intermediate
- * payloads (progress updates) emitted by the server while the request is
- * in flight.
+ * Lifecycle status for an RPC.
+ *
+ * `sent` is written by the sender; the other non-terminal codes come from the
+ * device handling the request. `acknowledged` means it has picked the request
+ * up, and `pending` carries arbitrary intermediate payloads (progress updates)
+ * it emits while still working — by convention a `{ text }` summary, plus
+ * whatever structured fields the handler wants alongside it. Both prove the
+ * device is alive, so consumers should treat either as a reason to extend how
+ * long they are willing to wait (see `SendRpcOptions.pendingTimeoutMs`), never
+ * as a completion.
+ *
+ * `success` and `error` are the only terminal codes.
  */
 export type RpcStatus<TPending = undefined> = {
     code: "awaiting_confirmation";

package/dist/utils/snowflake.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Snowflake id for a point in time, floored at the epoch.
+ *
+ * Ids are unsigned, so a pre-epoch time has no id to generate. Returning the
+ * negative arithmetic result produced a value the API rejects outright
+ * ("expected a snowflake id value"), failing the whole request; `0` is the
+ * oldest addressable id, which is what a caller reaching further back wants.
+ */
 export declare function generateSnowflakeIdAtTime(time: {
     valueOf(): number;
 }): string;

package/dist/utils/snowflake.js

@@ -3,10 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateSnowflakeIdAtTime = generateSnowflakeIdAtTime;
 exports.extractSnowflakeId = extractSnowflakeId;
 exports.addTimestampToMessage = addTimestampToMessage;
+/** Doover's snowflake epoch: 2025-01-01T00:00:00Z. Nothing predates it. */
+const SNOWFLAKE_EPOCH_MS = 1735689600000;
+/**
+ * Snowflake id for a point in time, floored at the epoch.
+ *
+ * Ids are unsigned, so a pre-epoch time has no id to generate. Returning the
+ * negative arithmetic result produced a value the API rejects outright
+ * ("expected a snowflake id value"), failing the whole request; `0` is the
+ * oldest addressable id, which is what a caller reaching further back wants.
+ */
 function generateSnowflakeIdAtTime(time) {
-    const offset = 1735689600000;
-    const bigTime = BigInt(time.valueOf() - offset);
-    const bigId = bigTime << 22n;
+    const offsetMs = time.valueOf() - SNOWFLAKE_EPOCH_MS;
+    if (Number.isNaN(offsetMs)) {
+        throw new TypeError("generateSnowflakeIdAtTime received an invalid time");
+    }
+    const bigId = BigInt(Math.max(0, offsetMs)) << 22n;
     return bigId.toString();
 }
 function extractSnowflakeId(id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",