doover-js 0.6.9 → 0.7.1

package/dist/apis/messages-api.d.ts

@@ -3,6 +3,13 @@ import type { CreateMessageRequest, DataSeries, MessageStructure, UpdateMessageR
 import type { DooverRequestOptions } from "../client/request-options";
 export interface ListMessagesParams {
     before?: string;
+    /**
+     * Lower-bound cursor (exclusive). With `before` set (or defaulted) it merely
+     * floors the window. On its own — `after` set, `before` omitted — it pages
+     * *forward*: the server returns the `limit` **oldest** messages strictly
+     * newer than the cursor, oldest-first. This is the only way to walk history
+     * upward toward "now".
+     */
     after?: string;
     limit?: number;
     field_name?: string[];

package/dist/apis/messages-api.js

@@ -5,15 +5,31 @@ const snowflake_1 = require("../utils/snowflake");
 const _args_1 = require("./_args");
 function resolveListMessagesParams(params) {
     const order = params?.order ?? "desc";
+    const hasAfter = params?.after !== undefined;
+    const hasBefore = params?.before !== undefined;
+    // The server keys pagination on whichever bound is sent: `before` walks
+    // newest-first downward, `after` alone walks oldest-first upward (the N
+    // oldest messages strictly newer than the cursor). Sending `after` without
+    // `before` is the only way to page forward; sending both, or neither, keeps
+    // the newest-first behaviour (defaulting `before` to "now" when unbounded).
+    if (hasAfter && !hasBefore) {
+        const query = {
+            after: params.after,
+            limit: params?.limit ?? 10,
+        };
+        if (params?.field_name !== undefined)
+            query.field_name = params.field_name;
+        return { query, order, serverAscending: true };
+    }
     const query = {
         before: params?.before ?? (0, snowflake_1.generateSnowflakeIdAtTime)(new Date()),
         limit: params?.limit ?? 10,
     };
-    if (params?.after !== undefined)
+    if (hasAfter)
         query.after = params.after;
     if (params?.field_name !== undefined)
         query.field_name = params.field_name;
-    return { query, order };
+    return { query, order, serverAscending: false };
 }
 class MessagesApi {
     constructor(rest) {
@@ -24,10 +40,13 @@ class MessagesApi {
         return this._listMessages(agentId, channelName, options);
     }
     async _listMessages(agentId, channelName, params) {
-        const { query, order } = resolveListMessagesParams(params);
+        const { query, order, serverAscending } = resolveListMessagesParams(params);
         const response = await this.rest.get(`/agents/${agentId}/channels/${channelName}/messages`, query);
         const stamped = response.map(snowflake_1.addTimestampToMessage);
-        return order === "asc" ? [...stamped].reverse() : stamped;
+        // The server returns newest-first for `before` and oldest-first for a bare
+        // `after`; reverse only when that native order differs from what was asked.
+        const wantAscending = order === "asc";
+        return serverAscending === wantAscending ? stamped : [...stamped].reverse();
     }
     async postMessage(...args) {
         if (typeof args[0] === "string") {

package/dist/react/messageRangeStore.d.ts

@@ -0,0 +1,87 @@
+import type { MessageStructure } from "../types/common";
+/**
+ * A per-channel cache of *proven-complete* id ranges.
+ *
+ * `useChannelMessages` models history as a chain of cursors: each page's oldest
+ * id is the next page's `before`. That chain is anchored at its first cursor, so
+ * two windows over the same channel are two unrelated chains — re-anchoring
+ * always refetches, even over data already held.
+ *
+ * This store keeps the fact the chain throws away. A response to
+ * `before=X, limit=N` is "the N newest messages strictly older than X", so a
+ * full page proves that *every* message in `[oldest.id, X)` is in hand. History
+ * is append-only, so that stays true forever. Overlapping windows then merge
+ * into one segment instead of duplicating, and revisiting a range costs nothing.
+ *
+ * The store sits under the query, not beside it: the chains stay as they are and
+ * remain the cache React Query sees, while this layer removes the network calls
+ * underneath them.
+ *
+ * Ids are decimal snowflakes of varying length, so every comparison goes through
+ * `BigInt` — string ordering would put "500" after "4000".
+ */
+/** A contiguous range of history we can prove we hold in full. */
+export interface RangeSegment {
+    /** Id of the oldest message held. Meaningless when `atStart` (coverage runs to -inf). */
+    lo: bigint;
+    /** Exclusive upper bound of proven coverage. */
+    hi: bigint;
+    /** No messages exist below `lo` — the channel (or its retention window) starts here. */
+    atStart: boolean;
+    /**
+     * `hi` tracks the live feed. Only true while a fetch has proven coverage up to
+     * roughly now AND the socket has not dropped since — see `sealTips`.
+     */
+    live: boolean;
+    /** Ascending by id. */
+    messages: MessageStructure[];
+}
+export declare class ChannelRangeStore {
+    /** Disjoint, ascending by `lo`. */
+    private segments;
+    /**
+     * Answer "the newest `limit` messages strictly older than `before`" from cache,
+     * or `undefined` when the range isn't proven and the caller must fetch.
+     *
+     * Returns ascending by id, matching `listMessages({ order: "asc" })`.
+     */
+    read(before: bigint, limit: number): MessageStructure[] | undefined;
+    /**
+     * Record a fetched page. `before` is the cursor actually sent and `limit` the
+     * one actually requested — a short page proves the range bottoms out, which is
+     * only sound because the server rejects an over-cap `limit` rather than
+     * silently clamping it.
+     */
+    record(params: {
+        before: bigint;
+        limit: number;
+        page: MessageStructure[];
+        /** Epoch ms the request was issued, for deciding whether this segment is live. */
+        at?: number;
+    }): void;
+    /**
+     * Extend the live segment with a pushed message. Ignored unless a segment is
+     * currently live: outside that, the message and the segment may have a gap
+     * between them, and claiming coverage across it would hide messages forever.
+     */
+    recordLive(message: MessageStructure): void;
+    /**
+     * Stop trusting the live feed to extend coverage — call when the socket drops.
+     * Messages sent while disconnected would leave a hole, so segments go back to
+     * proving coverage by fetching.
+     */
+    sealTips(): void;
+    /** Test/debug view. */
+    snapshot(): RangeSegment[];
+    clear(): void;
+    /** Union `incoming` with every segment it overlaps or merely touches. */
+    private merge;
+}
+/**
+ * Stores are per *stream* — agent, channel, and any `fields` filter, which
+ * returns a different set of messages. Deliberately NOT per anchor: sharing
+ * across anchors is the entire point.
+ */
+export declare function getChannelRangeStore(key: string): ChannelRangeStore;
+/** Drop every store. Tests only — there is no eviction in normal operation. */
+export declare function resetChannelRangeStores(): void;

package/dist/react/messageRangeStore.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelRangeStore = void 0;
+exports.getChannelRangeStore = getChannelRangeStore;
+exports.resetChannelRangeStores = resetChannelRangeStores;
+/**
+ * How close to "now" a fetch's `before` must be for its segment to accept live
+ * pushes. Beyond this the feed and the segment may not be contiguous.
+ */
+const LIVE_PROOF_TOLERANCE_MS = 60000;
+const idOf = (message) => BigInt(message.id);
+function sortById(messages) {
+    return [...messages].sort((a, b) => (idOf(a) < idOf(b) ? -1 : idOf(a) > idOf(b) ? 1 : 0));
+}
+function dedupeById(messages) {
+    const seen = new Map();
+    // Later wins: a live push or a refetch supersedes an older copy
+    for (const message of messages)
+        seen.set(message.id, message);
+    return sortById([...seen.values()]);
+}
+class ChannelRangeStore {
+    constructor() {
+        /** Disjoint, ascending by `lo`. */
+        this.segments = [];
+    }
+    /**
+     * Answer "the newest `limit` messages strictly older than `before`" from cache,
+     * or `undefined` when the range isn't proven and the caller must fetch.
+     *
+     * Returns ascending by id, matching `listMessages({ order: "asc" })`.
+     */
+    read(before, limit) {
+        const segment = this.segments.find((s) => before <= s.hi && (s.atStart || before >= s.lo));
+        if (!segment)
+            return undefined;
+        const older = segment.messages.filter((m) => idOf(m) < before);
+        if (older.length >= limit)
+            return older.slice(older.length - limit);
+        // Short of `limit` only tells us the range is exhausted if nothing precedes it
+        return segment.atStart ? older : undefined;
+    }
+    /**
+     * Record a fetched page. `before` is the cursor actually sent and `limit` the
+     * one actually requested — a short page proves the range bottoms out, which is
+     * only sound because the server rejects an over-cap `limit` rather than
+     * silently clamping it.
+     */
+    record(params) {
+        const { before, limit, page } = params;
+        const at = params.at ?? Date.now();
+        const messages = sortById(page);
+        const atStart = messages.length < limit;
+        const lo = messages.length > 0 ? idOf(messages[0]) : before;
+        const live = timestampOf(before) >= at - LIVE_PROOF_TOLERANCE_MS;
+        this.merge({ lo, hi: before, atStart, live, messages });
+    }
+    /**
+     * Extend the live segment with a pushed message. Ignored unless a segment is
+     * currently live: outside that, the message and the segment may have a gap
+     * between them, and claiming coverage across it would hide messages forever.
+     */
+    recordLive(message) {
+        const id = idOf(message);
+        const tip = this.segments.find((s) => s.live);
+        if (!tip || id < tip.lo)
+            return;
+        tip.messages = dedupeById([...tip.messages, message]);
+        if (id >= tip.hi)
+            tip.hi = id + 1n;
+    }
+    /**
+     * Stop trusting the live feed to extend coverage — call when the socket drops.
+     * Messages sent while disconnected would leave a hole, so segments go back to
+     * proving coverage by fetching.
+     */
+    sealTips() {
+        for (const segment of this.segments)
+            segment.live = false;
+    }
+    /** Test/debug view. */
+    snapshot() {
+        return this.segments.map((s) => ({ ...s, messages: [...s.messages] }));
+    }
+    clear() {
+        this.segments = [];
+    }
+    /** Union `incoming` with every segment it overlaps or merely touches. */
+    merge(incoming) {
+        const overlapping = [];
+        const rest = [];
+        for (const segment of this.segments) {
+            // Touching counts: [a,b) and [b,c) are both proven, so [a,c) is too
+            const disjoint = segment.hi < incoming.lo || segment.lo > incoming.hi;
+            (disjoint ? rest : overlapping).push(segment);
+        }
+        const merged = overlapping.reduce((acc, s) => ({
+            lo: s.lo < acc.lo ? s.lo : acc.lo,
+            hi: s.hi > acc.hi ? s.hi : acc.hi,
+            atStart: acc.atStart || s.atStart,
+            live: acc.live || s.live,
+            messages: [...acc.messages, ...s.messages],
+        }), incoming);
+        merged.messages = dedupeById(merged.messages);
+        if (merged.atStart && merged.messages.length > 0) {
+            merged.lo = idOf(merged.messages[0]);
+        }
+        this.segments = [...rest, merged].sort((a, b) => (a.lo < b.lo ? -1 : a.lo > b.lo ? 1 : 0));
+    }
+}
+exports.ChannelRangeStore = ChannelRangeStore;
+const SNOWFLAKE_EPOCH_MS = 1735689600000n;
+/** Epoch ms encoded in a snowflake, without going through the string round-trip. */
+function timestampOf(id) {
+    return Number((id >> 22n) + SNOWFLAKE_EPOCH_MS);
+}
+const stores = new Map();
+/**
+ * Stores are per *stream* — agent, channel, and any `fields` filter, which
+ * returns a different set of messages. Deliberately NOT per anchor: sharing
+ * across anchors is the entire point.
+ */
+function getChannelRangeStore(key) {
+    let store = stores.get(key);
+    if (!store) {
+        store = new ChannelRangeStore();
+        stores.set(key, store);
+    }
+    return store;
+}
+/** Drop every store. Tests only — there is no eviction in normal operation. */
+function resetChannelRangeStores() {
+    stores.clear();
+}

package/dist/react/useChannelMessages.d.ts

@@ -2,7 +2,13 @@ import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-
 import type { MessageStructure } from "../types/common";
 import type { ChannelIdentifier } from "../types/viewer";
 import { type OfflineStatusSnapshot } from "./useOfflineStatus";
-export declare function channelMessagesQueryKey(agentId: string | undefined, channelName: string | undefined, fields?: readonly string[], sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
+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 {
@@ -22,6 +28,20 @@ export interface UseChannelMessagesOptions {
      * 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

package/dist/react/useChannelMessages.js

@@ -4,14 +4,21 @@ exports.channelMessagesQueryKey = channelMessagesQueryKey;
 exports.useChannelMessages = useChannelMessages;
 const react_1 = require("react");
 const react_query_1 = require("@tanstack/react-query");
+const snowflake_1 = require("../utils/snowflake");
+const messageRangeStore_1 = require("./messageRangeStore");
 const context_1 = require("./context");
 const useChannelSubscription_1 = require("./useChannelSubscription");
 const useOfflineStatus_1 = require("./useOfflineStatus");
-function channelMessagesQueryKey(agentId, channelName, fields, sources) {
+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 key = ["doover", "agent", agentId, "channel", channelName, "messages", "src", sourceDim];
+    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
@@ -22,6 +29,8 @@ function channelMessagesQueryKey(agentId, channelName, fields, sources) {
     // 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 prepended/appended to the newest page. The "next"
@@ -36,10 +45,27 @@ function useChannelMessages(identifier, options) {
     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);
+    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 = (0, messageRangeStore_1.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.
+    (0, react_1.useEffect)(() => {
+        const onClose = () => store.sealTips();
+        client.gateway.on("close", onClose);
+        return () => {
+            client.gateway.off("close", onClose);
+        };
+    }, [client, store]);
     const onMessage = (0, react_1.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
@@ -52,6 +78,8 @@ function useChannelMessages(identifier, options) {
                 return;
             }
         }
+        if (rangeCacheable)
+            store.recordLive(message);
         queryClient.setQueryData(key, (current) => {
             if (!current)
                 return current;
@@ -71,25 +99,76 @@ function useChannelMessages(identifier, options) {
         queryKey: key,
         enabled: !!agentId && !!channelName,
         staleTime: Infinity,
-        initialPageParam: initialBefore,
-        getNextPageParam: (lastPage) => lastPage && lastPage.length > 0 ? lastPage[0]?.id : undefined,
+        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 params = {
-                ...(typeof pageParam === "string" ? { before: pageParam } : {}),
+            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
+                : (0, snowflake_1.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",
-            };
-            // Pass `{ sources }` as a trailing bag only when set — cast through
-            // `never` since the TypeScript overloads don't declare it.
-            const sourcesArg = sources ? { sources } : undefined;
-            const page = sourcesArg
-                ? await client.messages.listMessages(id, params, sourcesArg)
-                : await client.messages.listMessages(id, params);
+            });
+            if (rangeCacheable) {
+                store.record({
+                    before: BigInt(before),
+                    limit: effectiveLimit,
+                    page: page,
+                    at: requestedAt,
+                });
+            }
             return page;
         },
     });

package/dist/test/apis.test.js

@@ -229,6 +229,36 @@ function setupRest(responseFactory) {
         (0, chai_1.expect)(formData.get("json_payload")).to.equal(JSON.stringify({ data: { x: 1 } }));
         (0, chai_1.expect)(formData.get("attachment-0")).to.be.instanceOf(Blob);
     });
+    (0, mocha_1.it)("pages forward with a bare `after`: sends no `before`, keeps oldest-first", async () => {
+        const older = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00Z"));
+        const newer = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-02T00:00:00Z"));
+        // The `after`-only route returns oldest-first natively (scan_index_forward).
+        const nativeAsc = [
+            { id: older, author_id: "u", channel: { agent_id: "a1", name: "c1" }, data: {}, attachments: [] },
+            { id: newer, author_id: "u", channel: { agent_id: "a1", name: "c1" }, data: {}, attachments: [] },
+        ];
+        let lastQuery;
+        const { rest } = setupRest((url) => {
+            if (url.endsWith("/messages") || url.includes("/messages?")) {
+                lastQuery = new URL(url).searchParams;
+                return (0, helpers_1.createJsonResponse)(nativeAsc);
+            }
+            return (0, helpers_1.createJsonResponse)([]);
+        });
+        const api = new messages_api_1.MessagesApi(rest);
+        // asc: server order already matches → no reversal, no `before` sent.
+        const asc = await api.listMessages("a1", "c1", { after: older, limit: 5, order: "asc" });
+        (0, chai_1.expect)(lastQuery?.get("after")).to.equal(older);
+        (0, chai_1.expect)(lastQuery?.has("before"), "bare `after` must not send `before`").to.equal(false);
+        (0, chai_1.expect)(asc.map((m) => m.id)).to.deep.equal([older, newer]);
+        // desc over the same forward route reverses the native ascending page.
+        const desc = await api.listMessages("a1", "c1", { after: older, limit: 5, order: "desc" });
+        (0, chai_1.expect)(desc.map((m) => m.id)).to.deep.equal([newer, older]);
+        // With `before` present, `after` is only a floor and both bounds are sent.
+        await api.listMessages("a1", "c1", { before: newer, after: older, limit: 5, order: "asc" });
+        (0, chai_1.expect)(lastQuery?.get("before")).to.equal(newer);
+        (0, chai_1.expect)(lastQuery?.get("after")).to.equal(older);
+    });
     (0, mocha_1.it)("covers aggregates and alarms methods", async () => {
         const { rest, fetchMock } = setupRest((url) => {
             if (url.includes("/attachments/")) {

package/dist/test/message-range-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/message-range-store.test.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const messageRangeStore_1 = require("../react/messageRangeStore");
+const snowflake_1 = require("../utils/snowflake");
+/** Frozen so a cursor built twice is the same cursor — real clocks make these flaky. */
+const NOW = Date.now();
+/** Messages at 1-minute spacing, oldest first, ending `minutesAgo` before NOW. */
+function makeMessages(count, startMinutesAgo) {
+    return Array.from({ length: count }, (_, i) => {
+        const at = new Date(NOW - (startMinutesAgo - i) * 60000);
+        return {
+            id: (0, snowflake_1.generateSnowflakeIdAtTime)(at),
+            data: { i },
+            attachments: [],
+            author_id: "a",
+            channel: { agentId: "agent", channelName: "chan" },
+            timestamp: at.getTime(),
+        };
+    });
+}
+const idAt = (minutesAgo) => BigInt((0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - minutesAgo * 60000)));
+const ids = (messages) => (messages ?? []).map((m) => m.id);
+(0, mocha_1.describe)("ChannelRangeStore", () => {
+    let store;
+    (0, mocha_1.beforeEach)(() => {
+        store = new messageRangeStore_1.ChannelRangeStore();
+    });
+    (0, mocha_1.it)("returns undefined for a range it has never seen", () => {
+        (0, chai_1.expect)(store.read(idAt(0), 10)).to.equal(undefined);
+    });
+    (0, mocha_1.it)("serves a full page back from cache", () => {
+        const page = makeMessages(10, 20);
+        store.record({ before: idAt(0), limit: 10, page });
+        const read = store.read(idAt(0), 10);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page));
+    });
+    (0, mocha_1.it)("returns messages ascending, matching order:asc", () => {
+        const page = makeMessages(5, 20);
+        store.record({ before: idAt(0), limit: 5, page });
+        const read = store.read(idAt(0), 5);
+        for (let i = 1; i < read.length; i++) {
+            (0, chai_1.expect)(BigInt(read[i].id) > BigInt(read[i - 1].id)).to.equal(true);
+        }
+    });
+    (0, mocha_1.it)("serves the NEWEST `limit` older than the cursor, not the first", () => {
+        const page = makeMessages(10, 20); // 20..11 minutes ago
+        store.record({ before: idAt(0), limit: 10, page });
+        const read = store.read(idAt(0), 3);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page.slice(7)));
+    });
+    (0, mocha_1.it)("excludes the cursor message itself (`before` is exclusive)", () => {
+        const page = makeMessages(5, 20);
+        store.record({ before: idAt(0), limit: 5, page });
+        // Only 2 messages sit below page[2], so asking for more would (rightly) be
+        // unanswerable — nothing proves what lies below the segment's `lo`.
+        const cursor = BigInt(page[2].id);
+        const read = store.read(cursor, 2);
+        (0, chai_1.expect)(read.every((m) => BigInt(m.id) < cursor)).to.equal(true);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page.slice(0, 2)));
+    });
+    (0, mocha_1.it)("will not answer beyond what it has proven", () => {
+        const page = makeMessages(10, 20);
+        store.record({ before: idAt(0), limit: 10, page });
+        // Holds 10, asked for 20, and nothing says the range bottoms out here
+        (0, chai_1.expect)(store.read(idAt(0), 20)).to.equal(undefined);
+    });
+    (0, mocha_1.it)("answers short when a short page proved the range bottoms out", () => {
+        const page = makeMessages(3, 20);
+        store.record({ before: idAt(0), limit: 10, page }); // 3 < 10 => atStart
+        const read = store.read(idAt(0), 10);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page));
+    });
+    (0, mocha_1.it)("will not answer a cursor above its proven upper bound", () => {
+        const page = makeMessages(10, 20);
+        store.record({ before: idAt(10), limit: 10, page });
+        // Nothing proves what sits between 10 minutes ago and now
+        (0, chai_1.expect)(store.read(idAt(0), 5)).to.equal(undefined);
+    });
+    (0, mocha_1.it)("merges touching ranges so a later read spans both", () => {
+        const older = makeMessages(10, 40); // 40..31
+        const newer = makeMessages(10, 20); // 20..11
+        store.record({ before: idAt(0), limit: 10, page: newer });
+        // Paging older: cursor is the oldest we held
+        store.record({ before: BigInt(newer[0].id), limit: 10, page: older, at: NOW });
+        (0, chai_1.expect)(store.snapshot()).to.have.length(1);
+        const read = store.read(idAt(0), 20);
+        (0, chai_1.expect)(ids(read)).to.deep.equal([...ids(older), ...ids(newer)]);
+    });
+    (0, mocha_1.it)("merges overlapping ranges without duplicating", () => {
+        const page = makeMessages(10, 20);
+        store.record({ before: idAt(0), limit: 10, page });
+        store.record({ before: idAt(0), limit: 10, page }); // same window again
+        (0, chai_1.expect)(store.snapshot()).to.have.length(1);
+        (0, chai_1.expect)(ids(store.read(idAt(0), 10))).to.deep.equal(ids(page));
+    });
+    (0, mocha_1.it)("keeps disjoint ranges apart rather than claiming the gap", () => {
+        const ancient = makeMessages(5, 500);
+        const recent = makeMessages(5, 20);
+        store.record({ before: idAt(0), limit: 5, page: recent });
+        store.record({ before: idAt(400), limit: 5, page: ancient });
+        (0, chai_1.expect)(store.snapshot()).to.have.length(2);
+        // The hole between them is not covered, so a span across it must refetch
+        (0, chai_1.expect)(store.read(idAt(0), 10)).to.equal(undefined);
+    });
+    (0, mocha_1.it)("serves an anchored read from a range fetched for a different anchor", () => {
+        const page = makeMessages(30, 60);
+        store.record({ before: idAt(0), limit: 30, page });
+        // Jumping to 30 minutes ago costs nothing: already proven
+        const read = store.read(idAt(30), 5);
+        (0, chai_1.expect)(read).to.not.equal(undefined);
+        (0, chai_1.expect)(read.every((m) => m.timestamp < Date.now() - 30 * 60000)).to.equal(true);
+    });
+    (0, mocha_1.it)("orders by numeric id, not string (500 sorts before 4000)", () => {
+        const short = { id: "500", timestamp: 1 };
+        const long = { id: "4000", timestamp: 2 };
+        store.record({ before: 5000n, limit: 10, page: [long, short], at: NOW });
+        (0, chai_1.expect)(ids(store.read(5000n, 10))).to.deep.equal(["500", "4000"]);
+    });
+    (0, mocha_1.it)("records an empty page as a proven-empty range", () => {
+        store.record({ before: idAt(0), limit: 10, page: [] });
+        (0, chai_1.expect)(store.read(idAt(0), 10)).to.deep.equal([]);
+    });
+    (0, mocha_1.describe)("live tip", () => {
+        (0, mocha_1.it)("extends coverage with pushes when proven up to now", () => {
+            const page = makeMessages(5, 20);
+            store.record({ before: idAt(0), limit: 5, page });
+            const [live] = makeMessages(1, -1); // one minute into the future
+            store.recordLive(live);
+            const read = store.read(BigInt(live.id) + 1n, 6);
+            (0, chai_1.expect)(ids(read)).to.deep.equal([...ids(page), live.id]);
+        });
+        (0, mocha_1.it)("ignores pushes for a stale window, which may not be contiguous", () => {
+            const page = makeMessages(5, 500);
+            // Proven only up to ~8 hours ago, so a push now leaves a hole
+            store.record({ before: idAt(480), limit: 5, page });
+            const [live] = makeMessages(1, 0);
+            store.recordLive(live);
+            (0, chai_1.expect)(store.read(BigInt(live.id) + 1n, 6)).to.equal(undefined);
+        });
+        (0, mocha_1.it)("stops extending once the socket drops", () => {
+            const page = makeMessages(5, 20);
+            store.record({ before: idAt(0), limit: 5, page });
+            store.sealTips(); // gateway "close"
+            const [live] = makeMessages(1, -1);
+            store.recordLive(live);
+            // The push is not trusted to prove the range, so the gap must be refetched
+            (0, chai_1.expect)(store.read(BigInt(live.id) + 1n, 6)).to.equal(undefined);
+        });
+        (0, mocha_1.it)("does not duplicate a push already fetched", () => {
+            const page = makeMessages(5, 20);
+            store.record({ before: idAt(0), limit: 5, page });
+            store.recordLive(page[4]);
+            (0, chai_1.expect)(ids(store.read(idAt(0), 5))).to.deep.equal(ids(page));
+        });
+    });
+});
+(0, mocha_1.describe)("getChannelRangeStore", () => {
+    (0, mocha_1.beforeEach)(() => (0, messageRangeStore_1.resetChannelRangeStores)());
+    (0, mocha_1.it)("shares one store per stream key", () => {
+        (0, chai_1.expect)((0, messageRangeStore_1.getChannelRangeStore)("a|c")).to.equal((0, messageRangeStore_1.getChannelRangeStore)("a|c"));
+    });
+    (0, mocha_1.it)("keeps different streams apart", () => {
+        (0, chai_1.expect)((0, messageRangeStore_1.getChannelRangeStore)("a|c")).to.not.equal((0, messageRangeStore_1.getChannelRangeStore)("a|d"));
+    });
+});

package/dist/test/react-channel-messages-forward.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/react-channel-messages-forward.test.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const sinon_1 = __importDefault(require("sinon"));
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const messageRangeStore_1 = require("../react/messageRangeStore");
+const snowflake_1 = require("../utils/snowflake");
+const helpers_1 = require("./helpers");
+const AGENT = "agent-1";
+const CHANNEL = "camera_1";
+const NOW = Date.now();
+/** `COUNT` messages, one per minute, ascending by id (index 0 = oldest). */
+const COUNT = 60;
+const ALL = Array.from({ length: COUNT }, (_, i) => {
+    const at = new Date(NOW - (COUNT - 1 - i) * 60000);
+    return {
+        id: (0, snowflake_1.generateSnowflakeIdAtTime)(at),
+        data: { i },
+        attachments: [],
+        author_id: "author",
+        channel: { agent_id: AGENT, name: CHANNEL },
+    };
+}).sort((a, b) => (BigInt(a.id) < BigInt(b.id) ? -1 : 1));
+/**
+ * Emulates the REST route's *native* ordering, which the SDK client then
+ * reverses per `order`: `before` returns the newest N below the cursor,
+ * newest-first; a bare `after` returns the oldest N above it, oldest-first.
+ */
+function serveNative(query) {
+    const before = query.get("before");
+    const after = query.get("after");
+    const limit = Number(query.get("limit") ?? "10");
+    if (before && !after) {
+        const below = ALL.filter((m) => BigInt(m.id) < BigInt(before));
+        return below.slice(Math.max(0, below.length - limit)).reverse(); // newest-first
+    }
+    if (after && !before) {
+        const above = ALL.filter((m) => BigInt(m.id) > BigInt(after));
+        return above.slice(0, limit); // oldest-first
+    }
+    // both bounds: newest-first within (after, before]
+    const within = ALL.filter((m) => BigInt(m.id) < BigInt(before) && BigInt(m.id) > BigInt(after));
+    return within.slice(Math.max(0, within.length - limit)).reverse();
+}
+function makeClient() {
+    const calls = [];
+    const fetchMock = sinon_1.default.stub().callsFake(async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (url.includes("/messages")) {
+            const q = new URL(url).searchParams;
+            calls.push(q);
+            return (0, helpers_1.createJsonResponse)(serveNative(q));
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, calls };
+}
+function wrapper(client, queryClient) {
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+const newQueryClient = () => new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+const idAtIndex = (i) => ALL[i].id;
+const timeOfIndex = (i) => NOW - (COUNT - 1 - i) * 60000;
+/** A snowflake landing strictly between messages i and i+1 (30s after i). */
+const anchorAfter = (i) => (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(timeOfIndex(i) + 30000));
+(0, mocha_1.describe)("useChannelMessages forward pagination", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        (0, messageRangeStore_1.resetChannelRangeStores)();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("pages forward from an anchor into newer messages", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        // Anchor between index 29 and 30 — half the history is newer than it.
+        const anchor = anchorAfter(29);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(10));
+        // The anchored page is the 10 newest *below* the anchor: indices 20..29.
+        (0, chai_1.expect)(result.current.messages.every((m) => BigInt(m.id) < BigInt(anchor))).to.equal(true);
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(true);
+        await (0, react_1.act)(async () => {
+            await result.current.fetchPreviousPage();
+        });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages.some((m) => BigInt(m.id) > BigInt(anchor))).to.equal(true));
+        // Forward page brought in the messages immediately above the anchor (index 30+).
+        (0, chai_1.expect)(result.current.messages.map((m) => m.data).some((d) => d.i >= 30)).to.equal(true);
+    });
+    (0, mocha_1.it)("exposes no previous page for an unanchored (live) window", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(10));
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(false);
+    });
+    (0, mocha_1.it)("recovers messages above an anchor that has nothing below it, and terminates", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        // Anchor older than every message: the initial before=anchor page is empty.
+        const anchor = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - COUNT * 10 * 60000));
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.isLoading).to.equal(false));
+        (0, chai_1.expect)(result.current.messages).to.have.length(0);
+        // Empty below, but the walk still seeds from the anchor itself.
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(true);
+        // Drain forward until exhausted — must terminate, never loop.
+        for (let guard = 0; guard < 20 && result.current.hasPreviousPage; guard++) {
+            await (0, react_1.act)(async () => {
+                await result.current.fetchPreviousPage();
+            });
+        }
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(false);
+        // Every message above the anchor is recovered (order is the consumer's job).
+        const ids = result.current.messages.map((m) => m.id);
+        (0, chai_1.expect)(ids).to.have.length(COUNT);
+        (0, chai_1.expect)(ids).to.include(idAtIndex(0));
+        (0, chai_1.expect)(ids).to.include(idAtIndex(COUNT - 1));
+    });
+});

