doover-js 0.8.1 → 0.9.1

package/README.md

@@ -37,6 +37,43 @@ const client = new DooverClient({
 const channels = await client.viewer.getChannels({ agentId: "123" });
 ```
 
+### Cookie usage with session refresh (browser apps behind FusionAuth)
+
+Pass `authServerUrl` — and no token material — to get a `CookieAuth` that can
+renew the session itself. The client then POSTs the hosted-backend refresh
+endpoint (`/app/refresh/` by default) when the access token has expired: before
+a request goes out, and again if one comes back 401, replaying it once.
+
+This exists because the FusionAuth React SDK's auto-refresh is a single
+`setTimeout`. A tab the browser suspends (backgrounded, machine asleep) never
+fires it, so it wakes with a dead access-token cookie and 401s on everything —
+even though the refresh token itself is usually still valid.
+
+```ts
+const client = new DooverClient({
+  dataRestUrl: "https://example.com/api",
+  controlApiUrl: "https://example.com/control",
+  dataWssUrl: "wss://example.com/gateway",
+  authServerUrl: "https://auth.example.com",
+});
+```
+
+`CookieAuth` also exposes the session state apps need for their own lifecycle
+hooks — typically a proactive refresh when a tab regains visibility:
+
+```ts
+const auth = client.auth as CookieAuth;
+
+document.addEventListener("visibilitychange", () => {
+  if (document.visibilityState !== "visible") return;
+  if (!auth.isAccessTokenStale(5 * 60_000)) return;
+  void auth.refreshAccessToken();
+});
+```
+
+Without `authServerUrl`, `CookieAuth` behaves exactly as before: ambient
+cookies, no refresh.
+
 ### Explicit token usage
 
 Pass a token directly to use bearer auth. The client will send `Authorization: Bearer <token>` on every HTTP request and use `credentials: "omit"`.

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

@@ -28,10 +28,11 @@ interface BuildAuthOptions extends AuthConfig {
  *
  * Rules:
  * 1. If `auth` is provided it is returned as-is.
- * 2. If any token-related field is present, build `DooverTokenAuth`.
+ * 2. If any token material is present, build `DooverTokenAuth`.
  * 3. If `profile` is an `AuthProfile`, use it to seed a `DooverTokenAuth`.
  * 4. If `profile` is a string, look it up via `configManager`.
- * 5. Otherwise fall back to `CookieAuth`.
+ * 5. Otherwise fall back to `CookieAuth`, refresh-capable when
+ *    `authServerUrl` is known.
  */
 export declare function buildAuth(options: BuildAuthOptions): DooverAuth;
 export {};

package/dist/auth/build-auth.js

@@ -12,15 +12,31 @@ const TOKEN_FIELDS = [
     "authServerUrl",
     "authServerClientId",
 ];
+/**
+ * The subset of `TOKEN_FIELDS` that actually implies bearer-token auth.
+ *
+ * `authServerUrl` / `authServerClientId` describe *where* to refresh, not what
+ * we hold: on their own they now configure a refresh-capable `CookieAuth`
+ * (a browser session in an app that knows its auth server), which is far more
+ * useful than the tokenless `DooverTokenAuth` they used to produce — that
+ * instance could only ever throw "missing refreshToken" on first use.
+ */
+const TOKEN_MATERIAL_FIELDS = [
+    "token",
+    "tokenExpires",
+    "refreshToken",
+    "refreshTokenId",
+];
 /**
  * Build a `DooverAuth` instance from the provided configuration.
  *
  * Rules:
  * 1. If `auth` is provided it is returned as-is.
- * 2. If any token-related field is present, build `DooverTokenAuth`.
+ * 2. If any token material is present, build `DooverTokenAuth`.
  * 3. If `profile` is an `AuthProfile`, use it to seed a `DooverTokenAuth`.
  * 4. If `profile` is a string, look it up via `configManager`.
- * 5. Otherwise fall back to `CookieAuth`.
+ * 5. Otherwise fall back to `CookieAuth`, refresh-capable when
+ *    `authServerUrl` is known.
  */
 function buildAuth(options) {
     if (options.auth) {
@@ -48,11 +64,15 @@ function buildAuth(options) {
         resolvedProfile = options.profile;
     }
     // Determine whether we need token auth.
-    const hasTokenInput = TOKEN_FIELDS.some((k) => options[k] !== undefined);
+    const hasTokenInput = TOKEN_MATERIAL_FIELDS.some((k) => options[k] !== undefined);
     const profileHasToken = resolvedProfile?.token != null;
     if (!hasTokenInput && !profileHasToken) {
-        // No token data at all — fall back to cookie auth.
-        const auth = new cookie_auth_1.CookieAuth();
+        // No token data at all — fall back to cookie auth, which can still renew
+        // the session when the app has told us where its auth server lives.
+        const auth = new cookie_auth_1.CookieAuth({
+            authServerUrl: options.authServerUrl ?? resolvedProfile?.authServerUrl ?? null,
+            fetchImpl: options.fetchImpl,
+        });
         if (resolvedProfile) {
             auth.attachProfile(resolvedProfile, options.configManager);
         }

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

@@ -1,11 +1,49 @@
 import { DooverAuth } from "./doover-auth";
+export interface CookieAuthOptions {
+    /**
+     * Base URL of the auth server that serves the hosted-backend refresh
+     * endpoint. Required for any refresh behaviour; without it `CookieAuth`
+     * behaves exactly as it always has (no refresh, no recovery).
+     */
+    authServerUrl?: string | null;
+    /** Refresh endpoint path. Defaults to `/app/refresh/`. */
+    refreshPath?: string;
+    /** Name of the access-token expiry cookie. Defaults to `app.at_exp`. */
+    accessTokenExpiryCookieName?: string;
+    /** Override `fetch` (tests, native hosts). */
+    fetchImpl?: typeof fetch;
+    /** Override how the cookie string is read. Defaults to `document.cookie`. */
+    cookieReader?: () => string;
+}
 /**
  * Cookie-based auth — the default browser strategy.
  *
  * Relies on ambient cookies (`credentials: "include"`) and does not add any
- * `Authorization` header. Token refresh is not applicable.
+ * `Authorization` header. The access token itself is httpOnly and invisible to
+ * JS; the only readable part of the session is a companion expiry cookie
+ * (`app.at_exp`).
+ *
+ * ## Why this refreshes
+ *
+ * The FusionAuth React SDK's auto-refresh is a single `setTimeout` per token.
+ * A browser that suspends the tab (backgrounded, laptop asleep) never fires it,
+ * so the tab wakes with an expired access-token cookie and every request 401s —
+ * even though the refresh token itself is usually still valid. Rather than
+ * leaving every browser app to work around that on its own, `CookieAuth`
+ * handles it whenever `authServerUrl` is configured: `ensureReady` renews an
+ * already-expired token before a request goes out (which also covers gateway
+ * reconnects, since `GatewayClient` awaits it before opening a socket), and
+ * `handleUnauthorized` lets `RestClient` replay a 401 once after a renewal.
  */
 export declare class CookieAuth extends DooverAuth {
+    private readonly authServerUrl;
+    private readonly refreshPath;
+    private readonly expiryCookieName;
+    private readonly fetchImpl;
+    private readonly cookieReader;
+    private refreshInFlight;
+    private lastAttempt;
+    constructor(options?: CookieAuthOptions);
     getHttpHeaders(): Promise<Record<string, string>>;
     getFetchCredentials(): RequestCredentials;
     prepareWebSocket(url: string, _canUseHeaders: boolean): Promise<{
@@ -14,5 +52,40 @@ export declare class CookieAuth extends DooverAuth {
     }>;
     setToken(_token: string | null, _tokenExpires?: Date | number | null): void;
     setRefreshToken(_refreshToken: string | null): void;
+    /**
+     * Renew the access token when it has already expired, so the request that
+     * follows isn't a guaranteed 401. A token that is merely close to expiry is
+     * left alone: requests must not block on a refresh they don't need, and
+     * `handleUnauthorized` is there for the race.
+     */
     ensureReady(): Promise<void>;
+    /**
+     * Called by `RestClient` after a 401. A successful refresh means the request
+     * is worth replaying once.
+     */
+    handleUnauthorized(): Promise<boolean>;
+    /** Expiry of the current access token, or `null` if there is no session. */
+    getAccessTokenExpiry(): Date | null;
+    /** True when a session cookie exists and has not yet expired. */
+    isAccessTokenValid(): boolean;
+    /**
+     * True when the access token expires within `thresholdMs` (or already has).
+     * Apps use this to decide whether a `visibilitychange` is worth a proactive
+     * refresh. False when there is no session at all — nothing to refresh.
+     */
+    isAccessTokenStale(thresholdMs?: number): boolean;
+    /**
+     * Refresh the access token, returning whether a valid one is now in place.
+     * Concurrent callers share one request, and the result is reused briefly so
+     * a burst of 401s costs a single round-trip.
+     *
+     * Safe to call directly — e.g. from a `visibilitychange` handler when
+     * {@link isAccessTokenStale} says the token is nearly up.
+     */
+    refreshAccessToken(): Promise<boolean>;
+    private canRefresh;
+    private performRefresh;
+    /** The expiry cookie in epoch milliseconds, or `null` when absent. */
+    private readExpiryCookie;
+    private readCookieString;
 }

package/dist/auth/cookie-auth.js

@@ -2,13 +2,52 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CookieAuth = void 0;
 const doover_auth_1 = require("./doover-auth");
+/** Default FusionAuth hosted-backend refresh endpoint. */
+const DEFAULT_REFRESH_PATH = "/app/refresh/";
+/** Default name of the cookie holding the access token's expiry (Unix seconds). */
+const DEFAULT_EXPIRY_COOKIE = "app.at_exp";
+/**
+ * How long a refresh result is reused. Collapses the burst of callers that all
+ * discover an expired token at the same moment (every queued request 401-ing
+ * after a tab wakes up), and — more importantly — stops a *failed* refresh from
+ * being retried in a tight loop.
+ */
+const ATTEMPT_TTL_MS = 5000;
 /**
  * Cookie-based auth — the default browser strategy.
  *
  * Relies on ambient cookies (`credentials: "include"`) and does not add any
- * `Authorization` header. Token refresh is not applicable.
+ * `Authorization` header. The access token itself is httpOnly and invisible to
+ * JS; the only readable part of the session is a companion expiry cookie
+ * (`app.at_exp`).
+ *
+ * ## Why this refreshes
+ *
+ * The FusionAuth React SDK's auto-refresh is a single `setTimeout` per token.
+ * A browser that suspends the tab (backgrounded, laptop asleep) never fires it,
+ * so the tab wakes with an expired access-token cookie and every request 401s —
+ * even though the refresh token itself is usually still valid. Rather than
+ * leaving every browser app to work around that on its own, `CookieAuth`
+ * handles it whenever `authServerUrl` is configured: `ensureReady` renews an
+ * already-expired token before a request goes out (which also covers gateway
+ * reconnects, since `GatewayClient` awaits it before opening a socket), and
+ * `handleUnauthorized` lets `RestClient` replay a 401 once after a renewal.
  */
 class CookieAuth extends doover_auth_1.DooverAuth {
+    constructor(options = {}) {
+        super();
+        this.refreshInFlight = null;
+        this.lastAttempt = null;
+        this.authServerUrl = options.authServerUrl ?? null;
+        this.refreshPath = options.refreshPath ?? DEFAULT_REFRESH_PATH;
+        this.expiryCookieName =
+            options.accessTokenExpiryCookieName ?? DEFAULT_EXPIRY_COOKIE;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.cookieReader = options.cookieReader ?? null;
+    }
+    // ------------------------------------------------------------------
+    // DooverAuth interface
+    // ------------------------------------------------------------------
     async getHttpHeaders() {
         return {};
     }
@@ -20,13 +59,142 @@ class CookieAuth extends doover_auth_1.DooverAuth {
         return { url };
     }
     setToken(_token, _tokenExpires) {
-        // No-op for cookie auth.
+        // No-op for cookie auth — the token lives in an httpOnly cookie.
     }
     setRefreshToken(_refreshToken) {
-        // No-op for cookie auth.
+        // No-op for cookie auth — the refresh token lives in an httpOnly cookie.
     }
+    /**
+     * Renew the access token when it has already expired, so the request that
+     * follows isn't a guaranteed 401. A token that is merely close to expiry is
+     * left alone: requests must not block on a refresh they don't need, and
+     * `handleUnauthorized` is there for the race.
+     */
     async ensureReady() {
-        // Nothing to prepare for cookie auth.
+        if (!this.canRefresh()) {
+            return;
+        }
+        if (this.isAccessTokenValid()) {
+            return;
+        }
+        // A failed refresh is not fatal here — let the request go out and be
+        // handled by `handleUnauthorized` / the caller's error handling.
+        await this.refreshAccessToken();
+    }
+    /**
+     * Called by `RestClient` after a 401. A successful refresh means the request
+     * is worth replaying once.
+     */
+    async handleUnauthorized() {
+        if (!this.canRefresh()) {
+            return false;
+        }
+        return this.refreshAccessToken();
+    }
+    // ------------------------------------------------------------------
+    // Public helpers — apps need these for their own lifecycle hooks
+    // ------------------------------------------------------------------
+    /** Expiry of the current access token, or `null` if there is no session. */
+    getAccessTokenExpiry() {
+        const expiryMs = this.readExpiryCookie();
+        return expiryMs == null ? null : new Date(expiryMs);
+    }
+    /** True when a session cookie exists and has not yet expired. */
+    isAccessTokenValid() {
+        const expiryMs = this.readExpiryCookie();
+        return expiryMs != null && expiryMs > Date.now();
+    }
+    /**
+     * True when the access token expires within `thresholdMs` (or already has).
+     * Apps use this to decide whether a `visibilitychange` is worth a proactive
+     * refresh. False when there is no session at all — nothing to refresh.
+     */
+    isAccessTokenStale(thresholdMs = 60000) {
+        const expiryMs = this.readExpiryCookie();
+        if (expiryMs == null) {
+            return false;
+        }
+        return expiryMs - Date.now() < thresholdMs;
+    }
+    /**
+     * Refresh the access token, returning whether a valid one is now in place.
+     * Concurrent callers share one request, and the result is reused briefly so
+     * a burst of 401s costs a single round-trip.
+     *
+     * Safe to call directly — e.g. from a `visibilitychange` handler when
+     * {@link isAccessTokenStale} says the token is nearly up.
+     */
+    async refreshAccessToken() {
+        if (!this.canRefresh()) {
+            return false;
+        }
+        if (this.refreshInFlight) {
+            return this.refreshInFlight;
+        }
+        // No expiry cookie means we were never logged in, or have since logged
+        // out. The refresh endpoint would just 400.
+        if (this.readExpiryCookie() == null) {
+            return false;
+        }
+        if (this.lastAttempt && Date.now() - this.lastAttempt.at < ATTEMPT_TTL_MS) {
+            return this.lastAttempt.result;
+        }
+        const inFlight = this.performRefresh().then((result) => {
+            this.lastAttempt = { result, at: Date.now() };
+            this.refreshInFlight = null;
+            return result;
+        });
+        this.refreshInFlight = inFlight;
+        return inFlight;
+    }
+    // ------------------------------------------------------------------
+    // Internal
+    // ------------------------------------------------------------------
+    canRefresh() {
+        return this.authServerUrl != null && this.authServerUrl !== "";
+    }
+    async performRefresh() {
+        const url = `${this.authServerUrl}${this.refreshPath}`;
+        try {
+            const response = await this.fetchImpl(url, {
+                method: "POST",
+                credentials: "include",
+                headers: { "Content-Type": "text/plain" },
+            });
+            return response.ok;
+        }
+        catch {
+            // Offline, DNS failure, blocked request — indistinguishable from here,
+            // and all mean "no new token".
+            return false;
+        }
+    }
+    /** The expiry cookie in epoch milliseconds, or `null` when absent. */
+    readExpiryCookie() {
+        const cookieString = this.readCookieString();
+        if (!cookieString) {
+            return null;
+        }
+        const match = cookieString.match(new RegExp(`(?:^|;\\s*)${escapeRegExp(this.expiryCookieName)}=([^;]+)`));
+        if (!match) {
+            return null;
+        }
+        // Stored as Unix *seconds* (matching the FusionAuth SDK's own parser);
+        // callers compare against Date.now(), so normalise to milliseconds.
+        const seconds = parseInt(decodeURIComponent(match[1]), 10);
+        return Number.isFinite(seconds) ? seconds * 1000 : null;
+    }
+    readCookieString() {
+        if (this.cookieReader) {
+            return this.cookieReader();
+        }
+        if (typeof document === "undefined") {
+            return null;
+        }
+        return document.cookie;
     }
 }
 exports.CookieAuth = CookieAuth;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export type { DataClient, AgentScope, DataClientStatus, DataClientConnectionStat
 export type { SourceProvenance, SourceProvenanceViaRest, SourceProvenanceViaGateway, } from "./types/provenance";
 export { DooverAuth } from "./auth/doover-auth";
 export { CookieAuth } from "./auth/cookie-auth";
+export type { CookieAuthOptions } from "./auth/cookie-auth";
 export { DooverTokenAuth } from "./auth/doover-token-auth";
 export { AuthProfile } from "./auth/auth-profile";
 export type { AuthProfileData } from "./auth/auth-profile";

package/dist/react/messageRangeStore.d.ts

@@ -65,6 +65,12 @@ export declare class ChannelRangeStore {
      * between them, and claiming coverage across it would hide messages forever.
      */
     recordLive(message: MessageStructure): void;
+    /**
+     * Replace a message already held by one or more proven ranges. MessageUpdate
+     * carries the complete server representation, so both data and attachments
+     * supersede the cached create-time copy without changing range coverage.
+     */
+    recordUpdate(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

package/dist/react/messageRangeStore.js

@@ -69,6 +69,18 @@ class ChannelRangeStore {
         if (id >= tip.hi)
             tip.hi = id + 1n;
     }
+    /**
+     * Replace a message already held by one or more proven ranges. MessageUpdate
+     * carries the complete server representation, so both data and attachments
+     * supersede the cached create-time copy without changing range coverage.
+     */
+    recordUpdate(message) {
+        for (const segment of this.segments) {
+            const index = segment.messages.findIndex((item) => item.id === message.id);
+            if (index >= 0)
+                segment.messages[index] = message;
+        }
+    }
     /**
      * 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

package/dist/react/useChannelMessages.d.ts

@@ -75,8 +75,9 @@ export interface UseChannelMessagesResult<TData> extends Omit<UseInfiniteQueryRe
 }
 /**
  * Paginated infinite query over `DooverDataProvider.getMessages`, with live
- * `messageCreate` pushes prepended/appended to the newest page. The "next"
- * page fetches older messages (cursor = oldest-loaded message id).
+ * `messageCreate` pushes are appended to the newest page and `messageUpdate`
+ * pushes replace matching cached messages. The "next" page fetches older
+ * messages (cursor = oldest-loaded message id).
  */
 export declare function useChannelMessages<TData = unknown>(identifier: ChannelIdentifier, options?: UseChannelMessagesOptions): UseChannelMessagesResult<TData>;
 export {};

package/dist/react/useChannelMessages.js

@@ -33,8 +33,9 @@ function channelMessagesQueryKey(agentId, channelName, fields, sources, anchor)
 const DEFAULT_PAGE_LIMIT = 10;
 /**
  * Paginated infinite query over `DooverDataProvider.getMessages`, with live
- * `messageCreate` pushes prepended/appended to the newest page. The "next"
- * page fetches older messages (cursor = oldest-loaded message id).
+ * `messageCreate` pushes are appended to the newest page and `messageUpdate`
+ * pushes replace matching cached messages. The "next" page fetches older
+ * messages (cursor = oldest-loaded message id).
  */
 function useChannelMessages(identifier, options) {
     const client = (0, context_1.useDooverClient)();
@@ -94,7 +95,40 @@ function useChannelMessages(identifier, options) {
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [queryClient, agentId, channelName, fields?.join(","), sources?.join(",")]);
-    (0, useChannelSubscription_1.useChannelSubscription)(liveUpdates ? identifier : undefined, { onMessage });
+    const onMessageUpdate = (0, react_1.useCallback)((message) => {
+        // A filtered stream must not accept an update that does not belong to it.
+        // Newly qualifying messages are left for a refetch because inserting one
+        // into an arbitrary cursor page could invalidate that page's boundaries.
+        if (fields && fields.length > 0) {
+            const data = message.data;
+            if (!data ||
+                typeof data !== "object" ||
+                !fields.some((field) => field in data)) {
+                return;
+            }
+        }
+        if (rangeCacheable)
+            store.recordUpdate(message);
+        queryClient.setQueryData(key, (current) => {
+            if (!current)
+                return current;
+            let changed = false;
+            const typed = message;
+            const pages = current.pages.map((page) => page.map((item) => {
+                if (item.id !== typed.id)
+                    return item;
+                changed = true;
+                return typed;
+            }));
+            return changed ? { ...current, pages } : current;
+        });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, agentId, channelName, fields?.join(","), sources?.join(",")]);
+    (0, useChannelSubscription_1.useChannelSubscription)(liveUpdates ? identifier : undefined, {
+        onMessage,
+        onMessageUpdate,
+    });
     const query = (0, react_query_1.useInfiniteQuery)({
         queryKey: key,
         enabled: !!agentId && !!channelName,

package/dist/test/auth.test.js

@@ -50,6 +50,21 @@ class MemoryProfileStore {
     }
 }
 // ---------------------------------------------------------------------------
+// Helpers: cookie-auth session state
+// ---------------------------------------------------------------------------
+/** An `app.at_exp` cookie string expiring `secondsFromNow` from now. */
+function expiryCookie(secondsFromNow) {
+    return `app.at_exp=${Math.floor(Date.now() / 1000) + secondsFromNow}`;
+}
+/** A refresh-capable CookieAuth over a fixed cookie string. */
+function cookieAuth(options) {
+    return new cookie_auth_1.CookieAuth({
+        authServerUrl: "https://auth.example.com",
+        fetchImpl: (options.fetchMock ?? (0, helpers_1.createFetchMock)()),
+        cookieReader: () => options.cookie,
+    });
+}
+// ---------------------------------------------------------------------------
 // CookieAuth
 // ---------------------------------------------------------------------------
 (0, mocha_1.describe)("CookieAuth", () => {
@@ -67,6 +82,127 @@ class MemoryProfileStore {
         const auth = new cookie_auth_1.CookieAuth();
         await auth.ensureReady(); // should not throw
     });
+    (0, mocha_1.it)("does not refresh when no authServerUrl is configured", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)();
+        const auth = new cookie_auth_1.CookieAuth({
+            fetchImpl: fetchMock,
+            cookieReader: () => expiryCookie(-60),
+        });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        await auth.ensureReady();
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(0);
+    });
+    // -- Session inspection ---------------------------------------------------
+    (0, mocha_1.it)("reads the expiry cookie", () => {
+        const auth = cookieAuth({ cookie: expiryCookie(3600) });
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(true);
+        (0, chai_1.expect)(auth.isAccessTokenStale()).to.equal(false);
+        (0, chai_1.expect)(auth.getAccessTokenExpiry()).to.be.instanceOf(Date);
+    });
+    (0, mocha_1.it)("treats an expired cookie as invalid but refreshable", () => {
+        const auth = cookieAuth({ cookie: expiryCookie(-60) });
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(false);
+        (0, chai_1.expect)(auth.isAccessTokenStale()).to.equal(true);
+    });
+    (0, mocha_1.it)("reports a near-expiry token as stale while still valid", () => {
+        const auth = cookieAuth({ cookie: expiryCookie(60) });
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(true);
+        (0, chai_1.expect)(auth.isAccessTokenStale(5 * 60000)).to.equal(true);
+    });
+    (0, mocha_1.it)("reports no session when the cookie is absent", () => {
+        const auth = cookieAuth({ cookie: "other=1" });
+        (0, chai_1.expect)(auth.getAccessTokenExpiry()).to.equal(null);
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(false);
+        // Nothing to refresh — must not read as "stale".
+        (0, chai_1.expect)(auth.isAccessTokenStale()).to.equal(false);
+    });
+    (0, mocha_1.it)("ignores a non-numeric expiry cookie", () => {
+        const auth = cookieAuth({ cookie: "app.at_exp=garbage" });
+        (0, chai_1.expect)(auth.getAccessTokenExpiry()).to.equal(null);
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(false);
+    });
+    (0, mocha_1.it)("honours a custom expiry cookie name", () => {
+        const auth = new cookie_auth_1.CookieAuth({
+            authServerUrl: "https://auth.example.com",
+            accessTokenExpiryCookieName: "custom.exp",
+            cookieReader: () => `custom.exp=${Math.floor(Date.now() / 1000) + 3600}`,
+        });
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(true);
+    });
+    // -- Refresh behaviour ----------------------------------------------------
+    (0, mocha_1.it)("refreshes an expired token via the hosted-backend endpoint", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(true);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+        (0, chai_1.expect)(fetchMock.firstCall.args[0]).to.equal("https://auth.example.com/app/refresh/");
+        const init = fetchMock.firstCall.args[1];
+        (0, chai_1.expect)(init.method).to.equal("POST");
+        (0, chai_1.expect)(init.credentials).to.equal("include");
+    });
+    (0, mocha_1.it)("honours a custom refresh path", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = new cookie_auth_1.CookieAuth({
+            authServerUrl: "https://auth.example.com",
+            refreshPath: "/proxy/renew",
+            fetchImpl: fetchMock,
+            cookieReader: () => expiryCookie(-60),
+        });
+        await auth.refreshAccessToken();
+        (0, chai_1.expect)(fetchMock.firstCall.args[0]).to.equal("https://auth.example.com/proxy/renew");
+    });
+    (0, mocha_1.it)("reports failure when the refresh endpoint rejects", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}, { status: 400 }));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+    });
+    (0, mocha_1.it)("reports failure when the refresh request throws", async () => {
+        const fetchMock = sinon_1.default.stub().rejects(new Error("offline"));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+    });
+    (0, mocha_1.it)("skips the refresh call when there is no session cookie", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: "", fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(0);
+    });
+    (0, mocha_1.it)("collapses concurrent refreshes onto one request", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        const results = await Promise.all([
+            auth.handleUnauthorized(),
+            auth.handleUnauthorized(),
+            auth.handleUnauthorized(),
+        ]);
+        (0, chai_1.expect)(results).to.deep.equal([true, true, true]);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+    (0, mocha_1.it)("reuses a recent failure instead of retrying in a loop", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}, { status: 400 }));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+    (0, mocha_1.it)("ensureReady refreshes an expired token before the request goes out", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        await auth.ensureReady();
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+    (0, mocha_1.it)("ensureReady leaves a valid token alone", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: expiryCookie(30), fetchMock });
+        await auth.ensureReady();
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(0);
+    });
+    (0, mocha_1.it)("ensureReady does not reject when the refresh fails", async () => {
+        const fetchMock = sinon_1.default.stub().rejects(new Error("offline"));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        await auth.ensureReady(); // should not throw
+    });
 });
 // ---------------------------------------------------------------------------
 // DooverTokenAuth
@@ -310,6 +446,24 @@ class MemoryProfileStore {
     (0, mocha_1.it)("builds CookieAuth when no token-related input is present", () => {
         (0, chai_1.expect)((0, build_auth_1.buildAuth)({})).to.be.instanceOf(cookie_auth_1.CookieAuth);
     });
+    (0, mocha_1.it)("builds a refresh-capable CookieAuth from authServerUrl alone", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = (0, build_auth_1.buildAuth)({
+            authServerUrl: "https://auth.example.com",
+            fetchImpl: fetchMock,
+        });
+        // authServerUrl says where to refresh; it is not token material, so this
+        // stays cookie auth rather than becoming a tokenless DooverTokenAuth.
+        (0, chai_1.expect)(auth).to.be.instanceOf(cookie_auth_1.CookieAuth);
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false); // no session cookie
+    });
+    (0, mocha_1.it)("still builds DooverTokenAuth when token material accompanies authServerUrl", () => {
+        const auth = (0, build_auth_1.buildAuth)({
+            authServerUrl: "https://auth.example.com",
+            refreshToken: "rt",
+        });
+        (0, chai_1.expect)(auth).to.be.instanceOf(doover_token_auth_1.DooverTokenAuth);
+    });
     (0, mocha_1.it)("builds DooverTokenAuth when token is provided", () => {
         const auth = (0, build_auth_1.buildAuth)({ token: "tok" });
         (0, chai_1.expect)(auth).to.be.instanceOf(doover_token_auth_1.DooverTokenAuth);
@@ -506,6 +660,39 @@ class MemoryProfileStore {
         (0, chai_1.expect)(headers.get("Authorization")).to.equal(null);
         (0, chai_1.expect)(init?.credentials).to.equal("include");
     });
+    (0, mocha_1.it)("refreshes and replays a 401 with refresh-capable cookie auth", async () => {
+        let itemsCalls = 0;
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url === "https://auth.example.com/app/refresh/") {
+                return (0, helpers_1.createJsonResponse)({});
+            }
+            itemsCalls += 1;
+            // First attempt uses the dead cookie; the replay succeeds.
+            return itemsCalls === 1
+                ? (0, helpers_1.createJsonResponse)({ detail: "expired" }, { status: 401 })
+                : (0, helpers_1.createJsonResponse)({ items: [] });
+        });
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        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);
+        const result = await client.get("/items");
+        (0, chai_1.expect)(result).to.deep.equal({ items: [] });
+        (0, chai_1.expect)(itemsCalls).to.equal(2);
+    });
+    (0, mocha_1.it)("surfaces the 401 when cookie auth cannot refresh", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({ detail: "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,
+        }, new cookie_auth_1.CookieAuth());
+        await (0, chai_1.expect)(client.get("/items")).to.be.rejected;
+    });
     (0, mocha_1.it)("uses credentials: include when no auth is provided (backward compat)", async () => {
         const fetchMock = (0, helpers_1.createFetchMock)();
         const client = new rest_client_1.RestClient({

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

@@ -95,6 +95,22 @@ const ids = (messages) => (messages ?? []).map((m) => m.id);
         (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)("replaces an updated message without changing range coverage", () => {
+        const page = makeMessages(5, 20);
+        store.record({ before: idAt(0), limit: 5, page });
+        const before = store.snapshot();
+        const updated = {
+            ...page[2],
+            data: { i: 2, analysed_by: "detector" },
+            attachments: [{ id: "updated-image" }],
+        };
+        store.recordUpdate(updated);
+        const read = store.read(idAt(0), 5);
+        (0, chai_1.expect)(read[2]).to.equal(updated);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page));
+        (0, chai_1.expect)(store.snapshot().map(({ lo, hi, atStart }) => ({ lo, hi, atStart })))
+            .to.deep.equal(before.map(({ lo, hi, atStart }) => ({ lo, hi, atStart })));
+    });
     (0, mocha_1.it)("keeps disjoint ranges apart rather than claiming the gap", () => {
         const ancient = makeMessages(5, 500);
         const recent = makeMessages(5, 20);

package/dist/test/react.test.js

@@ -208,7 +208,7 @@ function wrapper(client) {
         const cached = queryClient.getQueryData((0, react_2.channelAggregateQueryKey)("a1", "ui_cmds"));
         (0, chai_1.expect)(cached).to.deep.include({ data: { y: 2 }, attachments: [] });
     });
-    (0, mocha_1.it)("useChannelMessages paginates and prepends on live messageCreate", async () => {
+    (0, mocha_1.it)("useChannelMessages applies live creates and updates", async () => {
         const oldId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2025-12-31T23:59:00.000Z"));
         const newId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:01.000Z"));
         const liveId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:02.000Z"));
@@ -269,6 +269,28 @@ function wrapper(client) {
             newId,
             liveId,
         ]));
+        await (0, react_1.act)(async () => {
+            helpers_1.MockWebSocket.instances[0].receive({
+                op: 0,
+                t: "MessageUpdate",
+                d: {
+                    message: {
+                        id: newId,
+                        author_id: "u1",
+                        channel: { agent_id: "a1", name: "notes" },
+                        data: { v: 22, analysed_by: "detector" },
+                        attachments: [{ id: "analysed-image" }],
+                    },
+                    request_data: {},
+                },
+            });
+        });
+        await (0, react_1.waitFor)(() => {
+            const updated = result.current.messages.find((message) => message.id === newId);
+            (0, chai_1.expect)(updated?.data).to.deep.equal({ v: 22, analysed_by: "detector" });
+            (0, chai_1.expect)(updated?.attachments).to.have.length(1);
+            (0, chai_1.expect)(updated?.attachments?.[0]).to.deep.include({ id: "analysed-image" });
+        });
     });
     (0, mocha_1.it)("useChannelMessage seeds via REST and patches on MessageUpdate", async () => {
         const messageId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00.000Z"));

package/package.json

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