doover-js 0.11.0 → 0.13.0

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

@@ -0,0 +1,64 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Aggregate } from "../types/common.js";
+import type { ChannelIdentifier } from "../types/viewer.js";
+import { type OfflineStatusSnapshot } from "./useOfflineStatus.js";
+export declare function channelAggregateQueryKey(agentId: string | undefined, channelName: string | undefined, sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "src", string];
+/**
+ * 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 **milliseconds**) of the last aggregate update —
+     * matches the `Date` / `dayjs()` constructor. Use `dayjs(last_updated)`, not
+     * `dayjs.unix(last_updated)` (the latter assumes seconds and lands ~58000
+     * years in the future).
+     */
+    last_updated: number | null | undefined;
+    /** Offline/cache status when the provided client supports offline caching. */
+    offline: OfflineStatusSnapshot;
+}
+export interface UseChannelAggregateOptions {
+    /**
+     * Whether to fetch the initial aggregate over REST on mount.
+     *
+     * Defaults to `true` — the hook does a one-shot HTTP GET to seed the cache
+     * before the gateway WebSocket has connected, so the first paint isn't
+     * empty.
+     *
+     * Set to `false` for purely WS-driven consumers that don't want the REST
+     * round-trip (e.g. when the gateway's upsert-on-subscribe semantics make
+     * the REST call redundant or actively wrong, like channels that don't yet
+     * exist). The cache is then populated only by `ChannelSync` /
+     * `AggregateUpdate` events.
+     */
+    fetchInitial?: boolean;
+    /**
+     * Restrict to these source ids on a `MultiplexClient`. Ignored for a plain
+     * `DooverClient` or `LocalAgentClient`. When set, the query key is
+     * source-dimensioned so data from different source subsets is cached
+     * independently.
+     */
+    sources?: string[];
+}
+/**
+ * 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`. 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 = Aggregate["data"]>(identifier: ChannelIdentifier, options?: UseChannelAggregateOptions): UseChannelAggregateResult<TData>;

package/dist/esm/react/useChannelAggregate.js

@@ -0,0 +1,77 @@
+import { useCallback } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { DooverApiError } from "../http/errors.js";
+import { useDooverClient } from "./context.js";
+import { useChannelSubscription } from "./useChannelSubscription.js";
+import { useOfflineStatus } from "./useOfflineStatus.js";
+export function channelAggregateQueryKey(agentId, channelName, sources) {
+    const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
+    return ["doover", "agent", agentId, "channel", channelName, "src", sourceDim];
+}
+/**
+ * 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`. 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 function useChannelAggregate(identifier, options) {
+    const client = useDooverClient();
+    const offline = useOfflineStatus();
+    const queryClient = useQueryClient();
+    const { agentId, channelName } = identifier;
+    const sources = options?.sources;
+    const key = channelAggregateQueryKey(agentId, channelName, sources);
+    const fetchInitial = options?.fetchInitial ?? true;
+    const onAggregate = useCallback((aggregate) => {
+        queryClient.setQueryData(key, aggregate);
+    }, 
+    // The key array is structurally stable per (agentId, channelName, sourceDim).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName, sources?.join(",")]);
+    useChannelSubscription(identifier, { onAggregate });
+    const query = useQuery({
+        queryKey: key,
+        enabled: fetchInitial && !!agentId && !!channelName,
+        staleTime: Infinity,
+        queryFn: async () => {
+            if (!agentId || !channelName)
+                return undefined;
+            const id = { agentId, channelName };
+            // Pass `{ sources }` as a trailing bag only when set. The TypeScript
+            // overloads don't declare it, so we cast through `never` — the runtime
+            // implementation reads it via `...args: unknown[]`.
+            const sourcesArg = sources ? { sources } : undefined;
+            const channel = sourcesArg
+                ? await client.channels.getChannel(id, sourcesArg)
+                : await client.channels.getChannel(id);
+            if (channel.aggregate)
+                return channel.aggregate;
+            return (sourcesArg
+                ? await client.aggregates.getAggregate(id, sourcesArg)
+                : await client.aggregates.getAggregate(id));
+        },
+        // A 404 means the aggregate doesn't exist — retrying won't change that,
+        // and the caller needs the error promptly to render an empty/"not
+        // installed" state. Fall back to the react-query default (3 retries) for
+        // every other failure.
+        retry: (failureCount, error) => {
+            if (error instanceof DooverApiError && error.status === 404)
+                return false;
+            return failureCount < 3;
+        },
+    });
+    const aggregate = query.data;
+    const { data: _ignored, ...rest } = query;
+    return {
+        ...rest,
+        data: aggregate?.data,
+        attachments: aggregate?.attachments,
+        last_updated: aggregate?.last_updated,
+        offline,
+    };
+}

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

@@ -0,0 +1,45 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { JSONValue, MessageAttachment, MessageStructure } from "../types/common.js";
+import type { ChannelIdentifier } from "../types/viewer.js";
+export declare function channelMessageQueryKey(agentId: string | undefined, channelName: string | undefined, messageId: string | undefined, sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "message", string | undefined, "src", string];
+export interface UseChannelMessageOptions {
+    /** If false, skip subscribing for live message-update events. Defaults true. */
+    liveUpdates?: boolean;
+    /**
+     * Restrict to these source ids on a `MultiplexClient`. Ignored for a plain
+     * `DooverClient` or `LocalAgentClient`. When set, the query key is
+     * source-dimensioned so data from different source subsets is cached
+     * independently.
+     */
+    sources?: string[];
+}
+/**
+ * Shape returned by `useChannelMessage`. Mirrors `UseChannelAggregateResult`:
+ * `data` is unwrapped to the message payload (`message.data`) so the common
+ * `const { data } = useChannelMessage(…)` pattern works without a secondary
+ * access. The full `MessageStructure` and a couple of useful slots
+ * (`attachments`, `timestamp`) are hoisted alongside.
+ */
+export interface UseChannelMessageResult<TData> extends Omit<UseQueryResult<MessageStructure<TData> | undefined>, "data"> {
+    /** Unwrapped message payload (`message.data`). Undefined until first fetch. */
+    data: TData | undefined;
+    /** Full message structure, or undefined until first fetch. */
+    message: MessageStructure<TData> | undefined;
+    attachments: MessageAttachment[] | undefined;
+    /** Server timestamp reported by the message. */
+    timestamp: number | undefined;
+}
+/**
+ * Fetch a single channel message by id and keep it live via gateway
+ * `MessageUpdate` events. Mirrors `useChannelAggregate`'s pattern: REST seeds
+ * the cache, then `onMessageUpdate` patches it whenever the message body is
+ * mutated server-side — handy for watching long-running RPC-style messages
+ * where the receiver writes progress into a `response` field.
+ *
+ * Channel subscriptions deliver every message in the channel, so the
+ * handlers filter to the requested `messageId` before patching the cache.
+ *
+ * Typed on `TData` — the shape of `message.data`. Defaults to `JSONValue` to
+ * match `MessageStructure`.
+ */
+export declare function useChannelMessage<TData = JSONValue>(identifier: ChannelIdentifier, messageId: string | undefined, options?: UseChannelMessageOptions): UseChannelMessageResult<TData>;

