doover-js 0.11.0 → 0.13.0

package/dist/esm/react/useMultiAgentChannelMessages.js

@@ -0,0 +1,169 @@
+import { useCallback, useEffect, useMemo } from "react";
+import { useInfiniteQuery, useQueryClient, } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+export function multiAgentChannelMessagesQueryKey(channelName, agentIds, sources, scope) {
+    const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
+    const base = [
+        "doover",
+        "channel",
+        channelName,
+        "messages",
+        [...agentIds].sort().join(","),
+        "src",
+        sourceDim,
+    ];
+    // Pagination cursors come from the first page's response and are scoped
+    // to *that* response's `after`/`fields`. Mixing them under one cache
+    // entry would cause `getNextPageParam` to anchor on an unrelated page,
+    // so a differently-bounded request must live under its own key.
+    const scopeKey = {};
+    if (scope?.after)
+        scopeKey.after = scope.after;
+    if (scope?.fields && scope.fields.length > 0) {
+        scopeKey.fields = [...scope.fields].sort();
+    }
+    return Object.keys(scopeKey).length > 0
+        ? [...base, scopeKey]
+        : base;
+}
+function nextPageParam(lastPage) {
+    if (!lastPage)
+        return undefined;
+    const cursors = lastPage.next_cursors;
+    if (cursors) {
+        const entries = Object.entries(cursors);
+        // Present-but-empty means every agent drained its window: we're done.
+        if (entries.length === 0)
+            return undefined;
+        return {
+            agentIds: entries.map(([id]) => id),
+            agentBefore: entries.map(([, cursor]) => cursor),
+        };
+    }
+    // Legacy server: one global `before` for whichever agents were at limit.
+    // Those agents whose own cursor is older than `next` re-return a few
+    // messages we already hold — harmless, since we dedupe by id below.
+    if (typeof lastPage.next === "string" && lastPage.next) {
+        return {
+            before: lastPage.next,
+            ...(lastPage.at_limit_agent_ids?.length
+                ? { agentIds: lastPage.at_limit_agent_ids }
+                : {}),
+        };
+    }
+    return undefined;
+}
+export function useMultiAgentChannelMessages(channelName, agentIds, options) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    const limit = options?.limit;
+    const agentMessageLimit = options?.agentMessageLimit;
+    const liveUpdates = options?.liveUpdates ?? true;
+    const fields = options?.fields;
+    const initialBefore = options?.initialBefore;
+    const sources = options?.sources;
+    const after = options?.after;
+    const autoPaginate = options?.autoPaginate ?? false;
+    const maxPages = options?.maxPages ?? 20;
+    const key = multiAgentChannelMessagesQueryKey(channelName, agentIds, sources, {
+        after,
+        fields,
+    });
+    const prependMessage = useCallback((message) => {
+        queryClient.setQueryData(key, (current) => {
+            if (!current)
+                return current;
+            const typed = message;
+            const [firstPage, ...rest] = current.pages;
+            const firstResults = firstPage?.results ?? [];
+            return {
+                ...current,
+                pages: [
+                    { ...firstPage, results: [typed, ...firstResults] },
+                    ...rest,
+                ],
+            };
+        });
+    }, 
+    // `key` captures every scope dim (agentIds + sources + after + fields);
+    // serialise the whole thing so the closure refreshes when any dim
+    // changes — listing dims by hand drops live updates whenever the list
+    // grows (we used to omit `after`/`fields`).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, JSON.stringify(key)]);
+    useEffect(() => {
+        if (!liveUpdates || agentIds.length === 0)
+            return;
+        const offs = agentIds.map((agentId) => {
+            const channel = { agent_id: agentId, name: channelName };
+            return client.gateway.subscribeToChannel(channel, {
+                onMessage: (msg) => prependMessage(msg),
+            });
+        });
+        void client.gateway.connect();
+        return () => {
+            for (const off of offs)
+                off();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, channelName, liveUpdates, agentIds.join(",")]);
+    const query = useInfiniteQuery({
+        queryKey: key,
+        enabled: agentIds.length > 0,
+        staleTime: Infinity,
+        initialPageParam: (initialBefore ? { before: initialBefore } : {}),
+        getNextPageParam: nextPageParam,
+        queryFn: async ({ pageParam }) => {
+            const params = {
+                agent_id: pageParam.agentIds ?? agentIds,
+                ...(pageParam.before ? { before: pageParam.before } : {}),
+                ...(pageParam.agentBefore ? { agent_before: pageParam.agentBefore } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+                ...(agentMessageLimit !== undefined
+                    ? { agent_message_limit: agentMessageLimit }
+                    : {}),
+                ...(fields && fields.length > 0 ? { field_name: fields } : {}),
+                ...(after !== undefined ? { after } : {}),
+            };
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `never` since the TypeScript overloads don't declare it.
+            const sourcesArg = sources ? { sources } : undefined;
+            const page = await (sourcesArg
+                ? client.agents.getMultiAgentMessages(channelName, params, sourcesArg)
+                : client.agents.getMultiAgentMessages(channelName, params));
+            return page;
+        },
+    });
+    useEffect(() => {
+        if (!autoPaginate)
+            return;
+        if (query.isFetching || !query.hasNextPage)
+            return;
+        if ((query.data?.pages.length ?? 0) >= maxPages)
+            return;
+        query.fetchNextPage();
+    }, [
+        autoPaginate,
+        maxPages,
+        query.isFetching,
+        query.hasNextPage,
+        query.fetchNextPage,
+        query.data?.pages.length,
+    ]);
+    const messages = useMemo(() => {
+        // The legacy single-cursor path (and a live push that races a page
+        // fetch) can hand us the same message twice; keep the first copy.
+        const seen = new Set();
+        const out = [];
+        for (const page of query.data?.pages ?? []) {
+            for (const message of page.results) {
+                if (seen.has(message.id))
+                    continue;
+                seen.add(message.id);
+                out.push(message);
+            }
+        }
+        return out;
+    }, [query.data]);
+    return { ...query, messages };
+}

package/dist/esm/react/useOfflineStatus.d.ts

@@ -0,0 +1,8 @@
+import type { OfflineStatusSnapshot } from "../client/offline-cache.js";
+export type { OfflineStatusSnapshot } from "../client/offline-cache.js";
+export interface OfflineStatusClient {
+    getOfflineStatus(): OfflineStatusSnapshot;
+    onOfflineStatusChange(listener: (status: OfflineStatusSnapshot) => void): () => void;
+}
+export declare function hasOfflineStatus(client: unknown): client is OfflineStatusClient;
+export declare function useOfflineStatus(): OfflineStatusSnapshot;

package/dist/esm/react/useOfflineStatus.js

@@ -0,0 +1,37 @@
+import { useMemo, useSyncExternalStore } from "react";
+import { browserNetworkStatus } from "../client/network-status.js";
+import { useDooverClient } from "./context.js";
+export function hasOfflineStatus(client) {
+    return !!client && typeof client === "object" &&
+        "getOfflineStatus" in client && typeof client.getOfflineStatus === "function" &&
+        "onOfflineStatusChange" in client && typeof client.onOfflineStatusChange === "function";
+}
+const SERVER_OFFLINE_STATUS = {
+    online: true, state: "online", isOfflineFallback: false, isExpired: false, at: 0,
+};
+export function useOfflineStatus() {
+    const client = useDooverClient();
+    const store = useMemo(() => {
+        if (hasOfflineStatus(client)) {
+            return {
+                subscribe: (listener) => client.onOfflineStatusChange(listener),
+                getSnapshot: () => client.getOfflineStatus(),
+            };
+        }
+        const network = client.networkStatus ?? browserNetworkStatus;
+        let previous = network.getSnapshot();
+        let snapshot = { ...SERVER_OFFLINE_STATUS, ...previous };
+        return {
+            subscribe: (listener) => network.subscribe(listener),
+            getSnapshot: () => {
+                const next = network.getSnapshot();
+                if (next !== previous) {
+                    previous = next;
+                    snapshot = { ...SERVER_OFFLINE_STATUS, ...next };
+                }
+                return snapshot;
+            },
+        };
+    }, [client]);
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, () => SERVER_OFFLINE_STATUS);
+}

package/dist/esm/react/useSendMessage.d.ts

@@ -0,0 +1,16 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { MessageStructure } from "../types/common.js";
+import type { ChannelIdentifier } from "../types/viewer.js";
+export interface UseSendMessageOptions {
+    /**
+     * Restrict the write to these source ids on a `MultiplexClient`. Ignored
+     * for a plain `DooverClient` or `LocalAgentClient`.
+     */
+    sources?: string[];
+}
+/**
+ * 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<TData extends object = object>(identifier: ChannelIdentifier, options?: UseSendMessageOptions): UseMutationResult<MessageStructure<TData>, Error, TData>;

package/dist/esm/react/useSendMessage.js

@@ -0,0 +1,26 @@
+import { useMutation } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+/**
+ * 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 function useSendMessage(identifier, options) {
+    const client = useDooverClient();
+    const sources = options?.sources;
+    return useMutation({
+        mutationFn: (data) => {
+            if (!identifier.agentId || !identifier.channelName) {
+                return Promise.reject(new Error("Identifier must include agentId and channelName"));
+            }
+            const id = { agentId: identifier.agentId, channelName: identifier.channelName };
+            const body = { data: data };
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `never` since the TypeScript overloads don't declare it.
+            const sourcesArg = sources ? { sources } : undefined;
+            return (sourcesArg
+                ? client.messages.postMessage(id, body, sourcesArg)
+                : client.messages.postMessage(id, body));
+        },
+    });
+}

package/dist/esm/react/useSendRpc.d.ts

@@ -0,0 +1,68 @@
+import { type UseMutateAsyncFunction, type UseMutateFunction, type UseMutationResult } from "@tanstack/react-query";
+import type { RpcStatus } from "../types/common.js";
+import type { ChannelIdentifier } from "../types/viewer.js";
+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[];
+    /** 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`). */
+    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/esm/react/useSendRpc.js

@@ -0,0 +1,164 @@
+import { useCallback, useMemo, useState } from "react";
+import { useMutation, } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+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.
+ */
+export function useSendRpc(identifier, options) {
+    const client = useDooverClient();
+    const [commandStatuses, setCommandStatuses] = useState({});
+    const mutationKey = options.mutationKey ??
+        [
+            "doover",
+            "agent",
+            identifier.agentId,
+            "channel",
+            identifier.channelName,
+            "rpc",
+            options.method,
+        ];
+    const appendStatus = 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 = 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 = 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 }
+                        : {}),
+            };
+            if (!identifier.agentId || !identifier.channelName) {
+                throw new Error("Identifier must include agentId and channelName");
+            }
+            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, {
+            data,
+            fallbackStatus: { code: "success" },
+        }),
+        onError: (error, variables) => settleCommand(variables.commandId, {
+            error,
+            fallbackStatus: toErrorStatus(error),
+        }),
+    });
+    const getCommandState = useCallback((commandId) => commandStatuses[commandId], [commandStatuses]);
+    const getStatus = useCallback((commandId) => getCommandState(commandId)?.current, [getCommandState]);
+    const getHistory = useCallback((commandId) => getCommandState(commandId)?.history ?? [], [getCommandState]);
+    const currentStatus = 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/esm/react/useTurnCredentials.d.ts

