doover-js 0.2.0-alpha.0 → 0.2.0

package/dist/http/rest-client.d.ts

@@ -1,5 +1,6 @@
 import type { AuthConfig } from "../auth/build-auth";
 import type { DooverAuth } from "../auth/doover-auth";
+import type { DooverStatsCollector } from "../client/stats";
 export interface DooverClientConfig extends AuthConfig {
     dataRestUrl: string;
     controlApiUrl: string;
@@ -13,6 +14,12 @@ export interface DooverClientConfig extends AuthConfig {
         url: string;
         headers?: Record<string, string>;
     }) => WebSocket;
+    /**
+     * When true, disables the GatewayClient's browser lifecycle listeners
+     * (visibilitychange, online). Defaults to false — hooks are on by default
+     * in browsers and automatically skipped in non-browser environments.
+     */
+    disableBrowserLifecycleHooks?: boolean;
 }
 export interface RequestOptions {
     baseUrl?: string;
@@ -28,8 +35,12 @@ type QueryParams = Record<string, QueryValue> | object;
 export declare class RestClient {
     readonly config: Required<Pick<DooverClientConfig, "dataRestUrl" | "controlApiUrl" | "dataWssUrl" | "sharing" | "impersonateUserStorageKey">> & Pick<DooverClientConfig, "organisationId" | "fetchImpl" | "webSocketImpl" | "webSocketFactory">;
     readonly auth: DooverAuth | null;
+    private stats;
     constructor(config: DooverClientConfig, auth?: DooverAuth);
+    /** Attach a stats collector. Call with `null` to detach. */
+    setStats(stats: DooverStatsCollector | null): void;
     request<T>(options: RequestOptions): Promise<T>;
+    private doRequest;
     get<T>(path: string, query?: RequestOptions["query"], baseUrl?: string): Promise<T>;
     post<T>(path: string, body?: RequestOptions["body"], query?: RequestOptions["query"], baseUrl?: string): Promise<T>;
     put<T>(path: string, body?: RequestOptions["body"], query?: RequestOptions["query"], baseUrl?: string): Promise<T>;

package/dist/http/rest-client.js

@@ -4,6 +4,7 @@ exports.RestClient = void 0;
 const errors_1 = require("./errors");
 class RestClient {
     constructor(config, auth) {
+        this.stats = null;
         this.config = {
             ...config,
             sharing: config.sharing ?? "internal",
@@ -12,7 +13,23 @@ class RestClient {
         };
         this.auth = auth ?? null;
     }
+    /** Attach a stats collector. Call with `null` to detach. */
+    setStats(stats) {
+        this.stats = stats;
+    }
     async request(options) {
+        const startedAt = this.stats?.recordRestStart() ?? null;
+        try {
+            const payload = await this.doRequest(options);
+            this.stats?.recordRestEnd(startedAt, true);
+            return payload;
+        }
+        catch (err) {
+            this.stats?.recordRestEnd(startedAt, false);
+            throw err;
+        }
+    }
+    async doRequest(options) {
         if (this.auth) {
             await this.auth.ensureReady();
         }

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { DooverClient } from "./client/doover-client";
+export { getDooverClient, peekDooverClient, resetDooverClient, } from "./client/singleton";
+export { DooverStatsCollector } from "./client/stats";
+export type { DooverStatsSnapshot, RestStatsSnapshot, GatewayStatsSnapshot, } from "./client/stats";
 export { AgentsApi } from "./apis/agents-api";
 export { AggregatesApi } from "./apis/aggregates-api";
 export { AlarmsApi } from "./apis/alarms-api";

package/dist/index.js

@@ -1,8 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverClient = void 0;
+exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.DooverClient = void 0;
 var doover_client_1 = require("./client/doover-client");
 Object.defineProperty(exports, "DooverClient", { enumerable: true, get: function () { return doover_client_1.DooverClient; } });
+var singleton_1 = require("./client/singleton");
+Object.defineProperty(exports, "getDooverClient", { enumerable: true, get: function () { return singleton_1.getDooverClient; } });
+Object.defineProperty(exports, "peekDooverClient", { enumerable: true, get: function () { return singleton_1.peekDooverClient; } });
+Object.defineProperty(exports, "resetDooverClient", { enumerable: true, get: function () { return singleton_1.resetDooverClient; } });
+var stats_1 = require("./client/stats");
+Object.defineProperty(exports, "DooverStatsCollector", { enumerable: true, get: function () { return stats_1.DooverStatsCollector; } });
 var agents_api_1 = require("./apis/agents-api");
 Object.defineProperty(exports, "AgentsApi", { enumerable: true, get: function () { return agents_api_1.AgentsApi; } });
 var aggregates_api_1 = require("./apis/aggregates-api");

package/dist/react/context.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from "react";
+import { DooverClient } from "../client/doover-client";
+export interface DooverProviderProps {
+    client: DooverClient;
+    children: ReactNode;
+}
+/**
+ * Wraps a React subtree with a `DooverClient` instance so downstream hooks
+ * (`useDooverClient`, `useChannelAggregate`, etc.) can read it from context.
+ *
+ * Pair with a `@tanstack/react-query` `<QueryClientProvider>` in the same tree —
+ * the hooks call `useQueryClient()` internally and will throw without one.
+ */
+export declare function DooverProvider({ client, children }: DooverProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Read the `DooverClient` from context. Throws if called outside a
+ * `<DooverProvider>`.
+ */
+export declare function useDooverClient(): DooverClient;

package/dist/react/context.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DooverProvider = DooverProvider;
+exports.useDooverClient = useDooverClient;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const DooverClientContext = (0, react_1.createContext)(null);
+/**
+ * Wraps a React subtree with a `DooverClient` instance so downstream hooks
+ * (`useDooverClient`, `useChannelAggregate`, etc.) can read it from context.
+ *
+ * Pair with a `@tanstack/react-query` `<QueryClientProvider>` in the same tree —
+ * the hooks call `useQueryClient()` internally and will throw without one.
+ */
+function DooverProvider({ client, children }) {
+    return ((0, jsx_runtime_1.jsx)(DooverClientContext.Provider, { value: client, children: children }));
+}
+/**
+ * Read the `DooverClient` from context. Throws if called outside a
+ * `<DooverProvider>`.
+ */
+function useDooverClient() {
+    const client = (0, react_1.useContext)(DooverClientContext);
+    if (!client) {
+        throw new Error("useDooverClient must be called inside a <DooverProvider>.");
+    }
+    return client;
+}

package/dist/react/index.d.ts

@@ -0,0 +1,24 @@
+export { DooverProvider, useDooverClient } from "./context";
+export type { DooverProviderProps } from "./context";
+export { useConnectionState } from "./useConnectionState";
+export type { ConnectionState, ConnectionStatus } from "./useConnectionState";
+export { useAgentConnections, agentConnectionsQueryKey, } from "./useAgentConnections";
+export { useChannelSubscription, } from "./useChannelSubscription";
+export type { ChannelSubscriptionHandlers } from "./useChannelSubscription";
+export { useChannelAggregate, channelAggregateQueryKey, } from "./useChannelAggregate";
+export { useAgentChannel } from "./useAgentChannel";
+export { useSendMessage } from "./useSendMessage";
+export { useUpdateAggregate } from "./useUpdateAggregate";
+export type { UseUpdateAggregateOptions } from "./useUpdateAggregate";
+export { useUpdateMessage } from "./useUpdateMessage";
+export type { UpdateMessageVariables, UseUpdateMessageOptions, } from "./useUpdateMessage";
+export { useChannelMessages, channelMessagesQueryKey, } from "./useChannelMessages";
+export type { UseChannelMessagesOptions, UseChannelMessagesResult, } from "./useChannelMessages";
+export { useSendRpc } from "./useSendRpc";
+export type { RpcCommandId, RpcStatusEvent, SendRpcVariables, UseSendRpcOptions, UseSendRpcResult, } from "./useSendRpc";
+export { useMultiAgentAggregates, multiAgentAggregatesQueryKey, } from "./useMultiAgentAggregates";
+export type { UseMultiAgentAggregatesOptions, UseMultiAgentAggregatesResult, } from "./useMultiAgentAggregates";
+export { useMultiAgentChannelMessages, multiAgentChannelMessagesQueryKey, } from "./useMultiAgentChannelMessages";
+export type { UseMultiAgentChannelMessagesOptions, UseMultiAgentChannelMessagesResult, } from "./useMultiAgentChannelMessages";
+export { useTurnCredentials } from "./useTurnCredentials";
+export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient";

package/dist/react/index.js

@@ -0,0 +1,40 @@
+"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;
+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; } });
+var useConnectionState_1 = require("./useConnectionState");
+Object.defineProperty(exports, "useConnectionState", { enumerable: true, get: function () { return useConnectionState_1.useConnectionState; } });
+var useAgentConnections_1 = require("./useAgentConnections");
+Object.defineProperty(exports, "useAgentConnections", { enumerable: true, get: function () { return useAgentConnections_1.useAgentConnections; } });
+Object.defineProperty(exports, "agentConnectionsQueryKey", { enumerable: true, get: function () { return useAgentConnections_1.agentConnectionsQueryKey; } });
+var useChannelSubscription_1 = require("./useChannelSubscription");
+Object.defineProperty(exports, "useChannelSubscription", { enumerable: true, get: function () { return useChannelSubscription_1.useChannelSubscription; } });
+var useChannelAggregate_1 = require("./useChannelAggregate");
+Object.defineProperty(exports, "useChannelAggregate", { enumerable: true, get: function () { return useChannelAggregate_1.useChannelAggregate; } });
+Object.defineProperty(exports, "channelAggregateQueryKey", { enumerable: true, get: function () { return useChannelAggregate_1.channelAggregateQueryKey; } });
+var useAgentChannel_1 = require("./useAgentChannel");
+Object.defineProperty(exports, "useAgentChannel", { enumerable: true, get: function () { return useAgentChannel_1.useAgentChannel; } });
+var useSendMessage_1 = require("./useSendMessage");
+Object.defineProperty(exports, "useSendMessage", { enumerable: true, get: function () { return useSendMessage_1.useSendMessage; } });
+var useUpdateAggregate_1 = require("./useUpdateAggregate");
+Object.defineProperty(exports, "useUpdateAggregate", { enumerable: true, get: function () { return useUpdateAggregate_1.useUpdateAggregate; } });
+var useUpdateMessage_1 = require("./useUpdateMessage");
+Object.defineProperty(exports, "useUpdateMessage", { enumerable: true, get: function () { return useUpdateMessage_1.useUpdateMessage; } });
+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 useSendRpc_1 = require("./useSendRpc");
+Object.defineProperty(exports, "useSendRpc", { enumerable: true, get: function () { return useSendRpc_1.useSendRpc; } });
+var useMultiAgentAggregates_1 = require("./useMultiAgentAggregates");
+Object.defineProperty(exports, "useMultiAgentAggregates", { enumerable: true, get: function () { return useMultiAgentAggregates_1.useMultiAgentAggregates; } });
+Object.defineProperty(exports, "multiAgentAggregatesQueryKey", { enumerable: true, get: function () { return useMultiAgentAggregates_1.multiAgentAggregatesQueryKey; } });
+var useMultiAgentChannelMessages_1 = require("./useMultiAgentChannelMessages");
+Object.defineProperty(exports, "useMultiAgentChannelMessages", { enumerable: true, get: function () { return useMultiAgentChannelMessages_1.useMultiAgentChannelMessages; } });
+Object.defineProperty(exports, "multiAgentChannelMessagesQueryKey", { enumerable: true, get: function () { return useMultiAgentChannelMessages_1.multiAgentChannelMessagesQueryKey; } });
+var useTurnCredentials_1 = require("./useTurnCredentials");
+Object.defineProperty(exports, "useTurnCredentials", { enumerable: true, get: function () { return useTurnCredentials_1.useTurnCredentials; } });
+var sharedQueryClient_1 = require("./sharedQueryClient");
+Object.defineProperty(exports, "getSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_1.getSharedQueryClient; } });
+Object.defineProperty(exports, "resetSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_1.resetSharedQueryClient; } });

package/dist/react/sharedQueryClient.d.ts

@@ -0,0 +1,21 @@
+import { QueryClient, type QueryClientConfig } from "@tanstack/react-query";
+/**
+ * Get a process-wide `QueryClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_query_client__` so that every app + remote
+ * in a module-federation setup ends up with the same `QueryClient` — and
+ * therefore the same cache — even if they each load their own copy of the
+ * react-query library. The first caller's `config` wins.
+ *
+ * Wrap your tree once at the app root:
+ *
+ * ```tsx
+ * import { QueryClientProvider } from "@tanstack/react-query";
+ * import { getSharedQueryClient } from "doover-js/react";
+ *
+ * <QueryClientProvider client={getSharedQueryClient()}>…</QueryClientProvider>
+ * ```
+ */
+export declare function getSharedQueryClient(config?: QueryClientConfig): QueryClient;
+/** Test-only: clear the shared `QueryClient`. */
+export declare function resetSharedQueryClient(): void;

package/dist/react/sharedQueryClient.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSharedQueryClient = getSharedQueryClient;
+exports.resetSharedQueryClient = resetSharedQueryClient;
+const react_query_1 = require("@tanstack/react-query");
+const GLOBAL_KEY = "__doover_js_query_client__";
+function globalBag() {
+    return globalThis;
+}
+/**
+ * Get a process-wide `QueryClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_query_client__` so that every app + remote
+ * in a module-federation setup ends up with the same `QueryClient` — and
+ * therefore the same cache — even if they each load their own copy of the
+ * react-query library. The first caller's `config` wins.
+ *
+ * Wrap your tree once at the app root:
+ *
+ * ```tsx
+ * import { QueryClientProvider } from "@tanstack/react-query";
+ * import { getSharedQueryClient } from "doover-js/react";
+ *
+ * <QueryClientProvider client={getSharedQueryClient()}>…</QueryClientProvider>
+ * ```
+ */
+function getSharedQueryClient(config) {
+    const bag = globalBag();
+    const existing = bag[GLOBAL_KEY];
+    if (existing)
+        return existing;
+    const client = new react_query_1.QueryClient(config);
+    bag[GLOBAL_KEY] = client;
+    return client;
+}
+/** Test-only: clear the shared `QueryClient`. */
+function resetSharedQueryClient() {
+    delete globalBag()[GLOBAL_KEY];
+}

package/dist/react/useAgentChannel.d.ts

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

package/dist/react/useAgentChannel.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAgentChannel = useAgentChannel;
+const useChannelAggregate_1 = require("./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`.
+ */
+function useAgentChannel(agentId, channelName) {
+    return (0, useChannelAggregate_1.useChannelAggregate)({ agentId, channelName });
+}

package/dist/react/useAgentConnections.d.ts

@@ -0,0 +1,8 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { ConnectionDetails } from "../types/common";
+export declare function agentConnectionsQueryKey(agentId: string | undefined): readonly ["doover", "agent", string | undefined, "connections"];
+/**
+ * Fetch the list of active WSS connections for an agent. Query key:
+ * `["doover", "agent", agentId, "connections"]`.
+ */
+export declare function useAgentConnections(agentId: string | undefined): UseQueryResult<ConnectionDetails[]>;

package/dist/react/useAgentConnections.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentConnectionsQueryKey = agentConnectionsQueryKey;
+exports.useAgentConnections = useAgentConnections;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+function agentConnectionsQueryKey(agentId) {
+    return ["doover", "agent", agentId, "connections"];
+}
+/**
+ * Fetch the list of active WSS connections for an agent. Query key:
+ * `["doover", "agent", agentId, "connections"]`.
+ */
+function useAgentConnections(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useQuery)({
+        queryKey: agentConnectionsQueryKey(agentId),
+        enabled: !!agentId,
+        staleTime: 30000,
+        queryFn: () => agentId
+            ? client.connections.getAgentConnections(agentId)
+            : Promise.resolve([]),
+    });
+}

package/dist/react/useChannelAggregate.d.ts

@@ -0,0 +1,13 @@
+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];
+/**
+ * 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`.
+ */
+export declare function useChannelAggregate<TData extends Aggregate["data"] = Aggregate["data"]>(identifier: ChannelIdentifier): UseQueryResult<Aggregate<TData> | undefined>;

package/dist/react/useChannelAggregate.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.channelAggregateQueryKey = channelAggregateQueryKey;
+exports.useChannelAggregate = useChannelAggregate;
+const react_1 = require("react");
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+const useChannelSubscription_1 = require("./useChannelSubscription");
+function channelAggregateQueryKey(agentId, channelName) {
+    return ["doover", "agent", agentId, "channel", channelName];
+}
+/**
+ * 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`.
+ */
+function useChannelAggregate(identifier) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { agentId, channelName } = identifier;
+    const key = channelAggregateQueryKey(agentId, channelName);
+    const onAggregate = (0, react_1.useCallback)((aggregate) => {
+        queryClient.setQueryData(key, aggregate);
+    }, 
+    // The key array is structurally stable per (agentId, channelName).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName]);
+    (0, useChannelSubscription_1.useChannelSubscription)(identifier, { onAggregate });
+    return (0, react_query_1.useQuery)({
+        queryKey: key,
+        enabled: !!agentId && !!channelName,
+        staleTime: Infinity,
+        queryFn: () => client.viewer.getAggregate(identifier),
+    });
+}

package/dist/react/useChannelMessages.d.ts

@@ -0,0 +1,23 @@
+import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-query";
+import type { MessageStructure } from "../types/common";
+import type { ChannelIdentifier } from "../types/viewer";
+export declare function channelMessagesQueryKey(agentId: string | undefined, channelName: string | undefined): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages"];
+export interface UseChannelMessagesOptions {
+    limit?: number;
+    /** If false, skip subscribing for live message-create updates. Defaults true. */
+    liveUpdates?: boolean;
+}
+type Page<TData> = MessageStructure<TData>[];
+export interface UseChannelMessagesResult<TData> extends Omit<UseInfiniteQueryResult<InfiniteData<Page<TData>>>, "data"> {
+    /** Flat chronological list across all loaded pages. */
+    messages: MessageStructure<TData>[];
+    /** Raw react-query data (pages). */
+    data: InfiniteData<Page<TData>> | undefined;
+}
+/**
+ * Paginated infinite query over `DooverDataProvider.getMessages`, with live
+ * `messageCreate` pushes prepended/appended to the newest page. The "next"
+ * page fetches older messages (cursor = oldest-loaded message id).
+ */
+export declare function useChannelMessages<TData = unknown>(identifier: ChannelIdentifier, options?: UseChannelMessagesOptions): UseChannelMessagesResult<TData>;
+export {};

package/dist/react/useChannelMessages.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.channelMessagesQueryKey = channelMessagesQueryKey;
+exports.useChannelMessages = useChannelMessages;
+const react_1 = require("react");
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+const useChannelSubscription_1 = require("./useChannelSubscription");
+function channelMessagesQueryKey(agentId, channelName) {
+    return ["doover", "agent", agentId, "channel", channelName, "messages"];
+}
+/**
+ * Paginated infinite query over `DooverDataProvider.getMessages`, with live
+ * `messageCreate` pushes prepended/appended to the newest page. The "next"
+ * page fetches older messages (cursor = oldest-loaded message id).
+ */
+function useChannelMessages(identifier, options) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { agentId, channelName } = identifier;
+    const limit = options?.limit;
+    const liveUpdates = options?.liveUpdates ?? true;
+    const key = channelMessagesQueryKey(agentId, channelName);
+    const onMessage = (0, react_1.useCallback)((message) => {
+        queryClient.setQueryData(key, (current) => {
+            if (!current)
+                return current;
+            const typed = message;
+            // Newest page is index 0 — prepend there.
+            const [firstPage, ...rest] = current.pages;
+            return {
+                ...current,
+                pages: [[...(firstPage ?? []), typed], ...rest],
+            };
+        });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName]);
+    (0, useChannelSubscription_1.useChannelSubscription)(liveUpdates ? identifier : undefined, { onMessage });
+    const query = (0, react_query_1.useInfiniteQuery)({
+        queryKey: key,
+        enabled: !!agentId && !!channelName,
+        staleTime: Infinity,
+        initialPageParam: undefined,
+        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 } : {}),
+            });
+            return (page ?? []);
+        },
+    });
+    const messages = (0, react_1.useMemo)(() => (query.data?.pages ?? []).flat(), [query.data]);
+    return { ...query, messages };
+}

