doover-js 0.2.0 → 0.4.0

package/dist/react/index.d.ts

@@ -6,6 +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 { useAgentChannel } from "./useAgentChannel";
 export { useSendMessage } from "./useSendMessage";
 export { useUpdateAggregate } from "./useUpdateAggregate";

package/dist/react/useAgentChannel.d.ts

@@ -4,4 +4,4 @@ import type { Aggregate } from "../types/common";
  * 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 extends Aggregate["data"] = Aggregate["data"]>(agentId: string | undefined, channelName: string): import("@tanstack/react-query").UseQueryResult<Aggregate<TData> | undefined>;
+export declare function useAgentChannel<TData = Aggregate["data"]>(agentId: string | undefined, channelName: string): import("./useChannelAggregate").UseChannelAggregateResult<TData>;

package/dist/react/useChannelAggregate.d.ts

@@ -2,12 +2,32 @@ import { type UseQueryResult } from "@tanstack/react-query";
 import type { Aggregate } from "../types/common";
 import type { ChannelIdentifier } from "../types/viewer";
 export declare function channelAggregateQueryKey(agentId: string | undefined, channelName: string | undefined): readonly ["doover", "agent", string | undefined, "channel", string | undefined];
+/**
+ * Shape returned by `useChannelAggregate`. Shadows the react-query
+ * `data` field with the unwrapped aggregate payload (`TData`) so the
+ * common call-site pattern — `const { data } = useChannelAggregate(…)` —
+ * just works without a secondary `.data` access or cast. The
+ * `attachments` and `last_updated` slots are hoisted alongside for the
+ * same reason; everything else (isLoading, isError, refetch, status,
+ * …) passes through from react-query unchanged.
+ */
+export interface UseChannelAggregateResult<TData> extends Omit<UseQueryResult<Aggregate<TData> | undefined>, "data"> {
+    /** The aggregate payload. `undefined` until the first fetch lands. */
+    data: TData | undefined;
+    /** Attachments (files/blobs) on the aggregate. */
+    attachments: Aggregate["attachments"] | undefined;
+    /** Server timestamp (epoch seconds) of the last aggregate update. */
+    last_updated: number | null | undefined;
+}
 /**
  * Fetch a channel's aggregate and keep it live via the gateway. Incoming
  * `channelSync` and `aggregateUpdate` events patch the react-query cache
  * under `channelAggregateQueryKey(agentId, channelName)`.
  *
  * Typed on `TData` — the shape of `aggregate.data`. Defaults to the generic
- * `Record<string, JSONValue>` used by `Aggregate`.
+ * `Record<string, JSONValue>` used by `Aggregate`. No `extends` constraint
+ * on the generic: typed aggregate interfaces (e.g. `{ enabled: boolean }`)
+ * 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 extends Aggregate["data"] = Aggregate["data"]>(identifier: ChannelIdentifier): UseQueryResult<Aggregate<TData> | undefined>;
+export declare function useChannelAggregate<TData = Aggregate["data"]>(identifier: ChannelIdentifier): UseChannelAggregateResult<TData>;

package/dist/react/useChannelAggregate.js

@@ -15,7 +15,10 @@ function channelAggregateQueryKey(agentId, channelName) {
  * under `channelAggregateQueryKey(agentId, channelName)`.
  *
  * Typed on `TData` — the shape of `aggregate.data`. Defaults to the generic
- * `Record<string, JSONValue>` used by `Aggregate`.
+ * `Record<string, JSONValue>` used by `Aggregate`. No `extends` constraint
+ * on the generic: typed aggregate interfaces (e.g. `{ enabled: boolean }`)
+ * 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) {
     const client = (0, context_1.useDooverClient)();
@@ -29,10 +32,18 @@ function useChannelAggregate(identifier) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [queryClient, agentId, channelName]);
     (0, useChannelSubscription_1.useChannelSubscription)(identifier, { onAggregate });
-    return (0, react_query_1.useQuery)({
+    const query = (0, react_query_1.useQuery)({
         queryKey: key,
         enabled: !!agentId && !!channelName,
         staleTime: Infinity,
         queryFn: () => client.viewer.getAggregate(identifier),
     });
+    const aggregate = query.data;
+    const { data: _ignored, ...rest } = query;
+    return {
+        ...rest,
+        data: aggregate?.data,
+        attachments: aggregate?.attachments,
+        last_updated: aggregate?.last_updated,
+    };
 }

package/dist/react/useChannelMessages.d.ts

@@ -6,6 +6,19 @@ export interface UseChannelMessagesOptions {
     limit?: number;
     /** If false, skip subscribing for live message-create updates. Defaults true. */
     liveUpdates?: boolean;
