doover-js 0.4.1 → 0.4.3

package/dist/react/index.d.ts

@@ -6,7 +6,7 @@ export { useAgentConnections, agentConnectionsQueryKey, } from "./useAgentConnec
 export { useChannelSubscription, } from "./useChannelSubscription";
 export type { ChannelSubscriptionHandlers } from "./useChannelSubscription";
 export { useChannelAggregate, channelAggregateQueryKey, } from "./useChannelAggregate";
-export type { UseChannelAggregateResult } from "./useChannelAggregate";
+export type { UseChannelAggregateOptions, UseChannelAggregateResult, } from "./useChannelAggregate";
 export { useAgentChannel } from "./useAgentChannel";
 export { useSendMessage } from "./useSendMessage";
 export { useUpdateAggregate } from "./useUpdateAggregate";
@@ -15,6 +15,8 @@ export { useUpdateMessage } from "./useUpdateMessage";
 export type { UpdateMessageVariables, UseUpdateMessageOptions, } from "./useUpdateMessage";
 export { useChannelMessages, channelMessagesQueryKey, } from "./useChannelMessages";
 export type { UseChannelMessagesOptions, UseChannelMessagesResult, } from "./useChannelMessages";
+export { useChannelMessage, channelMessageQueryKey, } from "./useChannelMessage";
+export type { UseChannelMessageOptions, UseChannelMessageResult, } from "./useChannelMessage";
 export { useSendRpc } from "./useSendRpc";
 export type { RpcCommandId, RpcStatusEvent, SendRpcVariables, UseSendRpcOptions, UseSendRpcResult, } from "./useSendRpc";
 export { useMultiAgentAggregates, multiAgentAggregatesQueryKey, } from "./useMultiAgentAggregates";

package/dist/react/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.useDooverClient = exports.DooverProvider = void 0;
+exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.useDooverClient = exports.DooverProvider = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "DooverProvider", { enumerable: true, get: function () { return context_1.DooverProvider; } });
 Object.defineProperty(exports, "useDooverClient", { enumerable: true, get: function () { return context_1.useDooverClient; } });