package/dist/test/react-channel-messages-range.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/react-channel-messages-range.test.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const sinon_1 = __importDefault(require("sinon"));
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const messageRangeStore_1 = require("../react/messageRangeStore");
+const snowflake_1 = require("../utils/snowflake");
+const helpers_1 = require("./helpers");
+const AGENT = "agent-1";
+const CHANNEL = "camera_1";
+const NOW = Date.now();
+/** Newest-first, as the bare REST route returns it. */
+function messagesDesc(count, startMinutesAgo) {
+    return Array.from({ length: count }, (_, i) => {
+        const at = new Date(NOW - (startMinutesAgo + i) * 60000);
+        return {
+            id: (0, snowflake_1.generateSnowflakeIdAtTime)(at),
+            data: { i },
+            attachments: [],
+            author_id: "author",
+            channel: { agent_id: AGENT, name: CHANNEL },
+        };
+    });
+}
+function makeClient(page) {
+    const calls = [];
+    const fetchMock = sinon_1.default.stub().callsFake(async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (url.includes("/messages")) {
+            const parsed = new URL(url);
+            calls.push({
+                before: parsed.searchParams.get("before"),
+                limit: parsed.searchParams.get("limit"),
+            });
+            return (0, helpers_1.createJsonResponse)(page);
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, calls };
+}
+/** One QueryClient per test, shared by both hooks, as a real app would have. */
+function wrapper(client, queryClient) {
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+const newQueryClient = () => new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+(0, mocha_1.describe)("useChannelMessages range cache", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        (0, messageRangeStore_1.resetChannelRangeStores)();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("serves an anchored window from history already fetched, without refetching", async () => {
+        const page = messagesDesc(30, 1); // 1..30 minutes ago
+        const { client, calls } = makeClient(page);
+        const qc = newQueryClient();
+        const live = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 30 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(live.result.current.messages).to.have.length(30));
+        (0, chai_1.expect)(calls).to.have.length(1);
+        // Anchor inside the range just proven — a different chain, same store
+        const anchor = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - 10 * 60000));
+        const anchored = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 5, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(anchored.result.current.messages).to.have.length(5));
+        (0, chai_1.expect)(calls, "anchoring over covered history should not hit the network").to.have.length(1);
+        (0, chai_1.expect)(anchored.result.current.messages.every((m) => BigInt(m.id) < BigInt(anchor))).to.equal(true);
+    });
+    (0, mocha_1.it)("fetches when the anchor lands outside anything proven", async () => {
+        const page = messagesDesc(30, 1);
+        const { client, calls } = makeClient(page);
+        const qc = newQueryClient();
+        const live = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 30 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(live.result.current.messages).to.have.length(30));
+        // A year back is nowhere near the covered range
+        const anchor = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - 365 * 24 * 60 * 60000));
+        (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 5, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(calls).to.have.length(2));
+        (0, chai_1.expect)(calls[1].before).to.equal(anchor);
+    });
+    (0, mocha_1.it)("keeps the unanchored key untouched, so existing consumers are unaffected", async () => {
+        const page = messagesDesc(10, 1);
+        const { client, calls } = makeClient(page);
+        const qc = newQueryClient();
+        const first = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(first.result.current.messages).to.have.length(10));
+        // Same options => same query key => React Query serves it, no second request
+        const second = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(second.result.current.messages).to.have.length(10));
+        (0, chai_1.expect)(calls).to.have.length(1);
+    });
+});