+    /**
+     * Restrict the returned messages to those whose payload contains any of
+     * these top-level field names. Passed through as `field_name` on the
+     * REST call.
+     */
+    fields?: string[];
+    /**
+     * Optional first-page `before` cursor (snowflake id). Defaults to
+     * unset, which returns the latest messages. Use this when you need to
+     * guard against client-side clock skew (seed with a slightly-future
+     * snowflake so server-stamped messages don't get missed).
+     */
+    initialBefore?: string;
 }
 type Page<TData> = MessageStructure<TData>[];
 export interface UseChannelMessagesResult<TData> extends Omit<UseInfiniteQueryResult<InfiniteData<Page<TData>>>, "data"> {

package/dist/react/useChannelMessages.js

@@ -20,6 +20,8 @@ function useChannelMessages(identifier, options) {
     const { agentId, channelName } = identifier;
     const limit = options?.limit;
     const liveUpdates = options?.liveUpdates ?? true;
+    const fields = options?.fields;
+    const initialBefore = options?.initialBefore;
     const key = channelMessagesQueryKey(agentId, channelName);
     const onMessage = (0, react_1.useCallback)((message) => {
         queryClient.setQueryData(key, (current) => {
@@ -41,12 +43,13 @@ function useChannelMessages(identifier, options) {
         queryKey: key,
         enabled: !!agentId && !!channelName,
         staleTime: Infinity,
-        initialPageParam: undefined,
+        initialPageParam: initialBefore,
         getNextPageParam: (lastPage) => lastPage && lastPage.length > 0 ? lastPage[0]?.id : undefined,
         queryFn: async ({ pageParam }) => {
             const page = await client.viewer.getMessages(identifier, {
                 ...(typeof pageParam === "string" ? { before: pageParam } : {}),
                 ...(limit !== undefined ? { limit } : {}),
+                ...(fields && fields.length > 0 ? { field_name: fields } : {}),
             });
             return (page ?? []);
         },

package/dist/react/useMultiAgentAggregates.js

@@ -5,6 +5,7 @@ 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",
@@ -28,7 +29,18 @@ function useMultiAgentAggregates(channelName, agentIds, options) {
         queryKey: key,
         enabled: agentIds.length > 0,
         staleTime: Infinity,
-        queryFn: () => client.agents.getMultiAgentAggregates(channelName, { agent_id: agentIds }),
+        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) => {
@@ -44,6 +56,9 @@ function useMultiAgentAggregates(channelName, agentIds, options) {
                 : 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(",")]);

package/dist/react/useMultiAgentChannelMessages.d.ts

@@ -5,6 +5,13 @@ 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[];

package/dist/react/useMultiAgentChannelMessages.js

@@ -19,6 +19,8 @@ function useMultiAgentChannelMessages(channelName, agentIds, options) {
     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) => {
@@ -62,13 +64,14 @@ function useMultiAgentChannelMessages(channelName, agentIds, options) {
         queryKey: key,
         enabled: agentIds.length > 0,
         staleTime: Infinity,
-        initialPageParam: undefined,
+        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;
         },

package/dist/react/useUpdateAggregate.d.ts

@@ -1,9 +1,16 @@
 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

package/dist/react/useUpdateAggregate.js

@@ -14,10 +14,11 @@ 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)
-            : client.viewer.updateAggregate(identifier, data),
+            ? 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

@@ -1,17 +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 UseUpdateMessageOptions {
-    /** If true, use PUT (replace) instead of PATCH (merge). Default PATCH. */
+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.
+ * 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

@@ -5,17 +5,23 @@ 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.
+ * 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 replace = options?.replace ?? false;
-    const params = options?.params;
+    const defaultReplace = options?.replace ?? false;
+    const defaultParams = options?.params;
     return (0, react_query_1.useMutation)({
-        mutationFn: ({ messageId, body }) => {
+        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/react.test.js

@@ -131,7 +131,8 @@ function wrapper(client) {
             wrapper: Wrapper,
         });
         await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.isSuccess).to.equal(true));
-        (0, chai_1.expect)(result.current.data?.data).to.deep.equal({ x: 1 });
+        (0, chai_1.expect)(result.current.data).to.deep.equal({ x: 1 });
+        (0, chai_1.expect)(result.current.attachments).to.deep.equal([]);
         // Drive a live aggregate update.
         await (0, react_1.act)(async () => {
             const ws = helpers_1.MockWebSocket.instances[0];
@@ -154,7 +155,7 @@ function wrapper(client) {
                 },
             });
         });
-        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.data?.data).to.deep.equal({ x: 2 }));
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.data).to.deep.equal({ x: 2 }));
     });
     (0, mocha_1.it)("useSendMessage posts via MessagesApi", async () => {
         const fetchMock = (0, helpers_1.createFetchMock)((url) => {

package/dist/viewer/doover-data-provider.d.ts

@@ -1,5 +1,5 @@
 import { AgentsApi } from "../apis/agents-api";
-import { AggregatesApi } from "../apis/aggregates-api";
+import { AggregatesApi, type AggregateMutationParams } from "../apis/aggregates-api";
 import { ChannelsApi } from "../apis/channels-api";
 import { ConnectionsApi } from "../apis/connections-api";
 import { MessagesApi, type ListMessagesParams } from "../apis/messages-api";
@@ -68,8 +68,8 @@ export declare class DooverDataProvider implements ChannelsDataProvider<ChannelI
     sendRPC<TRequest = object, TResponse = object, TPending = undefined>(identifier: ChannelIdentifier, rpcRequest: RpcRequest<TRequest>, options?: {
         onStatus?: (status: RpcStatus<TPending>) => void;
     }): Promise<TResponse>;
-    updateAggregate(identifier: ChannelIdentifier, message: object): Promise<Aggregate>;
-    putAggregate(identifier: ChannelIdentifier, message: object): Promise<Aggregate>;
+    updateAggregate(identifier: ChannelIdentifier, message: object, params?: AggregateMutationParams): Promise<Aggregate>;
+    putAggregate(identifier: ChannelIdentifier, message: object, params?: AggregateMutationParams): Promise<Aggregate>;
     getChannelSubscriptions(identifier: ChannelIdentifier): Promise<SubscriptionDetails[]>;
     getAgentConnections(identifier: ChannelIdentifier): Promise<ConnectionDetails[]>;
     getIdentifierFromPath(path: string, searchParams: URLSearchParams): {

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

@@ -228,13 +228,13 @@ class DooverDataProvider {
             });
         });
     }
-    updateAggregate(identifier, message) {
+    updateAggregate(identifier, message, params) {
         const validated = this.requireChannel(identifier);
-        return this.aggregatesApi.patchAggregate(validated.agentId, validated.channelName, message);
+        return this.aggregatesApi.patchAggregate(validated.agentId, validated.channelName, message, params);
     }
-    putAggregate(identifier, message) {
+    putAggregate(identifier, message, params) {
         const validated = this.requireChannel(identifier);
-        return this.aggregatesApi.putAggregate(validated.agentId, validated.channelName, message);
+        return this.aggregatesApi.putAggregate(validated.agentId, validated.channelName, message, params);
     }
     getChannelSubscriptions(identifier) {
         const validated = this.requireChannel(identifier);

package/package.json

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