@@ -25,6 +25,9 @@ Object.defineProperty(exports, "useUpdateMessage", { enumerable: true, get: func
 var useChannelMessages_1 = require("./useChannelMessages");
 Object.defineProperty(exports, "useChannelMessages", { enumerable: true, get: function () { return useChannelMessages_1.useChannelMessages; } });
 Object.defineProperty(exports, "channelMessagesQueryKey", { enumerable: true, get: function () { return useChannelMessages_1.channelMessagesQueryKey; } });
+var useChannelMessage_1 = require("./useChannelMessage");
+Object.defineProperty(exports, "useChannelMessage", { enumerable: true, get: function () { return useChannelMessage_1.useChannelMessage; } });
+Object.defineProperty(exports, "channelMessageQueryKey", { enumerable: true, get: function () { return useChannelMessage_1.channelMessageQueryKey; } });
 var useSendRpc_1 = require("./useSendRpc");
 Object.defineProperty(exports, "useSendRpc", { enumerable: true, get: function () { return useSendRpc_1.useSendRpc; } });
 var useMultiAgentAggregates_1 = require("./useMultiAgentAggregates");

package/dist/react/useAgentChannel.d.ts

@@ -1,7 +1,8 @@
 import type { Aggregate } from "../types/common";
+import { type UseChannelAggregateOptions } from "./useChannelAggregate";
 /**
  * Convenience wrapper around `useChannelAggregate` that accepts an agent id
  * and channel name as separate arguments — the most common shape at call
  * sites where the identifier isn't already a `ChannelIdentifier`.
  */
-export declare function useAgentChannel<TData = Aggregate["data"]>(agentId: string | undefined, channelName: string): import("./useChannelAggregate").UseChannelAggregateResult<TData>;
+export declare function useAgentChannel<TData = Aggregate["data"]>(agentId: string | undefined, channelName: string, options?: UseChannelAggregateOptions): import("./useChannelAggregate").UseChannelAggregateResult<TData>;

package/dist/react/useAgentChannel.js

@@ -7,6 +7,6 @@ const useChannelAggregate_1 = require("./useChannelAggregate");
  * and channel name as separate arguments — the most common shape at call
  * sites where the identifier isn't already a `ChannelIdentifier`.
  */
-function useAgentChannel(agentId, channelName) {
-    return (0, useChannelAggregate_1.useChannelAggregate)({ agentId, channelName });
+function useAgentChannel(agentId, channelName, options) {
+    return (0, useChannelAggregate_1.useChannelAggregate)({ agentId, channelName }, options);
 }

package/dist/react/useChannelAggregate.d.ts

@@ -19,6 +19,22 @@ export interface UseChannelAggregateResult<TData> extends Omit<UseQueryResult<Ag
     /** Server timestamp (epoch seconds) of the last aggregate update. */
     last_updated: number | null | undefined;
 }
+export interface UseChannelAggregateOptions {
+    /**
+     * Whether to fetch the initial aggregate over REST on mount.
+     *
+     * Defaults to `true` — the hook does a one-shot HTTP GET to seed the cache
+     * before the gateway WebSocket has connected, so the first paint isn't
+     * empty.
+     *
+     * Set to `false` for purely WS-driven consumers that don't want the REST
+     * round-trip (e.g. when the gateway's upsert-on-subscribe semantics make
+     * the REST call redundant or actively wrong, like channels that don't yet
+     * exist). The cache is then populated only by `ChannelSync` /
+     * `AggregateUpdate` events.
+     */
+    fetchInitial?: boolean;
+}
 /**
  * Fetch a channel's aggregate and keep it live via the gateway. Incoming
  * `channelSync` and `aggregateUpdate` events patch the react-query cache
@@ -30,4 +46,4 @@ export interface UseChannelAggregateResult<TData> extends Omit<UseQueryResult<Ag
  * don't have the implicit index signature that `Aggregate["data"]` carries
  * and enforcing compatibility there just forces `as` casts at call sites.
  */
-export declare function useChannelAggregate<TData = Aggregate["data"]>(identifier: ChannelIdentifier): UseChannelAggregateResult<TData>;
+export declare function useChannelAggregate<TData = Aggregate["data"]>(identifier: ChannelIdentifier, options?: UseChannelAggregateOptions): UseChannelAggregateResult<TData>;

package/dist/react/useChannelAggregate.js

@@ -4,6 +4,7 @@ exports.channelAggregateQueryKey = channelAggregateQueryKey;
 exports.useChannelAggregate = useChannelAggregate;
 const react_1 = require("react");
 const react_query_1 = require("@tanstack/react-query");
+const errors_1 = require("../http/errors");
 const context_1 = require("./context");
 const useChannelSubscription_1 = require("./useChannelSubscription");
 function channelAggregateQueryKey(agentId, channelName) {
@@ -20,11 +21,12 @@ function channelAggregateQueryKey(agentId, channelName) {
  * don't have the implicit index signature that `Aggregate["data"]` carries
  * and enforcing compatibility there just forces `as` casts at call sites.
  */
-function useChannelAggregate(identifier) {
+function useChannelAggregate(identifier, options) {
     const client = (0, context_1.useDooverClient)();
     const queryClient = (0, react_query_1.useQueryClient)();
     const { agentId, channelName } = identifier;
     const key = channelAggregateQueryKey(agentId, channelName);
+    const fetchInitial = options?.fetchInitial ?? true;
     const onAggregate = (0, react_1.useCallback)((aggregate) => {
         queryClient.setQueryData(key, aggregate);
     }, 
@@ -34,9 +36,18 @@ function useChannelAggregate(identifier) {
     (0, useChannelSubscription_1.useChannelSubscription)(identifier, { onAggregate });
     const query = (0, react_query_1.useQuery)({
         queryKey: key,
-        enabled: !!agentId && !!channelName,
+        enabled: fetchInitial && !!agentId && !!channelName,
         staleTime: Infinity,
         queryFn: () => client.viewer.getAggregate(identifier),
+        // A 404 means the aggregate doesn't exist — retrying won't change that,
+        // and the caller needs the error promptly to render an empty/"not
+        // installed" state. Fall back to the react-query default (3 retries) for
+        // every other failure.
+        retry: (failureCount, error) => {
+            if (error instanceof errors_1.DooverApiError && error.status === 404)
+                return false;
+            return failureCount < 3;
+        },
     });
     const aggregate = query.data;
     const { data: _ignored, ...rest } = query;

package/dist/react/useChannelMessage.d.ts

@@ -0,0 +1,38 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { JSONValue, MessageAttachment, MessageStructure } from "../types/common";
+import type { ChannelIdentifier } from "../types/viewer";
+export declare function channelMessageQueryKey(agentId: string | undefined, channelName: string | undefined, messageId: string | undefined): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "message", string | undefined];
+export interface UseChannelMessageOptions {
+    /** If false, skip subscribing for live message-update events. Defaults true. */
+    liveUpdates?: boolean;
+}
+/**
+ * Shape returned by `useChannelMessage`. Mirrors `UseChannelAggregateResult`:
+ * `data` is unwrapped to the message payload (`message.data`) so the common
+ * `const { data } = useChannelMessage(…)` pattern works without a secondary
+ * access. The full `MessageStructure` and a couple of useful slots
+ * (`attachments`, `timestamp`) are hoisted alongside.
+ */
+export interface UseChannelMessageResult<TData> extends Omit<UseQueryResult<MessageStructure<TData> | undefined>, "data"> {
+    /** Unwrapped message payload (`message.data`). Undefined until first fetch. */
+    data: TData | undefined;
+    /** Full message structure, or undefined until first fetch. */
+    message: MessageStructure<TData> | undefined;
+    attachments: MessageAttachment[] | undefined;
+    /** Server timestamp reported by the message. */
+    timestamp: number | undefined;
+}
+/**
+ * Fetch a single channel message by id and keep it live via gateway
+ * `MessageUpdate` events. Mirrors `useChannelAggregate`'s pattern: REST seeds
+ * the cache, then `onMessageUpdate` patches it whenever the message body is
+ * mutated server-side — handy for watching long-running RPC-style messages
+ * where the receiver writes progress into a `response` field.
+ *
+ * Channel subscriptions deliver every message in the channel, so the
+ * handlers filter to the requested `messageId` before patching the cache.
+ *
+ * Typed on `TData` — the shape of `message.data`. Defaults to `JSONValue` to
+ * match `MessageStructure`.
+ */
+export declare function useChannelMessage<TData = JSONValue>(identifier: ChannelIdentifier, messageId: string | undefined, options?: UseChannelMessageOptions): UseChannelMessageResult<TData>;

package/dist/react/useChannelMessage.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.channelMessageQueryKey = channelMessageQueryKey;
+exports.useChannelMessage = useChannelMessage;
+const react_1 = require("react");
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+const useChannelSubscription_1 = require("./useChannelSubscription");
+function channelMessageQueryKey(agentId, channelName, messageId) {
+    return [
+        "doover",
+        "agent",
+        agentId,
+        "channel",
+        channelName,
+        "message",
+        messageId,
+    ];
+}
+/**
+ * Fetch a single channel message by id and keep it live via gateway
+ * `MessageUpdate` events. Mirrors `useChannelAggregate`'s pattern: REST seeds
+ * the cache, then `onMessageUpdate` patches it whenever the message body is
+ * mutated server-side — handy for watching long-running RPC-style messages
+ * where the receiver writes progress into a `response` field.
+ *
+ * Channel subscriptions deliver every message in the channel, so the
+ * handlers filter to the requested `messageId` before patching the cache.
+ *
+ * Typed on `TData` — the shape of `message.data`. Defaults to `JSONValue` to
+ * match `MessageStructure`.
+ */
+function useChannelMessage(identifier, messageId, options) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { agentId, channelName } = identifier;
+    const liveUpdates = options?.liveUpdates ?? true;
+    const key = channelMessageQueryKey(agentId, channelName, messageId);
+    const onMessageUpdate = (0, react_1.useCallback)((message) => {
+        if (message.id !== messageId)
+            return;
+        queryClient.setQueryData(key, message);
+    }, 
+    // The key array is structurally stable per (agentId, channelName, messageId).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName, messageId]);
+    // Cover the case where the caller has the id before the create event has
+    // landed on this client — patch the cache when it shows up.
+    const onMessage = (0, react_1.useCallback)((message) => {
+        if (message.id !== messageId)
+            return;
+        queryClient.setQueryData(key, message);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName, messageId]);
+    (0, useChannelSubscription_1.useChannelSubscription)(liveUpdates && messageId ? identifier : undefined, { onMessage, onMessageUpdate });
+    const query = (0, react_query_1.useQuery)({
+        queryKey: key,
+        enabled: !!agentId && !!channelName && !!messageId,
+        staleTime: Infinity,
+        queryFn: () => client.messages.getMessage(agentId, channelName, messageId),
+    });
+    const message = query.data;
+    const { data: _ignored, ...rest } = query;
+    return {
+        ...rest,
+        data: message?.data,
+        message,
+        attachments: message?.attachments,
+        timestamp: message?.timestamp,
+    };
+}

package/dist/test/react.test.js

@@ -270,6 +270,72 @@ function wrapper(client) {
             liveId,
         ]));
     });
+    (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"));
+        const otherId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:01.000Z"));
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({
+            id: messageId,
+            author_id: "u1",
+            channel: { agent_id: "a1", name: "rpc" },
+            data: { method: "ping", response: { status: "pulling" } },
+            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.useChannelMessage)({ agentId: "a1", channelName: "rpc" }, messageId), { 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?.response?.status).to.equal("pulling");
+        (0, chai_1.expect)(result.current.message?.id).to.equal(messageId);
+        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: [] },
+            });
+            // Update for an unrelated message — should be ignored.
+            ws.receive({
+                op: 0,
+                t: "MessageUpdate",
+                d: {
+                    channel: { agent_id: "a1", name: "rpc" },
+                    author_id: "u1",
+                    message: {
+                        id: otherId,
+                        author_id: "u1",
+                        channel: { agent_id: "a1", name: "rpc" },
+                        data: { method: "ping", response: { status: "success" } },
+                        attachments: [],
+                    },
+                },
+            });
+            // Update for the message we're watching — should patch.
+            ws.receive({
+                op: 0,
+                t: "MessageUpdate",
+                d: {
+                    channel: { agent_id: "a1", name: "rpc" },
+                    author_id: "u1",
+                    message: {
+                        id: messageId,
+                        author_id: "u1",
+                        channel: { agent_id: "a1", name: "rpc" },
+                        data: { method: "ping", response: { status: "success" } },
+                        attachments: [],
+                    },
+                },
+            });
+        });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.data?.response?.status).to.equal("success"));
+    });
     (0, mocha_1.it)("getSharedQueryClient returns the same QueryClient across callers", () => {
         (0, react_2.resetSharedQueryClient)();
         const a = (0, react_2.getSharedQueryClient)();

package/package.json

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