package/dist/esm/react/useChannelMessage.js

@@ -0,0 +1,79 @@
+import { useCallback } from "react";
+import { useQuery, useQueryClient, } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+import { useChannelSubscription } from "./useChannelSubscription.js";
+export function channelMessageQueryKey(agentId, channelName, messageId, sources) {
+    const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
+    return [
+        "doover",
+        "agent",
+        agentId,
+        "channel",
+        channelName,
+        "message",
+        messageId,
+        "src",
+        sourceDim,
+    ];
+}
+/**
+ * Fetch a single channel message by id and keep it live via gateway
+ * `MessageUpdate` events. Mirrors `useChannelAggregate`'s pattern: REST seeds
+ * the cache, then `onMessageUpdate` patches it whenever the message body is
+ * mutated server-side — handy for watching long-running RPC-style messages
+ * where the receiver writes progress into a `response` field.
+ *
+ * Channel subscriptions deliver every message in the channel, so the
+ * handlers filter to the requested `messageId` before patching the cache.
+ *
+ * Typed on `TData` — the shape of `message.data`. Defaults to `JSONValue` to
+ * match `MessageStructure`.
+ */
+export function useChannelMessage(identifier, messageId, options) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    const { agentId, channelName } = identifier;
+    const liveUpdates = options?.liveUpdates ?? true;
+    const sources = options?.sources;
+    const key = channelMessageQueryKey(agentId, channelName, messageId, sources);
+    const onMessageUpdate = useCallback((message) => {
+        if (message.id !== messageId)
+            return;
+        queryClient.setQueryData(key, message);
+    }, 
+    // The key array is structurally stable per (agentId, channelName, messageId, sourceDim).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName, messageId, sources?.join(",")]);
+    // Cover the case where the caller has the id before the create event has
+    // landed on this client — patch the cache when it shows up.
+    const onMessage = useCallback((message) => {
+        if (message.id !== messageId)
+            return;
+        queryClient.setQueryData(key, message);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName, messageId, sources?.join(",")]);
+    useChannelSubscription(liveUpdates && messageId ? identifier : undefined, { onMessage, onMessageUpdate });
+    const query = useQuery({
+        queryKey: key,
+        enabled: !!agentId && !!channelName && !!messageId,
+        staleTime: Infinity,
+        queryFn: () => {
+            // 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.getMessage(agentId, channelName, messageId, sourcesArg)
+                : client.messages.getMessage(agentId, channelName, messageId));
+        },
+    });
+    const message = query.data;
+    const { data: _ignored, ...rest } = query;
+    return {
+        ...rest,
+        data: message?.data,
+        message,
+        attachments: message?.attachments,
+        timestamp: message?.timestamp,
+    };
+}

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

