doover-js 0.1.2 → 0.2.0

package/dist/node/config-manager.js

@@ -0,0 +1,177 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigManager = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const auth_profile_1 = require("../auth/auth-profile");
+const errors_1 = require("../auth/errors");
+/**
+ * File-backed profile store compatible with pydoover's config format.
+ *
+ * Reads `~/.doover/config` (or a custom path) synchronously on construction,
+ * matching Python's eager-read model.
+ *
+ * Behaviour:
+ * - Doover2 `[profile=...]` blocks are parsed into `AuthProfile` entries.
+ * - Legacy Doover1 `[...]` blocks and unrecognised raw blocks are preserved
+ *   verbatim in their original order and written back unchanged.
+ * - `write()` creates the `~/.doover` directory if missing.
+ */
+class ConfigManager {
+    constructor(configPath) {
+        this.currentProfile = null;
+        this.current = null;
+        /** Parsed Doover2 profiles keyed by profile name. */
+        this.profiles = new Map();
+        /**
+         * Ordered list of *blocks* in the file as they were originally read. Each
+         * entry is either a `{ type: "managed"; name: string }` reference into
+         * `this.profiles`, or a `{ type: "raw"; text: string }` blob that is
+         * preserved verbatim.
+         */
+        this.blocks = [];
+        this.configPath =
+            configPath ?? path.join(os.homedir(), ".doover", "config");
+        this.read();
+    }
+    // ------------------------------------------------------------------
+    // AuthProfileStore interface
+    // ------------------------------------------------------------------
+    get(profileName) {
+        return this.profiles.get(profileName);
+    }
+    create(entry) {
+        const existing = this.profiles.has(entry.profile);
+        this.profiles.set(entry.profile, entry);
+        if (!existing) {
+            this.blocks.push({ type: "managed", name: entry.profile });
+        }
+    }
+    delete(profileName) {
+        this.profiles.delete(profileName);
+        this.blocks = this.blocks.filter((b) => !(b.type === "managed" && b.name === profileName));
+        if (this.currentProfile === profileName) {
+            this.currentProfile = null;
+            this.current = null;
+        }
+    }
+    write() {
+        const dir = path.dirname(this.configPath);
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        catch (err) {
+            throw new errors_1.DooverAuthError(`Failed to create config directory '${dir}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const sections = [];
+        for (const block of this.blocks) {
+            if (block.type === "raw") {
+                sections.push(block.text);
+            }
+            else {
+                const profile = this.profiles.get(block.name);
+                if (profile) {
+                    sections.push(profile.dumpBlock());
+                }
+            }
+        }
+        try {
+            fs.writeFileSync(this.configPath, sections.join("\n\n") + "\n", "utf-8");
+        }
+        catch (err) {
+            throw new errors_1.DooverAuthError(`Failed to write config file '${this.configPath}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ------------------------------------------------------------------
+    // Internal parsing
+    // ------------------------------------------------------------------
+    read() {
+        let content;
+        try {
+            content = fs.readFileSync(this.configPath, "utf-8");
+        }
+        catch {
+            // File does not exist — start empty.
+            return;
+        }
+        this.profiles.clear();
+        this.blocks = [];
+        const lines = content.split(/\r?\n/);
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i];
+            const profileMatch = line.match(/^\[profile=(.+)\]$/);
+            if (profileMatch) {
+                // Doover2 managed block
+                const profileName = profileMatch[1];
+                const bodyLines = [];
+                i++;
+                while (i < lines.length && !lines[i].startsWith("[")) {
+                    bodyLines.push(lines[i]);
+                    i++;
+                }
+                const profile = auth_profile_1.AuthProfile.parse(profileName, bodyLines);
+                this.profiles.set(profileName, profile);
+                this.blocks.push({ type: "managed", name: profileName });
+            }
+            else if (line.match(/^\[.+\]$/) && !line.match(/^\[profile=/)) {
+                // Legacy Doover1 block — preserve verbatim.
+                const rawLines = [line];
+                i++;
+                while (i < lines.length && !lines[i].startsWith("[")) {
+                    rawLines.push(lines[i]);
+                    i++;
+                }
+                this.blocks.push({ type: "raw", text: rawLines.join("\n").trimEnd() });
+            }
+            else {
+                // Stray line outside any block — preserve as raw.
+                if (line.trim()) {
+                    this.blocks.push({ type: "raw", text: line });
+                }
+                i++;
+            }
+        }
+        // Set default current profile to the first managed profile.
+        if (this.profiles.size > 0) {
+            const firstName = this.profiles.keys().next().value;
+            this.currentProfile = firstName;
+            this.current = this.profiles.get(firstName);
+        }
+    }
+}
+exports.ConfigManager = ConfigManager;

package/dist/node/index.d.ts

@@ -0,0 +1 @@
+export { ConfigManager } from "./config-manager";

package/dist/node/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigManager = void 0;
+var config_manager_1 = require("./config-manager");
+Object.defineProperty(exports, "ConfigManager", { enumerable: true, get: function () { return config_manager_1.ConfigManager; } });

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;