package/dist/test/react-multiagent-messages.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/react-multiagent-messages.test.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const helpers_1 = require("./helpers");
+const sinon_1 = __importDefault(require("sinon"));
+/**
+ * Fetch mock for the multi-agent messages endpoint. `pagesByRound` supplies
+ * one canned response per call, in order, so a test can hand back
+ * `next_cursors` on early rounds and drain on the last one.
+ */
+function makeClient(pagesByRound) {
+    let round = 0;
+    const calls = [];
+    const fetchMock = sinon_1.default.stub().callsFake(async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (url.includes("/messages")) {
+            const parsed = new URL(url);
+            calls.push({
+                agent_id: parsed.searchParams.getAll("agent_id"),
+                agent_before: parsed.searchParams.getAll("agent_before"),
+            });
+            const page = pagesByRound[Math.min(round, pagesByRound.length - 1)];
+            round += 1;
+            return (0, helpers_1.createJsonResponse)(page);
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, calls };
+}
+function wrapper(client) {
+    const queryClient = new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+function msg(id, agentId) {
+    return { id, channel: { agent_id: agentId, name: "tag_values" }, data: {} };
+}
+(0, mocha_1.describe)("useMultiAgentChannelMessages autoPaginate", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        helpers_1.MockWebSocket.reset();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("walks back per-agent via next_cursors until the window drains", async () => {
+        const { client, calls } = makeClient([
+            // round 1: a1 hit its limit (cursor returned), a2 drained already
+            { results: [msg("100", "a1"), msg("99", "a2")], next_cursors: { a1: "90" } },
+            // round 2: a1 drains
+            { results: [msg("89", "a1")], next_cursors: {} },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1", "a2"], {
+            after: "1",
+            agentMessageLimit: 2,
+            autoPaginate: true,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(3));
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(false);
+        // Second request must resume ONLY a1, using its own cursor as agent_before.
+        (0, chai_1.expect)(calls).to.have.length(2);
+        (0, chai_1.expect)(calls[1].agent_id).to.deep.equal(["a1"]);
+        (0, chai_1.expect)(calls[1].agent_before).to.deep.equal(["90"]);
+    });
+    (0, mocha_1.it)("does not paginate when autoPaginate is off", async () => {
+        const { client, calls } = makeClient([
+            { results: [msg("100", "a1")], next_cursors: { a1: "90" } },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1"], {
+            agentMessageLimit: 1,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(1));
+        // hasNextPage is exposed, but nothing auto-fetches the second page.
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(true);
+        (0, chai_1.expect)(calls).to.have.length(1);
+    });
+    (0, mocha_1.it)("dedupes messages that repeat across pages", async () => {
+        const { client } = makeClient([
+            { results: [msg("100", "a1")], next_cursors: { a1: "100" } },
+            // overlaps the previous page's id 100 (legacy-style re-return)
+            { results: [msg("100", "a1"), msg("90", "a1")], next_cursors: {} },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1"], {
+            after: "1",
+            agentMessageLimit: 1,
+            autoPaginate: true,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(2));
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(false);
+        (0, chai_1.expect)(result.current.messages.map((m) => m.id)).to.deep.equal(["100", "90"]);
+    });
+});

package/package.json

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