doover-js 0.6.8 → 0.7.0

package/dist/auth/doover-auth.d.ts

@@ -41,6 +41,12 @@ export declare abstract class DooverAuth {
      * Called before every HTTP request and before opening a websocket.
      */
     abstract ensureReady(): Promise<void>;
+    /**
+     * Called after an authenticated HTTP request receives a 401. Return true when
+     * the auth layer recovered (for example by forcing a token refresh) and the
+     * request should be retried once.
+     */
+    handleUnauthorized(): Promise<boolean>;
     /** Attach a profile and optional config manager for refresh persistence. */
     attachProfile(profile: AuthProfile, configManager?: AuthProfileStore): void;
 }

package/dist/auth/doover-auth.js

@@ -13,6 +13,14 @@ class DooverAuth {
         this.profile = null;
         this.configManager = null;
     }
+    /**
+     * Called after an authenticated HTTP request receives a 401. Return true when
+     * the auth layer recovered (for example by forcing a token refresh) and the
+     * request should be retried once.
+     */
+    async handleUnauthorized() {
+        return false;
+    }
     /** Attach a profile and optional config manager for refresh persistence. */
     attachProfile(profile, configManager) {
         this.profile = profile;

package/dist/auth/doover-token-auth.d.ts

@@ -10,6 +10,7 @@ export declare class DooverTokenAuth extends DooverAuth {
     private authServerClientId;
     private fetchImpl;
     private refreshInFlight;
+    private authInvalid;
     constructor(options: {
         token?: string | null;
         tokenExpires?: Date | number | null;
@@ -28,9 +29,11 @@ export declare class DooverTokenAuth extends DooverAuth {
     setToken(token: string | null, tokenExpires?: Date | number | null): void;
     setRefreshToken(refreshToken: string | null): void;
     ensureReady(): Promise<void>;
+    handleUnauthorized(): Promise<boolean>;
     attachProfile(profile: AuthProfile, configManager?: AuthProfileStore): void;
     private needsRefresh;
     private refresh;
     private persistToProfile;
+    private markAuthInvalid;
     private resolveExpiry;
 }

package/dist/auth/doover-token-auth.js

@@ -10,6 +10,7 @@ class DooverTokenAuth extends doover_auth_1.DooverAuth {
     constructor(options) {
         super();
         this.refreshInFlight = null;
+        this.authInvalid = false;
         this.token = options.token ?? null;
         this.tokenExpires = this.resolveExpiry(options.tokenExpires, options.token ?? null);
         this.refreshToken = options.refreshToken ?? null;
@@ -48,13 +49,22 @@ class DooverTokenAuth extends doover_auth_1.DooverAuth {
     setToken(token, tokenExpires) {
         this.token = token;
         this.tokenExpires = this.resolveExpiry(tokenExpires, token);
+        if (token) {
+            this.authInvalid = false;
+        }
         this.persistToProfile();
     }
     setRefreshToken(refreshToken) {
         this.refreshToken = refreshToken;
+        if (refreshToken) {
+            this.authInvalid = false;
+        }
         this.persistToProfile();
     }
     async ensureReady() {
+        if (this.authInvalid) {
+            throw new errors_1.DooverAuthError("Authentication is invalid; sign in again");
+        }
         if (!this.needsRefresh()) {
             return;
         }
@@ -66,6 +76,23 @@ class DooverTokenAuth extends doover_auth_1.DooverAuth {
         }
         return this.refreshInFlight;
     }
+    async handleUnauthorized() {
+        if (this.authInvalid) {
+            return false;
+        }
+        if (!this.refreshInFlight) {
+            this.refreshInFlight = this.refresh().finally(() => {
+                this.refreshInFlight = null;
+            });
+        }
+        try {
+            await this.refreshInFlight;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     // ------------------------------------------------------------------
     // Profile attachment override — load refresh metadata from profile
     // ------------------------------------------------------------------
@@ -110,6 +137,7 @@ class DooverTokenAuth extends doover_auth_1.DooverAuth {
         if (!this.authServerUrl ||
             !this.refreshToken ||
             !this.authServerClientId) {
+            this.markAuthInvalid();
             throw new errors_1.DooverAuthError("Cannot refresh token: missing authServerUrl, refreshToken, or authServerClientId");
         }
         const url = new URL(`${this.authServerUrl}/oauth2/token`);
@@ -129,12 +157,17 @@ class DooverTokenAuth extends doover_auth_1.DooverAuth {
             throw new errors_1.DooverAuthError(`Token refresh request failed: ${err instanceof Error ? err.message : String(err)}`);
         }
         if (!response.ok) {
+            if (response.status >= 400 && response.status < 500) {
+                this.markAuthInvalid();
+            }
             throw new errors_1.DooverAuthError(`Token refresh failed with status ${response.status}`);
         }
         const body = (await response.json());
         if (!body.access_token) {
+            this.markAuthInvalid();
             throw new errors_1.DooverAuthError("Token refresh response did not contain an access_token");
         }
+        this.authInvalid = false;
         this.token = body.access_token;
         this.tokenExpires =
             typeof body.expires_in === "number"
@@ -154,9 +187,7 @@ class DooverTokenAuth extends doover_auth_1.DooverAuth {
         this.profile.tokenExpires = this.tokenExpires
             ? this.tokenExpires.toISOString()
             : null;
-        if (this.refreshToken) {
-            this.profile.refreshToken = this.refreshToken;
-        }
+        this.profile.refreshToken = this.refreshToken;
         if (this.configManager) {
             try {
                 this.configManager.create(this.profile);
@@ -167,6 +198,13 @@ class DooverTokenAuth extends doover_auth_1.DooverAuth {
             }
         }
     }
+    markAuthInvalid() {
+        this.authInvalid = true;
+        this.token = null;
+        this.tokenExpires = null;
+        this.refreshToken = null;
+        this.persistToProfile();
+    }
     resolveExpiry(explicit, token) {
         if (explicit instanceof Date) {
             return explicit;

package/dist/client/multiplex-client.js

@@ -554,7 +554,23 @@ class MultiplexClient {
                 }
                 const responses = await Promise.all(members.map((m) => m.client.agents.getMultiAgentMessages(...args)));
                 const merged = (0, multiplex_merge_1.mergeMessages)(responses.map((r) => r.results), { order: "desc" });
-                return { results: merged, count: merged.length };
+                // Union each member's per-agent resume cursors so a paginating caller
+                // keeps walking. If one agent lives in two members with different
+                // cursors, keep the lexically-highest (newest) — resuming from the
+                // older one would skip the newer member's tail; resuming from the
+                // newer just re-fetches a few messages that dedupe by id downstream.
+                const nextCursors = {};
+                for (const r of responses) {
+                    for (const [id, cursor] of Object.entries(r.next_cursors ?? {})) {
+                        if (!(id in nextCursors) || cursor > nextCursors[id])
+                            nextCursors[id] = cursor;
+                    }
+                }
+                return {
+                    results: merged,
+                    count: merged.length,
+                    ...(Object.keys(nextCursors).length > 0 ? { next_cursors: nextCursors } : {}),
+                };
             },
             async getMultiAgentAggregates(channelName, ...rest) {
                 const { args, sources } = self.splitSourcesOption([channelName, ...rest]);

package/dist/gateway/gateway-client.d.ts

@@ -71,6 +71,7 @@ export declare class GatewayClient {
     private send;
     private emit;
     private scheduleReconnect;
+    private connectInBackground;
     /** Exponential backoff with full-jitter, capped at RECONNECT_CAP_MS. */
     private computeReconnectDelay;
     private installLifecycleListeners;

package/dist/gateway/gateway-client.js

@@ -142,7 +142,7 @@ class GatewayClient {
             diff_only: options?.diff_only ?? false,
         });
         if (!this.isConnected()) {
-            void this.connect();
+            this.connectInBackground();
             return;
         }
         this.send({
@@ -222,7 +222,7 @@ class GatewayClient {
     }
     syncChannel(channel) {
         if (!this.isConnected()) {
-            void this.connect();
+            this.connectInBackground();
             return;
         }
         this.send({
@@ -235,7 +235,7 @@ class GatewayClient {
     }
     sendOneShotMessage(channel, data) {
         if (!this.isConnected()) {
-            void this.connect();
+            this.connectInBackground();
             return;
         }
         this.send({
@@ -382,9 +382,16 @@ class GatewayClient {
         this.reconnectAttempts += 1;
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
-            void this.connect();
+            this.connectInBackground();
         }, delay);
     }
+    connectInBackground() {
+        void this.connect().catch((err) => {
+            this.emit("wssError", {
+                message: err instanceof Error ? err.message : String(err),
+            });
+        });
+    }
     /** Exponential backoff with full-jitter, capped at RECONNECT_CAP_MS. */
     computeReconnectDelay() {
         const exp = Math.min(RECONNECT_CAP_MS, RECONNECT_BASE_MS * 2 ** this.reconnectAttempts);
@@ -413,7 +420,7 @@ class GatewayClient {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
-        void this.connect();
+        this.connectInBackground();
     }
     channelKey(channel) {
         return `${channel.agent_id}/${channel.name}`;

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

@@ -46,6 +46,9 @@ export declare class RestClient {
     setStats(stats: DooverStatsCollector | null): void;
     request<T>(options: RequestOptions): Promise<T>;
     private doRequest;
+    private prepareAuth;
+    private prepareRequest;
+    private sendRequest;
     get<T>(path: string, query?: RequestOptions["query"], baseUrl?: string): Promise<T>;
     post<T>(path: string, body?: RequestOptions["body"], query?: RequestOptions["query"], baseUrl?: string): Promise<T>;
     put<T>(path: string, body?: RequestOptions["body"], query?: RequestOptions["query"], baseUrl?: string): Promise<T>;

package/dist/http/rest-client.js

@@ -30,20 +30,45 @@ class RestClient {
         }
     }
     async doRequest(options) {
+        await this.prepareAuth();
+        const request = this.prepareRequest(options);
+        let response = await this.sendRequest(request);
+        let payload = await this.parseResponse(response);
+        if (response.status === 401 && this.auth) {
+            const recovered = await this.auth.handleUnauthorized();
+            if (recovered) {
+                await this.prepareAuth();
+                const retryRequest = this.prepareRequest(options);
+                response = await this.sendRequest(retryRequest);
+                payload = await this.parseResponse(response);
+            }
+        }
+        if (!response.ok) {
+            throw new errors_1.DooverApiError({
+                status: response.status,
+                body: payload,
+                url: request.url,
+                method: request.method,
+                message: typeof payload === "object" &&
+                    payload !== null &&
+                    "message" in payload &&
+                    typeof payload.message === "string"
+                    ? payload.message
+                    : undefined,
+            });
+        }
+        return payload;
+    }
+    async prepareAuth() {
         if (this.auth) {
             await this.auth.ensureReady();
         }
+    }
+    prepareRequest(options) {
         const method = options.method ?? "GET";
         const url = this.buildUrl(options.baseUrl ?? this.config.dataRestUrl, options.path, options.query);
         const headers = new Headers(options.headers);
         const body = this.normalizeBody(options.body, headers);
-        // Merge auth headers.
-        if (this.auth) {
-            const authHeaders = await this.auth.getHttpHeaders();
-            for (const [key, value] of Object.entries(authHeaders)) {
-                headers.set(key, value);
-            }
-        }
         if (!options.omitSharingHeader) {
             headers.set("X-Doover-Sharing", this.config.sharing);
         }
@@ -57,29 +82,24 @@ class RestClient {
         const credentials = this.auth
             ? this.auth.getFetchCredentials()
             : "include";
+        return { url, method, headers, body, credentials };
+    }
+    async sendRequest(request) {
+        // Merge auth headers immediately before fetch so a retry can use refreshed
+        // credentials without mutating the first request's Headers instance.
+        if (this.auth) {
+            const authHeaders = await this.auth.getHttpHeaders();
+            for (const [key, value] of Object.entries(authHeaders)) {
+                request.headers.set(key, value);
+            }
+        }
         const fetchImpl = this.config.fetchImpl ?? fetch;
-        const response = await fetchImpl(url, {
-            method,
-            headers,
-            body,
-            credentials,
+        return fetchImpl(request.url, {
+            method: request.method,
+            headers: request.headers,
+            body: request.body,
+            credentials: request.credentials,
         });
-        const payload = await this.parseResponse(response);
-        if (!response.ok) {
-            throw new errors_1.DooverApiError({
-                status: response.status,
-                body: payload,
-                url,
-                method,
-                message: typeof payload === "object" &&
-                    payload !== null &&
-                    "message" in payload &&
-                    typeof payload.message === "string"
-                    ? payload.message
-                    : undefined,
-            });
-        }
-        return payload;
     }
     get(path, query, baseUrl) {
         return this.request({ path, query, baseUrl });

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,14 +99,27 @@ function useChannelMessages(identifier, options) {
         queryKey: key,
         enabled: !!agentId && !!channelName,
         staleTime: Infinity,
-        initialPageParam: initialBefore,
+        initialPageParam: (anchor ?? initialBefore),
         getNextPageParam: (lastPage) => lastPage && lastPage.length > 0 ? lastPage[0]?.id : undefined,
         queryFn: async ({ pageParam }) => {
             if (!agentId || !channelName)
                 return [];
             const id = { agentId, channelName };
+            // Resolve `before` here rather than letting the API default it, so the
+            // range store records the exact bound the request proved.
+            const before = typeof pageParam === "string"
+                ? pageParam
+                : (0, snowflake_1.generateSnowflakeIdAtTime)(new Date());
+            // Mirrors the API's own default; the store needs the limit actually applied
+            const effectiveLimit = limit ?? DEFAULT_PAGE_LIMIT;
+            if (rangeCacheable) {
+                const cached = store.read(BigInt(before), effectiveLimit);
+                if (cached)
+                    return cached;
+            }
+            const requestedAt = Date.now();
             const params = {
-                ...(typeof pageParam === "string" ? { before: pageParam } : {}),
+                before,
                 ...(limit !== undefined ? { limit } : {}),
                 ...(fields && fields.length > 0 ? { field_name: fields } : {}),
                 ...(after !== undefined ? { after } : {}),
@@ -90,6 +131,14 @@ function useChannelMessages(identifier, options) {
             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/react/useMultiAgentChannelMessages.d.ts

@@ -27,6 +27,21 @@ export interface UseMultiAgentChannelMessagesOptions {
     fields?: string[];
     /** Optional first-page `before` cursor (snowflake id). */
     initialBefore?: string;
+    /**
+     * Keep paging older automatically until `hasNextPage` is false. Each page
+     * resumes only the agents that hit `agentMessageLimit`, using their own
+     * cursors, so a noisy agent doesn't drag the quiet ones back through
+     * messages they've already returned. Almost always combined with `after`
+     * — without a lower bound this walks every agent's channel back to its
+     * first message. `maxPages` caps the walk.
+     */
+    autoPaginate?: boolean;
+    /**
+     * Hard cap on pages fetched when `autoPaginate` is set. Defaults to 20.
+     * Guards against a window that's wider than `agentMessageLimit × maxPages`
+     * messages turning into an unbounded fetch loop.
+     */
+    maxPages?: number;
     /**
      * Optional lower-bound snowflake id. Forwarded server-side so each
      * agent's pagination stops on its own once it walks past the bound —
@@ -45,7 +60,16 @@ export interface UseMultiAgentChannelMessagesOptions {
 }
 interface Page<TData> {
     results: MessageStructure<TData>[];
-    next?: string;
+    /**
+     * Per-agent resume cursors, keyed by agent id. Present (and non-empty)
+     * only for agents that hit the per-agent limit before draining the
+     * window. This is the canonical "there is more" signal.
+     */
+    next_cursors?: Record<string, string>;
+    /** Legacy single-cursor signal, for servers predating `next_cursors`. */
+    next?: string | null;
+    /** Legacy: agent ids that may have more older messages. */
+    at_limit_agent_ids?: string[];
 }
 export interface UseMultiAgentChannelMessagesResult<TData> extends Omit<UseInfiniteQueryResult<InfiniteData<Page<TData>>>, "data"> {
     messages: MessageStructure<TData>[];

package/dist/react/useMultiAgentChannelMessages.js

@@ -30,6 +30,33 @@ function multiAgentChannelMessagesQueryKey(channelName, agentIds, sources, scope
         ? [...base, scopeKey]
         : base;
 }
+function nextPageParam(lastPage) {
+    if (!lastPage)
+        return undefined;
+    const cursors = lastPage.next_cursors;
+    if (cursors) {
+        const entries = Object.entries(cursors);
+        // Present-but-empty means every agent drained its window: we're done.
+        if (entries.length === 0)
+            return undefined;
+        return {
+            agentIds: entries.map(([id]) => id),
+            agentBefore: entries.map(([, cursor]) => cursor),
+        };
+    }
+    // Legacy server: one global `before` for whichever agents were at limit.
+    // Those agents whose own cursor is older than `next` re-return a few
+    // messages we already hold — harmless, since we dedupe by id below.
+    if (typeof lastPage.next === "string" && lastPage.next) {
+        return {
+            before: lastPage.next,
+            ...(lastPage.at_limit_agent_ids?.length
+                ? { agentIds: lastPage.at_limit_agent_ids }
+                : {}),
+        };
+    }
+    return undefined;
+}
 function useMultiAgentChannelMessages(channelName, agentIds, options) {
     const client = (0, context_1.useDooverClient)();
     const queryClient = (0, react_query_1.useQueryClient)();
@@ -40,6 +67,8 @@ function useMultiAgentChannelMessages(channelName, agentIds, options) {
     const initialBefore = options?.initialBefore;
     const sources = options?.sources;
     const after = options?.after;
+    const autoPaginate = options?.autoPaginate ?? false;
+    const maxPages = options?.maxPages ?? 20;
     const key = multiAgentChannelMessagesQueryKey(channelName, agentIds, sources, {
         after,
         fields,
@@ -86,12 +115,13 @@ function useMultiAgentChannelMessages(channelName, agentIds, options) {
         queryKey: key,
         enabled: agentIds.length > 0,
         staleTime: Infinity,
-        initialPageParam: initialBefore,
-        getNextPageParam: (lastPage) => lastPage?.next,
+        initialPageParam: (initialBefore ? { before: initialBefore } : {}),
+        getNextPageParam: nextPageParam,
         queryFn: async ({ pageParam }) => {
             const params = {
-                agent_id: agentIds,
-                ...(typeof pageParam === "string" ? { before: pageParam } : {}),
+                agent_id: pageParam.agentIds ?? agentIds,
+                ...(pageParam.before ? { before: pageParam.before } : {}),
+                ...(pageParam.agentBefore ? { agent_before: pageParam.agentBefore } : {}),
                 ...(limit !== undefined ? { limit } : {}),
                 ...(agentMessageLimit !== undefined
                     ? { agent_message_limit: agentMessageLimit }
@@ -108,6 +138,36 @@ function useMultiAgentChannelMessages(channelName, agentIds, options) {
             return page;
         },
     });
-    const messages = (0, react_1.useMemo)(() => (query.data?.pages ?? []).flatMap((p) => p.results), [query.data]);
+    (0, react_1.useEffect)(() => {
+        if (!autoPaginate)
+            return;
+        if (query.isFetching || !query.hasNextPage)
+            return;
+        if ((query.data?.pages.length ?? 0) >= maxPages)
+            return;
+        query.fetchNextPage();
+    }, [
+        autoPaginate,
+        maxPages,
+        query.isFetching,
+        query.hasNextPage,
+        query.fetchNextPage,
+        query.data?.pages.length,
+    ]);
+    const messages = (0, react_1.useMemo)(() => {
+        // The legacy single-cursor path (and a live push that races a page
+        // fetch) can hand us the same message twice; keep the first copy.
+        const seen = new Set();
+        const out = [];
+        for (const page of query.data?.pages ?? []) {
+            for (const message of page.results) {
+                if (seen.has(message.id))
+                    continue;
+                seen.add(message.id);
+                out.push(message);
+            }
+        }
+        return out;
+    }, [query.data]);
     return { ...query, messages };
 }

package/dist/test/gateway-client.test.js

@@ -6,9 +6,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const chai_1 = require("chai");
 const mocha_1 = require("mocha");
 const sinon_1 = __importDefault(require("sinon"));
+const doover_auth_1 = require("../auth/doover-auth");
+const errors_1 = require("../auth/errors");
 const gateway_client_1 = require("../gateway/gateway-client");
 const snowflake_1 = require("../utils/snowflake");
 const helpers_1 = require("./helpers");
+class RejectingAuth extends doover_auth_1.DooverAuth {
+    async getHttpHeaders() {
+        return {};
+    }
+    getFetchCredentials() {
+        return "omit";
+    }
+    async prepareWebSocket(url) {
+        return { url };
+    }
+    setToken() {
+        // no-op for test
+    }
+    setRefreshToken() {
+        // no-op for test
+    }
+    async ensureReady() {
+        throw new errors_1.DooverAuthError("Authentication is invalid; sign in again");
+    }
+}
 (0, mocha_1.describe)("GatewayClient", () => {
     (0, mocha_1.beforeEach)(() => {
         helpers_1.MockWebSocket.reset();
@@ -229,6 +251,27 @@ const helpers_1 = require("./helpers");
         (0, chai_1.expect)(cancelled.calledOnce).to.equal(true);
         (0, chai_1.expect)(client.getSession()).to.equal(null);
     });
+    (0, mocha_1.it)("reports background connect auth failures without creating a socket", async () => {
+        const client = new gateway_client_1.GatewayClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            webSocketImpl: helpers_1.MockWebSocket,
+        }, new RejectingAuth());
+        const wssError = sinon_1.default.spy();
+        client.on("wssError", wssError);
+        client.subscribe({ agent_id: "a1", name: "c1" });
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+        (0, chai_1.expect)(helpers_1.MockWebSocket.instances).to.have.length(0);
+        (0, chai_1.expect)(wssError.calledOnce).to.equal(true);
+        (0, chai_1.expect)(wssError.firstCall.args[0]).to.deep.equal({
+            message: "Authentication is invalid; sign in again",
+        });
+    });
     (0, mocha_1.it)("reconnects with exponential backoff + jitter on unexpected close", () => {
         // Make jitter deterministic: Math.random() → 1 means "wait the full backoff window".
         const randomStub = sinon_1.default.stub(Math, "random").returns(1);

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-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/rest-client.test.js

@@ -6,9 +6,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const chai_1 = require("chai");
 const chai_as_promised_1 = __importDefault(require("chai-as-promised"));
 const mocha_1 = require("mocha");
+const doover_auth_1 = require("../auth/doover-auth");
 const rest_client_1 = require("../http/rest-client");
 const helpers_1 = require("./helpers");
 (0, chai_1.use)(chai_as_promised_1.default);
+class RefreshableAuth extends doover_auth_1.DooverAuth {
+    constructor() {
+        super(...arguments);
+        this.refreshCount = 0;
+    }
+    async getHttpHeaders() {
+        return { Authorization: `Bearer token-${this.refreshCount}` };
+    }
+    getFetchCredentials() {
+        return "omit";
+    }
+    async prepareWebSocket(url) {
+        return { url };
+    }
+    setToken() {
+        // no-op for test
+    }
+    setRefreshToken() {
+        // no-op for test
+    }
+    async ensureReady() {
+        // no-op for test
+    }
+    async handleUnauthorized() {
+        this.refreshCount += 1;
+        return true;
+    }
+}
 (0, mocha_1.describe)("RestClient", () => {
     (0, mocha_1.beforeEach)(() => {
         (0, helpers_1.installSessionStorageMock)();
@@ -119,6 +148,42 @@ const helpers_1 = require("./helpers");
             (0, chai_1.expect)(error.method).to.equal("GET");
         });
     });
+    (0, mocha_1.it)("refreshes auth once and retries after a 401 response", async () => {
+        const auth = new RefreshableAuth();
+        const fetchMock = (0, helpers_1.createFetchMock)(() => {
+            if (fetchMock.callCount === 1) {
+                return (0, helpers_1.createJsonResponse)({ message: "expired" }, { status: 401 });
+            }
+            return (0, helpers_1.createJsonResponse)({ ok: true });
+        });
+        const client = new rest_client_1.RestClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+        }, auth);
+        await (0, chai_1.expect)(client.get("/needs-auth")).to.eventually.deep.equal({ ok: true });
+        (0, chai_1.expect)(auth.refreshCount).to.equal(1);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(2);
+        (0, chai_1.expect)((fetchMock.getCall(0).args[1]?.headers).get("Authorization")).to.equal("Bearer token-0");
+        (0, chai_1.expect)((fetchMock.getCall(1).args[1]?.headers).get("Authorization")).to.equal("Bearer token-1");
+    });
+    (0, mocha_1.it)("does not retry a 401 response when auth refresh cannot recover", async () => {
+        const auth = new RefreshableAuth();
+        auth.handleUnauthorized = async () => false;
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({ message: "expired" }, { status: 401 }));
+        const client = new rest_client_1.RestClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+        }, auth);
+        await (0, chai_1.expect)(client.get("/needs-auth")).to.be.rejected.then((error) => {
+            (0, chai_1.expect)(error.status).to.equal(401);
+            (0, chai_1.expect)(error.message).to.equal("expired");
+        });
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
     (0, mocha_1.it)("returns text bodies when the response is not JSON", async () => {
         const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createTextResponse)("plain text"));
         const client = new rest_client_1.RestClient({

package/package.json

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