@@ -0,0 +1,83 @@
+import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-query";
+import type { MessageStructure } from "../types/common.js";
+import type { ChannelIdentifier } from "../types/viewer.js";
+import { type OfflineStatusSnapshot } from "./useOfflineStatus.js";
+export declare function channelMessagesQueryKey(agentId: string | undefined, channelName: string | undefined, fields?: readonly string[], sources?: string[], anchor?: string): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
+    readonly anchor: string;
+}] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
+    readonly fields: string[];
+}] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
+    readonly anchor: string;
+}, {
+    readonly fields: string[];
+}];
+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;
+    /**
+     * Pin the window to a point in history (snowflake id), for "jump to this
+     * date" navigation. Changing it re-anchors and refetches.
+     *
+     * Distinct from `initialBefore`, which is a clock-skew seed regenerated per
+     * mount and therefore must NOT dimension the cache key. An anchor identifies
+     * a stream the caller means to look at, so it does. Pass a stable value — a
+     * per-render `now` would refetch on every render.
+     *
+     * Cheaper than it looks: anchored windows share the range cache with every
+     * other window on the channel, so re-anchoring over already-fetched history
+     * costs no requests.
+     */
+    anchor?: string;
+    /**
+     * Optional lower-bound snowflake id. The server only returns messages
+     * newer than this on every page, so paginating older eventually returns
+     * an empty page and `hasNextPage` flips to false — useful for fetching
+     * a bounded time window (e.g. last 24h) without a manual cutoff loop on
+     * the consumer side.
+     */
+    after?: string;
+    /**
+     * Keep paging older automatically until `hasNextPage` is false. Almost
+     * always combined with `after` (or a small channel) — without a lower
+     * bound this will walk the channel back to its first message.
+     */
+    autoPaginate?: boolean;
+    /**
+     * Restrict to these source ids on a `MultiplexClient`. Ignored for a plain
+     * `DooverClient` or `LocalAgentClient`. When set, the query key is
+     * source-dimensioned so data from different source subsets is cached
+     * independently.
+     */
+    sources?: string[];
+}
+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;
+    /** Offline/cache status when the provided client supports offline caching. */
+    offline: OfflineStatusSnapshot;
+}
+/**
+ * Paginated infinite query over `DooverDataProvider.getMessages`, with live
+ * `messageCreate` pushes are appended to the newest page and `messageUpdate`
+ * pushes replace matching cached messages. 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/esm/react/useChannelMessages.js

@@ -0,0 +1,214 @@
+import { useCallback, useEffect, useMemo } from "react";
+import { useInfiniteQuery, useQueryClient, } from "@tanstack/react-query";
+import { generateSnowflakeIdAtTime } from "../utils/snowflake.js";
+import { getChannelRangeStore } from "./messageRangeStore.js";
+import { useDooverClient } from "./context.js";
+import { useChannelSubscription } from "./useChannelSubscription.js";
+import { useOfflineStatus } from "./useOfflineStatus.js";
+export function channelMessagesQueryKey(agentId, channelName, fields, sources, anchor) {
+    // Source-dimension the key (multiplex source subsets cache independently);
+    // "*" means "all/unspecified" for a plain DooverClient/LocalAgentClient.
+    const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
+    const base = ["doover", "agent", agentId, "channel", channelName, "messages", "src", sourceDim];
+    // An anchored window is its own chain of cursors, so it must not share a cache
+    // entry with the live one — same reasoning as `fields` below. Note this is
+    // deliberately absent from the range store's key: sharing ranges across
+    // anchors is the point of it.
+    const key = anchor ? [...base, { anchor }] : base;
+    if (!fields || fields.length === 0)
+        return key;
+    // A `field_name`-filtered request returns a different message stream than
+    // the unfiltered (or differently-filtered) one, so it must live under its
+    // own cache entry — otherwise one filter's pagination cursor leaks into
+    // another's `getNextPageParam`, and the "next page" fetch ends up anchored
+    // to an unrelated (often much older) message id. Sort so call-site argument
+    // order doesn't fragment the cache.
+    return [...key, { fields: [...fields].sort() }];
+}
+/** Mirrors `MessagesApi.listMessages`'s own default. */
+const DEFAULT_PAGE_LIMIT = 10;
+/**
+ * Paginated infinite query over `DooverDataProvider.getMessages`, with live
+ * `messageCreate` pushes are appended to the newest page and `messageUpdate`
+ * pushes replace matching cached messages. The "next" page fetches older
+ * messages (cursor = oldest-loaded message id).
+ */
+export function useChannelMessages(identifier, options) {
+    const client = useDooverClient();
+    const offline = useOfflineStatus();
+    const queryClient = useQueryClient();
+    const { agentId, channelName } = identifier;
+    const limit = options?.limit;
+    const liveUpdates = options?.liveUpdates ?? true;
+    const fields = options?.fields;
+    const initialBefore = options?.initialBefore;
+    const anchor = options?.anchor;
+    const after = options?.after;
+    const autoPaginate = options?.autoPaginate ?? false;
+    const sources = options?.sources;
+    const key = channelMessagesQueryKey(agentId, channelName, fields, sources, anchor);
+    // Keyed per stream, NOT per anchor — every window on this channel shares it.
+    const storeKey = JSON.stringify(channelMessagesQueryKey(agentId, channelName, fields, sources));
+    const store = getChannelRangeStore(storeKey);
+    // `after`/`sources` change what a page means (a short page proves a bound was
+    // hit, not that history ran out; multiplex merges several streams), so those
+    // requests bypass the range cache rather than record unsound coverage.
+    const rangeCacheable = after === undefined && !sources;
+    // A dropped socket may have swallowed messages, so the live feed stops being
+    // proof of coverage until a fetch re-establishes it.
+    useEffect(() => {
+        const onClose = () => store.sealTips();
+        client.gateway.on("close", onClose);
+        return () => {
+            client.gateway.off("close", onClose);
+        };
+    }, [client, store]);
+    const onMessage = useCallback((message) => {
+        // This cache entry is scoped to `fields`; the gateway delivers every
+        // message on the channel, so drop live pushes whose payload doesn't
+        // carry one of those fields rather than letting them pollute it.
+        if (fields && fields.length > 0) {
+            const data = message.data;
+            if (!data ||
+                typeof data !== "object" ||
+                !fields.some((f) => f in data)) {
+                return;
+            }
+        }
+        if (rangeCacheable)
+            store.recordLive(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, fields?.join(","), sources?.join(",")]);
+    const onMessageUpdate = useCallback((message) => {
+        // A filtered stream must not accept an update that does not belong to it.
+        // Newly qualifying messages are left for a refetch because inserting one
+        // into an arbitrary cursor page could invalidate that page's boundaries.
+        if (fields && fields.length > 0) {
+            const data = message.data;
+            if (!data ||
+                typeof data !== "object" ||
+                !fields.some((field) => field in data)) {
+                return;
+            }
+        }
+        if (rangeCacheable)
+            store.recordUpdate(message);
+        queryClient.setQueryData(key, (current) => {
+            if (!current)
+                return current;
+            let changed = false;
+            const typed = message;
+            const pages = current.pages.map((page) => page.map((item) => {
+                if (item.id !== typed.id)
+                    return item;
+                changed = true;
+                return typed;
+            }));
+            return changed ? { ...current, pages } : current;
+        });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName, fields?.join(","), sources?.join(",")]);
+    useChannelSubscription(liveUpdates ? identifier : undefined, {
+        onMessage,
+        onMessageUpdate,
+    });
+    const query = useInfiniteQuery({
+        queryKey: key,
+        enabled: !!agentId && !!channelName,
+        staleTime: Infinity,
+        initialPageParam: { before: anchor ?? initialBefore },
+        // Older (down): the next cursor is the oldest id currently held.
+        getNextPageParam: (lastPage) => lastPage && lastPage.length > 0
+            ? { before: lastPage[0]?.id }
+            : undefined,
+        // Newer (up): only for an anchored window — the live window already begins
+        // at "now", so it has nothing above to page into. `after` = newest id held;
+        // the server returns the oldest messages above it, walking up toward now.
+        // An empty page whose own cursor was already a forward `after` means the
+        // top is reached; an empty *initial* page (nothing below the anchor) still
+        // seeds the walk from the anchor, since messages may sit above it.
+        getPreviousPageParam: (firstPage, _all, firstPageParam) => {
+            if (!anchor)
+                return undefined;
+            if (firstPage && firstPage.length > 0) {
+                return { after: firstPage[firstPage.length - 1]?.id };
+            }
+            if (firstPageParam?.after !== undefined)
+                return undefined;
+            return { after: anchor };
+        },
+        queryFn: async ({ pageParam }) => {
+            if (!agentId || !channelName)
+                return [];
+            const id = { agentId, channelName };
+            const param = (pageParam ?? {});
+            // Mirrors the API's own default; the store needs the limit actually applied
+            const effectiveLimit = limit ?? DEFAULT_PAGE_LIMIT;
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `unknown` since the TypeScript overloads don't declare it.
+            const runList = (params) => sources
+                ? client.messages.listMessages(id, params, { sources })
+                : client.messages.listMessages(id, params);
+            // Forward (newer) page: `after` alone pages oldest-first upward. Bypasses
+            // the range store, which models before-anchored windows only.
+            if (param.after !== undefined && param.before === undefined) {
+                const page = await runList({
+                    after: param.after,
+                    ...(limit !== undefined ? { limit } : {}),
+                    ...(fields && fields.length > 0 ? { field_name: fields } : {}),
+                    order: "asc",
+                });
+                return page;
+            }
+            // Older page. Resolve `before` here rather than letting the API default
+            // it, so the range store records the exact bound the request proved.
+            const before = typeof param.before === "string"
+                ? param.before
+                : generateSnowflakeIdAtTime(new Date());
+            if (rangeCacheable) {
+                const cached = store.read(BigInt(before), effectiveLimit);
+                if (cached)
+                    return cached;
+            }
+            const requestedAt = Date.now();
+            const page = await runList({
+                before,
+                ...(limit !== undefined ? { limit } : {}),
+                ...(fields && fields.length > 0 ? { field_name: fields } : {}),
+                ...(after !== undefined ? { after } : {}),
+                order: "asc",
+            });
+            if (rangeCacheable) {
+                store.record({
+                    before: BigInt(before),
+                    limit: effectiveLimit,
+                    page: page,
+                    at: requestedAt,
+                });
+            }
+            return page;
+        },
+    });
+    useEffect(() => {
+        if (!autoPaginate)
+            return;
+        if (query.isFetching || !query.hasNextPage)
+            return;
+        query.fetchNextPage();
+    }, [autoPaginate, query.isFetching, query.hasNextPage, query.fetchNextPage]);
+    const messages = useMemo(() => (query.data?.pages ?? []).flat(), [query.data]);
+    return { ...query, messages, offline };
+}

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

@@ -0,0 +1,27 @@
+import type { Aggregate, JSONValue, MessageStructure } from "../types/common.js";
+import type { ChannelIdentifier } from "../types/viewer.js";
+export interface ChannelSubscriptionHandlers {
+    onMessage?: (message: MessageStructure) => void;
+    /**
+     * Fires on server-side MessageUpdate events. `message` is the full updated
+     * MessageStructure; `request_data` (optional) is the diff of what changed
+     * in this specific update. Most consumers only need `message`.
+     */
+    onMessageUpdate?: (message: MessageStructure, request_data?: JSONValue) => void;
+    onAggregate?: (aggregate: Aggregate) => void;
+    /**
+     * Reserved for future use. The composite gateway already routes by
+     * `channel.agent_id`, so this option is a no-op in v1. Pass it for
+     * forward-compatibility; it has no effect on the subscription.
+     */
+    sources?: string[];
+}
+/**
+ * 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/esm/react/useChannelSubscription.js

@@ -0,0 +1,30 @@
+import { useEffect, useRef } from "react";
+import { useDooverClient } from "./context.js";
+/**
+ * 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 function useChannelSubscription(identifier, handlers) {
+    const client = useDooverClient();
+    const handlersRef = useRef(handlers);
+    handlersRef.current = handlers;
+    useEffect(() => {
+        if (!identifier?.agentId || !identifier?.channelName)
+            return;
+        const channel = { agent_id: identifier.agentId, name: identifier.channelName };
+        const off = client.gateway.subscribeToChannel(channel, {
+            onMessage: (msg) => handlersRef.current.onMessage?.(msg),
+            onMessageUpdate: (msg, rd) => handlersRef.current.onMessageUpdate?.(msg, rd),
+            onAggregate: (agg) => handlersRef.current.onAggregate?.(agg),
+        });
+        void client.gateway.connect();
+        return () => off();
+        // 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/esm/react/useClientStatus.d.ts

@@ -0,0 +1,10 @@
+import type { DataClientStatus } from "../client/data-client.js";
+/**
+ * Returns the live `DataClientStatus` for the client in context. Seeds with
+ * `client.getStatus()`, subscribes via `client.onStatusChange(...)` for the
+ * component's lifetime. Works for a `DooverClient` (single-source) or a
+ * `MultiplexClient` (rolled-up status with a `members` breakdown). Prefer this
+ * over `useConnectionState` for new code — it carries session, latency, last
+ * error and per-source state.
+ */
+export declare function useClientStatus(): DataClientStatus;

package/dist/esm/react/useClientStatus.js

@@ -0,0 +1,19 @@
+import { useEffect, useState } from "react";
+import { useDooverClient } from "./context.js";
+/**
+ * Returns the live `DataClientStatus` for the client in context. Seeds with
+ * `client.getStatus()`, subscribes via `client.onStatusChange(...)` for the
+ * component's lifetime. Works for a `DooverClient` (single-source) or a
+ * `MultiplexClient` (rolled-up status with a `members` breakdown). Prefer this
+ * over `useConnectionState` for new code — it carries session, latency, last
+ * error and per-source state.
+ */
+export function useClientStatus() {
+    const client = useDooverClient();
+    const [status, setStatus] = useState(() => client.getStatus());
+    useEffect(() => {
+        setStatus(client.getStatus());
+        return client.onStatusChange(setStatus);
+    }, [client]);
+    return status;
+}