package/dist/react/useChannelSubscription.d.ts

@@ -0,0 +1,16 @@
+import type { Aggregate, MessageStructure } from "../types/common";
+import type { ChannelIdentifier } from "../types/viewer";
+export interface ChannelSubscriptionHandlers {
+    onMessage?: (message: MessageStructure) => void;
+    onMessageUpdate?: (message: MessageStructure) => void;
+    onAggregate?: (aggregate: Aggregate) => void;
+}
+/**
+ * Attach live-update handlers to a channel for the lifetime of the host
+ * component. Wraps `DooverDataProvider.subscribeToChannel` with ref-counted
+ * subscribe/unsubscribe and handler refs so changes to the handler closures
+ * don't re-trigger the underlying subscribe.
+ *
+ * Passing `undefined` (or an identifier without both fields) is a no-op.
+ */
+export declare function useChannelSubscription(identifier: ChannelIdentifier | undefined, handlers: ChannelSubscriptionHandlers): void;

package/dist/react/useChannelSubscription.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useChannelSubscription = useChannelSubscription;
+const react_1 = require("react");
+const context_1 = require("./context");
+/**
+ * Attach live-update handlers to a channel for the lifetime of the host
+ * component. Wraps `DooverDataProvider.subscribeToChannel` with ref-counted
+ * subscribe/unsubscribe and handler refs so changes to the handler closures
+ * don't re-trigger the underlying subscribe.
+ *
+ * Passing `undefined` (or an identifier without both fields) is a no-op.
+ */
+function useChannelSubscription(identifier, handlers) {
+    const client = (0, context_1.useDooverClient)();
+    const handlersRef = (0, react_1.useRef)(handlers);
+    handlersRef.current = handlers;
+    (0, react_1.useEffect)(() => {
+        if (!identifier?.agentId || !identifier?.channelName)
+            return;
+        const messageCallback = (_id, message) => {
+            handlersRef.current.onMessage?.(message);
+        };
+        const aggregateCallback = (_id, aggregate) => {
+            handlersRef.current.onAggregate?.(aggregate);
+        };
+        const messageUpdateCallback = (_id, message) => {
+            handlersRef.current.onMessageUpdate?.(message);
+        };
+        void client.viewer.subscribeToChannel(identifier, messageCallback, aggregateCallback, messageUpdateCallback);
+        return () => {
+            client.viewer
+                .unsubscribeFromChannel(identifier, messageCallback)
+                .catch(() => {
+                // Already unsubscribed — race between strict-mode double-effect
+                // and async subscribe is harmless.
+            });
+        };
+        // Identifier fields are the real deps; we intentionally leave `handlers`
+        // out because it's read through handlersRef.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, identifier?.agentId, identifier?.channelName]);
+}

package/dist/react/useConnectionState.d.ts

@@ -0,0 +1,21 @@
+export type ConnectionStatus = "connecting" | "open";
+export interface ConnectionState {
+    /**
+     * `"open"` once the gateway has received a `Ready` frame;
+     * `"connecting"` any time the socket is reconnecting or awaiting Ready.
+     */
+    status: ConnectionStatus;
+    /** Timestamp of the most recent `Ready` frame, or `null` until the first one. */
+    lastOpenedAt: number | null;
+}
+/**
+ * Subscribes to the gateway's connection lifecycle and returns a snapshot
+ * suitable for a connection-indicator UI.
+ *
+ * The gateway doesn't measure application-level latency — liveness is
+ * handled at the WebSocket-protocol layer via ping/pong frames (opcodes
+ * 0x9 / 0xA) which browsers answer automatically but don't expose to JS.
+ * Dead connections surface as the `close` event, which we already handle
+ * via auto-reconnect.
+ */
+export declare function useConnectionState(): ConnectionState;

package/dist/react/useConnectionState.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useConnectionState = useConnectionState;
+const react_1 = require("react");
+const context_1 = require("./context");
+const INITIAL = {
+    status: "connecting",
+    lastOpenedAt: null,
+};
+/**
+ * Subscribes to the gateway's connection lifecycle and returns a snapshot
+ * suitable for a connection-indicator UI.
+ *
+ * The gateway doesn't measure application-level latency — liveness is
+ * handled at the WebSocket-protocol layer via ping/pong frames (opcodes
+ * 0x9 / 0xA) which browsers answer automatically but don't expose to JS.
+ * Dead connections surface as the `close` event, which we already handle
+ * via auto-reconnect.
+ */
+function useConnectionState() {
+    const client = (0, context_1.useDooverClient)();
+    const [state, setState] = (0, react_1.useState)(() => client.gateway.isConnected() && client.gateway.getSession()
+        ? {
+            status: "open",
+            lastOpenedAt: Date.now(),
+        }
+        : INITIAL);
+    (0, react_1.useEffect)(() => {
+        const onReady = () => setState((prev) => ({
+            ...prev,
+            status: "open",
+            lastOpenedAt: Date.now(),
+        }));
+        const onClose = () => setState((prev) => ({ ...prev, status: "connecting" }));
+        client.gateway.on("ready", onReady);
+        client.gateway.on("close", onClose);
+        return () => {
+            client.gateway.off("ready", onReady);
+            client.gateway.off("close", onClose);
+        };
+    }, [client]);
+    return state;
+}

package/dist/react/useMultiAgentAggregates.d.ts

@@ -0,0 +1,22 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Aggregate } from "../types/common";
+import type { AgentAggregate } from "../types/openapi";
+export declare function multiAgentAggregatesQueryKey(channelName: string, agentIds: string[]): readonly ["doover", "channel", string, "aggregates", string];
+export interface UseMultiAgentAggregatesOptions {
+    /** If false, skip per-agent live subscriptions. Defaults true. */
+    liveUpdates?: boolean;
+}
+export interface UseMultiAgentAggregatesResult {
+    /** Keyed by `agent_id` for O(1) lookup. */
+    aggregatesByAgent: Record<string, Aggregate>;
+    query: UseQueryResult<{
+        results: AgentAggregate[];
+        count: number;
+    }>;
+}
+/**
+ * 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.
+ */
+export declare function useMultiAgentAggregates(channelName: string, agentIds: string[], options?: UseMultiAgentAggregatesOptions): UseMultiAgentAggregatesResult;