doover-js 0.2.0-alpha.0 → 0.3.0

package/dist/react/useMultiAgentAggregates.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multiAgentAggregatesQueryKey = multiAgentAggregatesQueryKey;
+exports.useMultiAgentAggregates = useMultiAgentAggregates;
+const react_1 = require("react");
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+const useChannelAggregate_1 = require("./useChannelAggregate");
+function multiAgentAggregatesQueryKey(channelName, agentIds) {
+    return [
+        "doover",
+        "channel",
+        channelName,
+        "aggregates",
+        [...agentIds].sort().join(","),
+    ];
+}
+/**
+ * Batch-fetch aggregates for a channel across many agents, then keep each
+ * agent's slot live via its own gateway subscription. Reconciles per-agent
+ * `channelSync`/`aggregateUpdate` events into the batched query cache.
+ */
+function useMultiAgentAggregates(channelName, agentIds, options) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const liveUpdates = options?.liveUpdates ?? true;
+    const key = multiAgentAggregatesQueryKey(channelName, agentIds);
+    const query = (0, react_query_1.useQuery)({
+        queryKey: key,
+        enabled: agentIds.length > 0,
+        staleTime: Infinity,
+        queryFn: async () => {
+            const response = await client.agents.getMultiAgentAggregates(channelName, { agent_id: agentIds });
+            // Seed the per-agent `channelAggregateQueryKey` cache so that
+            // sibling `useChannelAggregate(id, channelName)` calls for any
+            // of these agents get an instant cache hit rather than issuing
+            // a second fetch for data we already have.
+            for (const result of response.results) {
+                const { agent_id, ...aggregate } = result;
+                queryClient.setQueryData((0, useChannelAggregate_1.channelAggregateQueryKey)(agent_id, channelName), aggregate);
+            }
+            return response;
+        },
+    });
+    const patchAgentAggregate = (0, react_1.useCallback)((agentId, aggregate) => {
+        queryClient.setQueryData(key, (current) => {
+            if (!current)
+                return current;
+            const idx = current.results.findIndex((r) => r.agent_id === agentId);
+            const next = {
+                agent_id: agentId,
+                ...aggregate,
+            };
+            const results = idx === -1
+                ? [...current.results, next]
+                : current.results.map((r, i) => (i === idx ? next : r));
+            return { ...current, results };
+        });
+        // Mirror live updates into the per-agent cache so sibling
+        // `useChannelAggregate` consumers see them too.
+        queryClient.setQueryData((0, useChannelAggregate_1.channelAggregateQueryKey)(agentId, channelName), aggregate);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, channelName, agentIds.join(",")]);
+    (0, react_1.useEffect)(() => {
+        if (!liveUpdates || agentIds.length === 0)
+            return;
+        const noopMessage = () => { };
+        const subscriptions = agentIds.map((agentId) => {
+            const identifier = { agentId, channelName };
+            const messageCallback = noopMessage;
+            const aggregateCallback = (_id, aggregate) => {
+                patchAgentAggregate(agentId, aggregate);
+            };
+            void client.viewer.subscribeToChannel(identifier, messageCallback, aggregateCallback);
+            return { identifier, messageCallback };
+        });
+        return () => {
+            for (const { identifier, messageCallback } of subscriptions) {
+                client.viewer
+                    .unsubscribeFromChannel(identifier, messageCallback)
+                    .catch(() => { });
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, channelName, liveUpdates, agentIds.join(",")]);
+    const aggregatesByAgent = (0, react_1.useMemo)(() => {
+        const map = {};
+        for (const entry of query.data?.results ?? []) {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { agent_id, ...aggregate } = entry;
+            map[agent_id] = aggregate;
+        }
+        return map;
+    }, [query.data]);
+    return { aggregatesByAgent, query };
+}

package/dist/react/useMultiAgentChannelMessages.d.ts

@@ -0,0 +1,25 @@
+import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-query";
+import type { MessageStructure } from "../types/common";
+export declare function multiAgentChannelMessagesQueryKey(channelName: string, agentIds: string[]): readonly ["doover", "channel", string, "messages", string];
+export interface UseMultiAgentChannelMessagesOptions {
+    limit?: number;
+    /** If false, skip live subscriptions per agent. Defaults true. */
+    liveUpdates?: boolean;
+    /**
+     * Restrict the returned messages to those whose payload contains any
+     * of these top-level field names. Forwarded as `field_name`.
+     */
+    fields?: string[];
+    /** Optional first-page `before` cursor (snowflake id). */
+    initialBefore?: string;
+}
+interface Page {
+    results: MessageStructure[];
+    next?: string;
+}
+export interface UseMultiAgentChannelMessagesResult extends Omit<UseInfiniteQueryResult<InfiniteData<Page>>, "data"> {
+    messages: MessageStructure[];
+    data: InfiniteData<Page> | undefined;
+}
+export declare function useMultiAgentChannelMessages(channelName: string, agentIds: string[], options?: UseMultiAgentChannelMessagesOptions): UseMultiAgentChannelMessagesResult;
+export {};

package/dist/react/useMultiAgentChannelMessages.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multiAgentChannelMessagesQueryKey = multiAgentChannelMessagesQueryKey;
+exports.useMultiAgentChannelMessages = useMultiAgentChannelMessages;
+const react_1 = require("react");
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+function multiAgentChannelMessagesQueryKey(channelName, agentIds) {
+    return [
+        "doover",
+        "channel",
+        channelName,
+        "messages",
+        [...agentIds].sort().join(","),
+    ];
+}
+function useMultiAgentChannelMessages(channelName, agentIds, options) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const limit = options?.limit;
+    const liveUpdates = options?.liveUpdates ?? true;
+    const fields = options?.fields;
+    const initialBefore = options?.initialBefore;
+    const key = multiAgentChannelMessagesQueryKey(channelName, agentIds);
+    const prependMessage = (0, react_1.useCallback)((message) => {
+        queryClient.setQueryData(key, (current) => {
+            if (!current)
+                return current;
+            const [firstPage, ...rest] = current.pages;
+            const firstResults = firstPage?.results ?? [];
+            return {
+                ...current,
+                pages: [
+                    { ...firstPage, results: [message, ...firstResults] },
+                    ...rest,
+                ],
+            };
+        });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, channelName, agentIds.join(",")]);
+    (0, react_1.useEffect)(() => {
+        if (!liveUpdates || agentIds.length === 0)
+            return;
+        const subscriptions = agentIds.map((agentId) => {
+            const identifier = { agentId, channelName };
+            const messageCallback = (_id, message) => {
+                prependMessage(message);
+            };
+            const aggregateCallback = () => { };
+            void client.viewer.subscribeToChannel(identifier, messageCallback, aggregateCallback);
+            return { identifier, messageCallback };
+        });
+        return () => {
+            for (const { identifier, messageCallback } of subscriptions) {
+                client.viewer
+                    .unsubscribeFromChannel(identifier, messageCallback)
+                    .catch(() => { });
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, channelName, liveUpdates, agentIds.join(",")]);
+    const query = (0, react_query_1.useInfiniteQuery)({
+        queryKey: key,
+        enabled: agentIds.length > 0,
+        staleTime: Infinity,
+        initialPageParam: initialBefore,
+        getNextPageParam: (lastPage) => lastPage?.next,
+        queryFn: async ({ pageParam }) => {
+            const page = await client.agents.getMultiAgentMessages(channelName, {
+                agent_id: agentIds,
+                ...(typeof pageParam === "string" ? { before: pageParam } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+                ...(fields && fields.length > 0 ? { field_name: fields } : {}),
+            });
+            return page;
+        },
+    });
+    const messages = (0, react_1.useMemo)(() => (query.data?.pages ?? []).flatMap((p) => p.results), [query.data]);
+    return { ...query, messages };
+}

package/dist/react/useSendMessage.d.ts

@@ -0,0 +1,9 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { MessageStructure } from "../types/common";
+import type { ChannelIdentifier } from "../types/viewer";
+/**
+ * Mutation wrapping `DooverDataProvider.sendMessage`. Posts a JSON message
+ * to the channel and resolves with the created `MessageStructure` (including
+ * its server-assigned `id` and `timestamp`).
+ */
+export declare function useSendMessage(identifier: ChannelIdentifier): UseMutationResult<MessageStructure, Error, object>;

package/dist/react/useSendMessage.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSendMessage = useSendMessage;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+/**
+ * Mutation wrapping `DooverDataProvider.sendMessage`. Posts a JSON message
+ * to the channel and resolves with the created `MessageStructure` (including
+ * its server-assigned `id` and `timestamp`).
+ */
+function useSendMessage(identifier) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (data) => client.viewer.sendMessage(identifier, data),
+    });
+}