@@ -0,0 +1,12 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { TurnCredential } from "../types/common.js";
+import type { TurnTokenRequest } from "../types/openapi.js";
+/**
+ * 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/esm/react/useTurnCredentials.js

@@ -0,0 +1,22 @@
+import { useQuery } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+/**
+ * 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 function useTurnCredentials(request, options) {
+    const client = useDooverClient();
+    return 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/esm/react/useUpdateAggregate.d.ts

@@ -0,0 +1,27 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { AggregateMutationParams } from "../apis/aggregates-api.js";
+import type { Aggregate } from "../types/common.js";
+import type { ChannelIdentifier } from "../types/viewer.js";
+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;
+    /**
+     * Restrict the write to these source ids on a `MultiplexClient`. Ignored
+     * for a plain `DooverClient` or `LocalAgentClient`. Also scopes the
+     * react-query cache invalidation to the matching source-dimensioned key.
+     */
+    sources?: string[];
+}
+/**
+ * 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<TData extends object = object>(identifier: ChannelIdentifier, options?: UseUpdateAggregateOptions): UseMutationResult<Aggregate<TData>, Error, TData>;

package/dist/esm/react/useUpdateAggregate.js

@@ -0,0 +1,39 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+import { channelAggregateQueryKey } from "./useChannelAggregate.js";
+/**
+ * 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 function useUpdateAggregate(identifier, options) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    const replace = options?.replace ?? false;
+    const params = options?.params;
+    const sources = options?.sources;
+    return useMutation({
+        mutationFn: (data) => {
+            if (!identifier.agentId || !identifier.channelName) {
+                return Promise.reject(new Error("Identifier must include agentId and channelName"));
+            }
+            const id = { agentId: identifier.agentId, channelName: identifier.channelName };
+            const body = data;
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `never` since the TypeScript overloads don't declare it.
+            const sourcesArg = sources ? { sources } : undefined;
+            if (replace) {
+                return (sourcesArg
+                    ? client.aggregates.putAggregate(id, body, params, sourcesArg)
+                    : client.aggregates.putAggregate(id, body, params));
+            }
+            return (sourcesArg
+                ? client.aggregates.patchAggregate(id, body, params, sourcesArg)
+                : client.aggregates.patchAggregate(id, body, params));
+        },
+        onSuccess: (aggregate) => {
+            queryClient.setQueryData(channelAggregateQueryKey(identifier.agentId, identifier.channelName, sources), aggregate);
+        },
+    });
+}

package/dist/esm/react/useUpdateMessage.d.ts

@@ -0,0 +1,38 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { MessageBody, MessageMutationParams } from "../apis/messages-api.js";
+import type { ChannelIdentifier } from "../types/viewer.js";
+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 {
+    /**
+     * Restrict the write to these source ids on a `MultiplexClient`. Ignored
+     * for a plain `DooverClient` or `LocalAgentClient`.
+     */
+    sources?: string[];
+}
+export interface UpdateMessageVariables<TBody extends MessageBody = MessageBody> {
+    messageId: string;
+    body: TBody;
+    /**
+     * 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<TBody extends MessageBody = MessageBody>(identifier: ChannelIdentifier, options?: UseUpdateMessageOptions): UseMutationResult<unknown, Error, UpdateMessageVariables<TBody>>;

package/dist/esm/react/useUpdateMessage.js

@@ -0,0 +1,36 @@
+import { useMutation } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+/**
+ * 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 function useUpdateMessage(identifier, options) {
+    const client = useDooverClient();
+    const defaultReplace = options?.replace ?? false;
+    const defaultParams = options?.params;
+    const sources = options?.sources;
+    return 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;
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `never` since the TypeScript overloads don't declare it.
+            const sourcesArg = sources ? { sources } : undefined;
+            if (replace) {
+                return sourcesArg
+                    ? client.messages.putMessage(identifier.agentId, identifier.channelName, messageId, body, params, sourcesArg)
+                    : client.messages.putMessage(identifier.agentId, identifier.channelName, messageId, body, params);
+            }
+            return sourcesArg
+                ? client.messages.patchMessage(identifier.agentId, identifier.channelName, messageId, body, params, sourcesArg)
+                : client.messages.patchMessage(identifier.agentId, identifier.channelName, messageId, body, params);
+        },
+    });
+}