package/dist/react/useSendRpc.d.ts

@@ -0,0 +1,61 @@
+import { type UseMutateAsyncFunction, type UseMutateFunction, type UseMutationResult } from "@tanstack/react-query";
+import type { RpcStatus } from "../types/common";
+import type { ChannelIdentifier } from "../types/viewer";
+export type RpcCommandId = string;
+export interface RpcStatusEvent<TPending = undefined> {
+    commandId: RpcCommandId;
+    status: RpcStatus<TPending>;
+    timestamp: number;
+}
+export interface SendRpcVariables<TRequest = object> {
+    commandId: RpcCommandId;
+    request: TRequest;
+    /** Optional per-call override of the app_key. */
+    app_key?: string;
+}
+interface CommandState<TPending, TResponse> {
+    current: RpcStatus<TPending>;
+    history: RpcStatusEvent<TPending>[];
+    submittedAt: number;
+    settledAt?: number;
+    data?: TResponse;
+    error?: unknown;
+}
+type CommandStatuses<TPending, TResponse> = Record<RpcCommandId, CommandState<TPending, TResponse>>;
+export interface UseSendRpcOptions {
+    /** Method name passed on every RPC from this hook. */
+    method: string;
+    /** Default app_key. Overridable per-call via variables.app_key. */
+    app_key?: string;
+    /**
+     * react-query mutation key. Defaults to
+     * `["doover", "agent", agentId, "channel", channelName, "rpc", method]`.
+     */
+    mutationKey?: readonly unknown[];
+}
+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`). */
+    currentStatus: RpcStatus<TPending> | undefined;
+    commandStatuses: CommandStatuses<TPending, TResponse>;
+    getStatus: (commandId: RpcCommandId) => RpcStatus<TPending> | undefined;
+    getHistory: (commandId: RpcCommandId) => RpcStatusEvent<TPending>[];
+    getCommandState: (commandId: RpcCommandId) => CommandState<TPending, TResponse> | undefined;
+    isPending: {
+        (): boolean;
+        (commandId: RpcCommandId): boolean;
+    };
+    mutate: UseMutateFunction<TResponse, unknown, SendRpcVariables<TRequest>, void>;
+    mutateAsync: UseMutateAsyncFunction<TResponse, unknown, SendRpcVariables<TRequest>, void>;
+}
+/**
+ * A react-query-integrated RPC hook. Calls
+ * `DooverDataProvider.sendRPC(identifier, { method, request, app_key })`
+ * under the hood and tracks a per-`commandId` status history so callers can
+ * render multi-step progress UIs and error popovers.
+ *
+ * For low-latency ephemeral commands (camera PTZ etc.) reach for
+ * `client.gateway.sendOneShotMessage` directly instead — those are not
+ * persisted and don't flow through this hook.
+ */
+export declare function useSendRpc<TRequest = object, TResponse = object, TPending = undefined>(identifier: ChannelIdentifier, options: UseSendRpcOptions): UseSendRpcResult<TRequest, TResponse, TPending>;
+export {};

package/dist/react/useSendRpc.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSendRpc = useSendRpc;
+const react_1 = require("react");
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+const SENT_STATUS = { code: "sent" };
+function isTerminal(status) {
+    return status?.code === "success" || status?.code === "error";
+}
+function isPendingCode(status) {
+    return (status?.code === "sent" ||
+        status?.code === "acknowledged" ||
+        status?.code === "deferred" ||
+        status?.code === "pending");
+}
+function toErrorStatus(error) {
+    if (error instanceof Error)
+        return { code: "error", message: error.message };
+    if (typeof error === "string")
+        return { code: "error", message: error };
+    return { code: "error", message: "Unknown RPC error" };
+}
+/**
+ * A react-query-integrated RPC hook. Calls
+ * `DooverDataProvider.sendRPC(identifier, { method, request, app_key })`
+ * under the hood and tracks a per-`commandId` status history so callers can
+ * render multi-step progress UIs and error popovers.
+ *
+ * For low-latency ephemeral commands (camera PTZ etc.) reach for
+ * `client.gateway.sendOneShotMessage` directly instead — those are not
+ * persisted and don't flow through this hook.
+ */
+function useSendRpc(identifier, options) {
+    const client = (0, context_1.useDooverClient)();
+    const [commandStatuses, setCommandStatuses] = (0, react_1.useState)({});
+    const mutationKey = options.mutationKey ??
+        [
+            "doover",
+            "agent",
+            identifier.agentId,
+            "channel",
+            identifier.channelName,
+            "rpc",
+            options.method,
+        ];
+    const appendStatus = (0, react_1.useCallback)((commandId, status) => {
+        const timestamp = Date.now();
+        setCommandStatuses((current) => {
+            const existing = current[commandId];
+            if (!existing || existing.settledAt !== undefined)
+                return current;
+            return {
+                ...current,
+                [commandId]: {
+                    ...existing,
+                    current: status,
+                    history: [...existing.history, { commandId, status, timestamp }],
+                },
+            };
+        });
+    }, []);
+    const settleCommand = (0, react_1.useCallback)((commandId, updates) => {
+        setCommandStatuses((current) => {
+            const existing = current[commandId];
+            if (!existing)
+                return current;
+            const settledAt = Date.now();
+            const next = {
+                ...existing,
+                settledAt,
+            };
+            if ("data" in updates)
+                next.data = updates.data;
+            if ("error" in updates)
+                next.error = updates.error;
+            if (updates.fallbackStatus && !isTerminal(existing.current)) {
+                next.current = updates.fallbackStatus;
+                next.history = [
+                    ...existing.history,
+                    {
+                        commandId,
+                        status: updates.fallbackStatus,
+                        timestamp: settledAt,
+                    },
+                ];
+            }
+            return { ...current, [commandId]: next };
+        });
+    }, []);
+    const mutation = (0, react_query_1.useMutation)({
+        mutationKey: [...mutationKey],
+        mutationFn: async ({ commandId, request, app_key }) => {
+            const submittedAt = Date.now();
+            setCommandStatuses((current) => ({
+                ...current,
+                [commandId]: {
+                    current: SENT_STATUS,
+                    history: [
+                        {
+                            commandId,
+                            status: SENT_STATUS,
+                            timestamp: submittedAt,
+                        },
+                    ],
+                    submittedAt,
+                },
+            }));
+            const rpcRequest = {
+                method: options.method,
+                request,
+                ...(app_key !== undefined
+                    ? { app_key }
+                    : options.app_key !== undefined
+                        ? { app_key: options.app_key }
+                        : {}),
+            };
+            return client.viewer.sendRPC(identifier, rpcRequest, {
+                onStatus: (status) => appendStatus(commandId, status),
+            });
+        },
+        onSuccess: (data, variables) => settleCommand(variables.commandId, {
+            data,
+            fallbackStatus: { code: "success" },
+        }),
+        onError: (error, variables) => settleCommand(variables.commandId, {
+            error,
+            fallbackStatus: toErrorStatus(error),
+        }),
+    });
+    const getCommandState = (0, react_1.useCallback)((commandId) => commandStatuses[commandId], [commandStatuses]);
+    const getStatus = (0, react_1.useCallback)((commandId) => getCommandState(commandId)?.current, [getCommandState]);
+    const getHistory = (0, react_1.useCallback)((commandId) => getCommandState(commandId)?.history ?? [], [getCommandState]);
+    const currentStatus = (0, react_1.useMemo)(() => {
+        const latest = Object.values(commandStatuses).reduce((acc, state) => {
+            if (!acc || state.submittedAt > acc.submittedAt)
+                return state;
+            return acc;
+        }, undefined);
+        return latest?.current;
+    }, [commandStatuses]);
+    const isPending = ((commandId) => {
+        if (commandId === undefined)
+            return mutation.isPending;
+        return isPendingCode(getStatus(commandId));
+    });
+    return {
+        ...mutation,
+        mutate: mutation.mutate,
+        mutateAsync: mutation.mutateAsync,
+        currentStatus,
+        commandStatuses,
+        getStatus,
+        getHistory,
+        getCommandState,
+        isPending,
+    };
+}

package/dist/react/useTurnCredentials.d.ts

@@ -0,0 +1,12 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { TurnCredential } from "../types/common";
+import type { TurnTokenRequest } from "../types/openapi";
+/**
+ * Fetch TURN (relay) credentials for a camera stream. Cached for 10 minutes
+ * by default since the token has a server-controlled TTL; consumers that
+ * need refresh-on-expiry should do so at the call site.
+ */
+export declare function useTurnCredentials(request: TurnTokenRequest, options?: {
+    enabled?: boolean;
+    staleTime?: number;
+}): UseQueryResult<TurnCredential>;

package/dist/react/useTurnCredentials.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTurnCredentials = useTurnCredentials;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+/**
+ * Fetch TURN (relay) credentials for a camera stream. Cached for 10 minutes
+ * by default since the token has a server-controlled TTL; consumers that
+ * need refresh-on-expiry should do so at the call site.
+ */
+function useTurnCredentials(request, options) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useQuery)({
+        queryKey: [
+            "doover",
+            "turn",
+            request.role,
+            request.device_id ?? null,
+            request.camera_name,
+        ],
+        enabled: options?.enabled ?? true,
+        staleTime: options?.staleTime ?? 10 * 60 * 1000,
+        queryFn: () => client.turn.createTurnToken(request),
+    });
+}

package/dist/react/useUpdateAggregate.d.ts

@@ -0,0 +1,21 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { AggregateMutationParams } from "../apis/aggregates-api";
+import type { Aggregate } from "../types/common";
+import type { ChannelIdentifier } from "../types/viewer";
+export interface UseUpdateAggregateOptions {
+    /** If true, use PUT semantics (replace) instead of PATCH (merge). */
+    replace?: boolean;
+    /**
+     * Forwarded as query params to the aggregate endpoint:
+     * `log_update` (record a history message), `clear_attachments`,
+     * `suppress_response`. See `AggregateMutationParams`.
+     */
+    params?: AggregateMutationParams;
+}
+/**
+ * Mutation wrapping `DooverDataProvider.updateAggregate` (PATCH) or
+ * `putAggregate` (PUT when `replace: true`). Also writes the returned
+ * aggregate into the react-query cache for its channel so consumers of
+ * `useChannelAggregate` see the change immediately.
+ */
+export declare function useUpdateAggregate(identifier: ChannelIdentifier, options?: UseUpdateAggregateOptions): UseMutationResult<Aggregate, Error, object>;

package/dist/react/useUpdateAggregate.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useUpdateAggregate = useUpdateAggregate;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+const useChannelAggregate_1 = require("./useChannelAggregate");
+/**
+ * Mutation wrapping `DooverDataProvider.updateAggregate` (PATCH) or
+ * `putAggregate` (PUT when `replace: true`). Also writes the returned
+ * aggregate into the react-query cache for its channel so consumers of
+ * `useChannelAggregate` see the change immediately.
+ */
+function useUpdateAggregate(identifier, options) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const replace = options?.replace ?? false;
+    const params = options?.params;
+    return (0, react_query_1.useMutation)({
+        mutationFn: (data) => replace
+            ? client.viewer.putAggregate(identifier, data, params)
+            : client.viewer.updateAggregate(identifier, data, params),
+        onSuccess: (aggregate) => {
+            queryClient.setQueryData((0, useChannelAggregate_1.channelAggregateQueryKey)(identifier.agentId, identifier.channelName), aggregate);
+        },
+    });
+}

package/dist/react/useUpdateMessage.d.ts

@@ -0,0 +1,33 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { MessageBody, MessageMutationParams } from "../apis/messages-api";
+import type { ChannelIdentifier } from "../types/viewer";
+export interface UpdateMessageCallOptions {
+    /**
+     * If true, use PUT (replace) instead of PATCH (merge). Falls back to
+     * the hook-level `replace` option, which itself defaults to PATCH.
+     */
+    replace?: boolean;
+    /**
+     * Query params forwarded to the message endpoint. Merged over the
+     * hook-level `params` option (per-call keys win).
+     */
+    params?: MessageMutationParams;
+}
+export interface UseUpdateMessageOptions extends UpdateMessageCallOptions {
+}
+export interface UpdateMessageVariables {
+    messageId: string;
+    body: MessageBody;
+    /**
+     * Per-call overrides. Extensible — add new knobs here without breaking
+     * the variables shape.
+     */
+    options?: UpdateMessageCallOptions;
+}
+/**
+ * Mutation wrapping `MessagesApi.patchMessage` or `putMessage`. Bound to a
+ * single channel; the message id and body are passed per-call. Each
+ * invocation can override `replace` / `params` via `variables.options` for
+ * mutation sites that sometimes PUT and sometimes PATCH the same channel.
+ */
+export declare function useUpdateMessage(identifier: ChannelIdentifier, options?: UseUpdateMessageOptions): UseMutationResult<unknown, Error, UpdateMessageVariables>;

package/dist/react/useUpdateMessage.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useUpdateMessage = useUpdateMessage;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+/**
+ * Mutation wrapping `MessagesApi.patchMessage` or `putMessage`. Bound to a
+ * single channel; the message id and body are passed per-call. Each
+ * invocation can override `replace` / `params` via `variables.options` for
+ * mutation sites that sometimes PUT and sometimes PATCH the same channel.
+ */
+function useUpdateMessage(identifier, options) {
+    const client = (0, context_1.useDooverClient)();
+    const defaultReplace = options?.replace ?? false;
+    const defaultParams = options?.params;
+    return (0, react_query_1.useMutation)({
+        mutationFn: ({ messageId, body, options: call }) => {
+            if (!identifier.agentId || !identifier.channelName) {
+                throw new Error("useUpdateMessage requires both agentId and channelName on the identifier.");
+            }
+            const replace = call?.replace ?? defaultReplace;
+            const params = call?.params || defaultParams
+                ? { ...defaultParams, ...call?.params }
+                : undefined;
+            return replace
+                ? client.messages.putMessage(identifier.agentId, identifier.channelName, messageId, body, params)
+                : client.messages.patchMessage(identifier.agentId, identifier.channelName, messageId, body, params);
+        },
+    });
+}

package/dist/test/apis.test.js

@@ -177,6 +177,12 @@ function setupRest(responseFactory) {
         await connections.getAgentSubscriptionHistory("a1", { channel: "{\"agent_id\":\"a1\",\"name\":\"c1\"}" });
         await connections.getConnection("conn");
         await connections.getChannelSubscriptions("a1", "c1");
+        await connections.syncConnection("a1");
+        const syncCall = fetchMock
+            .getCalls()
+            .find((call) => call.args[0].endsWith("/agents/a1/connection_sync"));
+        (0, chai_1.expect)(syncCall).to.not.equal(undefined);
+        (0, chai_1.expect)(syncCall.args[1].method).to.equal("POST");
         await notifications.getAgentNotifications("a1");
         await notifications.getAgentNotificationEndpoints("a1", "browser");
         await notifications.createNotificationEndpoint("a1", {
@@ -207,7 +213,7 @@ function setupRest(responseFactory) {
             expires_at: 1,
         });
         await notifications.getWebPushPublicKey();
-        (0, chai_1.expect)(fetchMock.callCount).to.equal(20);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(21);
     });
     (0, mocha_1.it)("covers permissions, processors, and turn methods", async () => {
         const { rest, fetchMock } = setupRest(() => (0, helpers_1.createJsonResponse)({ db: { agent_id: "a1", is_superuser: false, resources: [] } }));

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

@@ -26,4 +26,17 @@ const helpers_1 = require("./helpers");
         (0, chai_1.expect)(client.agents).to.exist;
         (0, chai_1.expect)(client.gateway).to.exist;
     });
+    (0, mocha_1.it)("shares a single GatewayClient between client.gateway and client.viewer.gateway", () => {
+        const client = new doover_client_1.DooverClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: (0, helpers_1.createFetchMock)(),
+            webSocketImpl: helpers_1.MockWebSocket,
+            disableBrowserLifecycleHooks: true,
+        });
+        // Regression: these used to be separate GatewayClient instances,
+        // each opening its own WebSocket on connect().
+        (0, chai_1.expect)(client.gateway).to.equal(client.viewer.gateway);
+    });
 });