doover-js 0.12.1 → 0.13.1

package/README.md

@@ -389,3 +389,58 @@ const statuses = useClientStatus();
 `*Api` resource methods accept either positional arguments or a `ChannelIdentifier` / `{ agentId }` object on every call form.
 
 `client.rpc.send` adds optional `signal: AbortSignal` and `timeoutMs: number` and rejects with `DooverRpcError` (with `.status` and `.request`) instead of the bare status string.
+
+## Network availability and offline cache status
+
+`useOfflineStatus()` reports browser network changes for every client, including
+`DooverClient` without an offline cache. It updates on initial offline load and
+online/offline events even when no requests run. `online` describes the platform's
+network signal; it does not prove that the Doover server is reachable.
+`useClientStatus()` separately reports the gateway connection.
+
+`OfflineDataClient` adds cache metadata such as `isOfflineFallback` and `cachedAt`.
+These fields describe the last cache operation, not every item on the page. Its
+snapshots retain object identity between changes for React external-store hooks.
+Network transitions preserve cache metadata until another operation updates it.
+
+Both clients accept `networkStatus`, a `NetworkStatusSource` with `getSnapshot()`
+and `subscribe(listener)`. The offline wrapper inherits its underlying client's
+source unless overridden. Sources return a stable `{ online, at }` snapshot and
+notify subscribers when it changes. The exported `browserNetworkStatus` is the
+default; it attaches browser listeners while subscribed and releases them after
+the last unsubscribe. Outside a browser it assumes online when no platform
+signal exists.
+
+Native applications can pass `createNetworkStatusStore(initialOnline)` and call
+its `setOnline(online)` method from platform network callbacks. Gateway failures
+must not update this source. The legacy `OfflineDataClient.isOnline` callback
+remains supported for request-time checks; a reactive source also updates the UI
+between requests.
+
+### Data service reachability
+
+`useServiceReachability()` returns `"unknown"`, `"reachable"`, or `"unreachable"`.
+It observes `client.reachability`, independently of `navigator.onLine` and the
+WebSocket's open state. `OfflineDataClient` forwards the wrapped client's source.
+Clients without this source return `"unknown"`; multiplex consumers can observe
+the relevant member client rather than assuming all services share connectivity.
+
+Checks run only while this hook or a direct `client.reachability.subscribe(...)`
+subscription is mounted. Multiple observers share one loop. Existing
+`onStatusChange` subscriptions do not start checks. The final unsubscribe cancels
+the timer and probe. Each probe has a five-second deadline. Healthy clients check
+every 30 seconds; unreachable clients retry every five seconds. Browser offline
+events suspend probes; online events trigger a fresh check.
+
+A REST transport failure also schedules a check, coalescing simultaneous failures
+and limiting probes to one per second. It does not retry or queue the failed
+request, including commands. HTTP error responses and response parsing failures
+do not trigger these checks.
+
+The probe sends a credential-free `HEAD` request to `dataRestUrl` with
+`cache: "no-store"`. Any HTTP response, including 401, 404, or 500, proves network
+reachability; this is not an application health check. DNS, CORS, transport errors,
+and timeouts report unreachable. A deployment must allow CORS on its probe URL.
+Set `reachability: { probeUrl: "https://data.example.com/health" }` to use a different
+read-only endpoint, or `reachability: false` to disable the source. The configured
+`fetchImpl` also handles probes, including in native applications.

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

@@ -1,3 +1,5 @@
+import type { ServiceReachabilitySource } from "./service-reachability.js";
+import type { NetworkStatusSource } from "./network-status.js";
 import type { AgentsApi } from "../apis/agents-api.js";
 import type { AggregatesApi } from "../apis/aggregates-api.js";
 import type { AlarmsApi } from "../apis/alarms-api.js";
@@ -76,6 +78,10 @@ export interface DataClientStatus {
  * later; the invariant is that `DooverClient` always satisfies it.
  */
 export interface DataClient {
+    /** Optional platform source; React hooks otherwise use browser network status. */
+    readonly networkStatus?: NetworkStatusSource;
+    /** Optional data API reachability. Polls only while explicitly subscribed. */
+    readonly reachability?: ServiceReachabilitySource;
     readonly agents: AgentsApiLike;
     readonly channels: ChannelsApiLike;
     readonly messages: MessagesApiLike;

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

@@ -1,3 +1,5 @@
+import { type ServiceReachabilitySource } from "./service-reachability.js";
+import { type NetworkStatusSource } from "./network-status.js";
 import { OrganisationsApi } from "../apis/organisations-api.js";
 import type { DooverAuth } from "../auth/doover-auth.js";
 import { RestClient, type DooverClientConfig } from "../http/rest-client.js";
@@ -6,6 +8,8 @@ import { type Capability } from "./capabilities.js";
 import type { AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, AgentScope, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client.js";
 import { DooverStatsCollector, type DooverStatsSnapshot } from "./stats.js";
 export declare class DooverClient implements DataClient {
+    readonly networkStatus: NetworkStatusSource;
+    readonly reachability: ServiceReachabilitySource | undefined;
     readonly auth: DooverAuth;
     readonly rest: RestClient;
     readonly viewer: DooverDataProvider;

package/dist/client/doover-client.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DooverClient = void 0;
+const service_reachability_js_1 = require("./service-reachability.js");
+const network_status_js_1 = require("./network-status.js");
 const agents_api_js_1 = require("../apis/agents-api.js");
 const aggregates_api_js_1 = require("../apis/aggregates-api.js");
 const alarms_api_js_1 = require("../apis/alarms-api.js");
@@ -25,6 +27,7 @@ const stats_js_1 = require("./stats.js");
 const ALL_CAPS_SET = new Set(capabilities_js_1.ALL_CAPABILITIES);
 class DooverClient {
     constructor(config) {
+        this.networkStatus = config.networkStatus ?? network_status_js_1.browserNetworkStatus;
         this.auth = (0, build_auth_js_1.buildAuth)({
             auth: config.auth,
             profile: config.profile,
@@ -48,7 +51,9 @@ class DooverClient {
             },
         };
         const stamper = new provenance_js_1.ProvenanceStamper(this.identity);
-        this.rest = new rest_client_js_1.RestClient(config, this.auth);
+        const reachability = config.reachability === false ? undefined : new service_reachability_js_1.ServiceReachabilityMonitor(config.reachability?.probeUrl ?? config.dataRestUrl, this.networkStatus, config.fetchImpl ?? ((...args) => fetch(...args)));
+        this.reachability = reachability;
+        this.rest = new rest_client_js_1.RestClient(config, this.auth, () => reachability?.requestFailed());
         this.gatewayImpl = new gateway_client_js_1.GatewayClient(config, this.auth);
         this.gatewayImpl.setProvenanceHook((value, ctx) => stamper.stampGatewayEvent(value, ctx));
         this.gateway = this.gatewayImpl;

package/dist/client/index.d.ts

@@ -2,3 +2,6 @@ export { DooverClient } from "./doover-client.js";
 export { getDooverClient, peekDooverClient, resetDooverClient } from "./singleton.js";
 export type { DooverClientConfig } from "../http/rest-client.js";
 export type * from "./data-client.js";
+export { browserNetworkStatus, createNetworkStatusStore } from "./network-status.js";
+export type { NetworkStatusSource, NetworkStatusSnapshot } from "./network-status.js";
+export type { ServiceReachability, ServiceReachabilitySource, ReachabilityOptions } from "./service-reachability.js";

package/dist/client/index.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.DooverClient = void 0;
+exports.createNetworkStatusStore = exports.browserNetworkStatus = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.DooverClient = void 0;
 var doover_client_js_1 = require("./doover-client.js");
 Object.defineProperty(exports, "DooverClient", { enumerable: true, get: function () { return doover_client_js_1.DooverClient; } });
 var singleton_js_1 = require("./singleton.js");
 Object.defineProperty(exports, "getDooverClient", { enumerable: true, get: function () { return singleton_js_1.getDooverClient; } });
 Object.defineProperty(exports, "peekDooverClient", { enumerable: true, get: function () { return singleton_js_1.peekDooverClient; } });
 Object.defineProperty(exports, "resetDooverClient", { enumerable: true, get: function () { return singleton_js_1.resetDooverClient; } });
+var network_status_js_1 = require("./network-status.js");
+Object.defineProperty(exports, "browserNetworkStatus", { enumerable: true, get: function () { return network_status_js_1.browserNetworkStatus; } });
+Object.defineProperty(exports, "createNetworkStatusStore", { enumerable: true, get: function () { return network_status_js_1.createNetworkStatusStore; } });

package/dist/client/network-status.d.ts

@@ -0,0 +1,17 @@
+/** Network availability is independent of the Doover gateway connection. */
+export interface NetworkStatusSnapshot {
+    readonly online: boolean;
+    readonly at: number;
+}
+/** Snapshots must retain their identity until the status changes. */
+export interface NetworkStatusSource {
+    getSnapshot(): NetworkStatusSnapshot;
+    subscribe(listener: () => void): () => void;
+}
+/** A source that native network callbacks can update. */
+export declare function createNetworkStatusStore(initialOnline: boolean): {
+    getSnapshot: () => NetworkStatusSnapshot;
+    subscribe(listener: () => void): () => void;
+    setOnline(online: boolean): void;
+};
+export declare const browserNetworkStatus: NetworkStatusSource;

package/dist/client/network-status.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserNetworkStatus = void 0;
+exports.createNetworkStatusStore = createNetworkStatusStore;
+/** A source that native network callbacks can update. */
+function createNetworkStatusStore(initialOnline) {
+    let snapshot = { online: initialOnline, at: Date.now() };
+    const listeners = new Set();
+    return {
+        getSnapshot: () => snapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        setOnline(online) {
+            if (online === snapshot.online)
+                return;
+            snapshot = { online, at: Date.now() };
+            listeners.forEach((listener) => listener());
+        },
+    };
+}
+function readBrowserOnline() {
+    const nav = typeof window !== "undefined" ? window.navigator
+        : typeof navigator !== "undefined" ? navigator : undefined;
+    return typeof nav?.onLine === "boolean" ? nav.onLine : true;
+}
+// Listen only while observed. getSnapshot also refreshes after periods with
+// no subscribers, including initial offline loads. No browser globals at import.
+function createBrowserNetworkStatus() {
+    let snapshot = { online: true, at: 0 };
+    const listeners = new Set();
+    let detach;
+    const getSnapshot = () => {
+        const online = readBrowserOnline();
+        if (online !== snapshot.online)
+            snapshot = { online, at: Date.now() };
+        return snapshot;
+    };
+    const refresh = () => {
+        getSnapshot();
+        // A request may already have read the new snapshot before this event.
+        // Still notify mounted consumers; React ignores an unchanged snapshot.
+        listeners.forEach((listener) => listener());
+    };
+    return {
+        getSnapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            if (!detach && typeof window !== "undefined") {
+                const target = window;
+                target.addEventListener("online", refresh);
+                target.addEventListener("offline", refresh);
+                detach = () => {
+                    target.removeEventListener("online", refresh);
+                    target.removeEventListener("offline", refresh);
+                };
+            }
+            refresh();
+            return () => {
+                listeners.delete(listener);
+                if (!listeners.size) {
+                    detach?.();
+                    detach = undefined;
+                }
+            };
+        },
+    };
+}
+exports.browserNetworkStatus = createBrowserNetworkStatus();

package/dist/client/offline-cache.d.ts

@@ -1,3 +1,5 @@
+import type { ServiceReachabilitySource } from "./service-reachability.js";
+import { type NetworkStatusSource } from "./network-status.js";
 import type { AgentScope, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client.js";
 import type { Capability } from "./capabilities.js";
 export declare const DEFAULT_OFFLINE_RETENTION_MS: number;
@@ -83,18 +85,23 @@ export declare class MemoryOfflineStorageAdapter implements OfflineStorageAdapte
     deleteBlob(key: string): Promise<void>;
 }
 export interface OfflineDataClientOptions {
+    /** Reactive platform signal; defaults to the wrapped client's source. */
+    networkStatus?: NetworkStatusSource;
     client: DataClient;
     storage: OfflineStorageAdapter;
     scope: OfflineCacheScope;
     policies?: OfflineChannelPolicy[];
     defaultRetentionMs?: number;
     /**
-     * Apps may provide their own reachability signal. When omitted, the wrapper
-     * uses `navigator.onLine` when present and otherwise assumes online.
+     * Legacy pull-only override. Prefer networkStatus for reactive updates
+     * between requests. When omitted, the wrapper reads its network source.
      */
     isOnline?: () => boolean;
 }
 export declare class OfflineDataClient implements DataClient {
+    readonly networkStatus: NetworkStatusSource;
+    readonly reachability: ServiceReachabilitySource | undefined;
+    private unsubscribeNetwork?;
     readonly agents: AgentsApiLike;
     readonly channels: ChannelsApiLike;
     readonly messages: MessagesApiLike;

package/dist/client/offline-cache.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfflineDataClient = exports.MemoryOfflineStorageAdapter = exports.DEFAULT_OFFLINE_RETENTION_MS = void 0;
+const network_status_js_1 = require("./network-status.js");
 const errors_js_1 = require("./errors.js");
 const request_options_js_1 = require("./request-options.js");
 exports.DEFAULT_OFFLINE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
@@ -57,6 +58,8 @@ class OfflineDataClient {
         this.offlineStatus = INITIAL_OFFLINE_STATUS;
         this.persistQueue = Promise.resolve();
         this.client = options.client;
+        this.reachability = options.client.reachability;
+        this.networkStatus = options.networkStatus ?? options.client.networkStatus ?? network_status_js_1.browserNetworkStatus;
         this.storage = options.storage;
         this.scope = options.scope;
         this.defaultRetentionMs = options.defaultRetentionMs ?? exports.DEFAULT_OFFLINE_RETENTION_MS;
@@ -90,19 +93,30 @@ class OfflineDataClient {
         return this.policies;
     }
     getOfflineStatus() {
-        return {
-            ...this.offlineStatus,
-            online: this.isOnline(),
-        };
+        const online = this.isOnline();
+        if (online !== this.offlineStatus.online) {
+            this.offlineStatus = { ...this.offlineStatus, online, at: Date.now() };
+        }
+        return this.offlineStatus;
     }
     onOfflineStatusChange(listener) {
         this.offlineStatusListeners.add(listener);
+        if (!this.unsubscribeNetwork) {
+            this.unsubscribeNetwork = this.networkStatus.subscribe(() => {
+                const status = this.getOfflineStatus();
+                this.offlineStatusListeners.forEach((callback) => callback(status));
+            });
+        }
         let active = true;
         return () => {
             if (!active)
                 return;
             active = false;
             this.offlineStatusListeners.delete(listener);
+            if (!this.offlineStatusListeners.size) {
+                this.unsubscribeNetwork?.();
+                this.unsubscribeNetwork = undefined;
+            }
         };
     }
     async clearScope(scope = this.scope) {
@@ -682,8 +696,7 @@ class OfflineDataClient {
     isOnline() {
         if (this.isOnlineFn)
             return this.isOnlineFn();
-        const nav = globalThis.navigator;
-        return nav?.onLine ?? true;
+        return this.networkStatus.getSnapshot().online;
     }
     setOfflineStatus(status) {
         this.offlineStatus = {

package/dist/client/service-reachability.d.ts

@@ -0,0 +1,36 @@
+import type { NetworkStatusSource } from "./network-status.js";
+/** Reachability of the data API, independent of browser and gateway status. */
+export type ServiceReachability = "unknown" | "reachable" | "unreachable";
+export interface ServiceReachabilitySource {
+    getSnapshot(): ServiceReachability;
+    subscribe(listener: () => void): () => void;
+}
+export interface ReachabilityOptions {
+    /** A CORS-enabled, read-only URL on the data service. Defaults to dataRestUrl.
+     * Any HTTP response proves reachability, including authentication/server errors.
+     * HEAD requests omit credentials and bypass the browser cache. */
+    probeUrl?: string;
+}
+/** One polling loop per observed client. No requests or timers until subscribed. */
+export declare class ServiceReachabilityMonitor implements ServiceReachabilitySource {
+    private readonly url;
+    private readonly network;
+    private readonly fetchImpl;
+    private status;
+    private listeners;
+    private timer;
+    private controller;
+    private unsubscribeNetwork;
+    private lastCheck;
+    constructor(url: string, network: NetworkStatusSource, fetchImpl: typeof fetch);
+    getSnapshot(): ServiceReachability;
+    subscribe(listener: () => void): () => void;
+    /** Transport failures trigger a probe; they never retry the failed request.
+     * Coalesce failures and cap probes at one per second during request bursts. */
+    requestFailed(): void;
+    private setStatus;
+    private cancel;
+    private networkChanged;
+    private schedule;
+    private check;
+}

package/dist/client/service-reachability.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceReachabilityMonitor = void 0;
+/** One polling loop per observed client. No requests or timers until subscribed. */
+class ServiceReachabilityMonitor {
+    constructor(url, network, fetchImpl) {
+        this.url = url;
+        this.network = network;
+        this.fetchImpl = fetchImpl;
+        this.status = "unknown";
+        this.listeners = new Set();
+        this.lastCheck = -Infinity;
+    }
+    getSnapshot() { return this.status; }
+    subscribe(listener) {
+        const notify = () => listener();
+        this.listeners.add(notify);
+        if (this.listeners.size === 1) {
+            this.unsubscribeNetwork = this.network.subscribe(() => this.networkChanged());
+            this.networkChanged();
+        }
+        return () => {
+            this.listeners.delete(notify);
+            if (!this.listeners.size) {
+                this.unsubscribeNetwork?.();
+                this.unsubscribeNetwork = undefined;
+                this.cancel();
+            }
+        };
+    }
+    /** Transport failures trigger a probe; they never retry the failed request.
+     * Coalesce failures and cap probes at one per second during request bursts. */
+    requestFailed() {
+        if (!this.listeners.size || this.controller || !this.network.getSnapshot().online)
+            return;
+        this.schedule(Math.max(0, 1000 - (Date.now() - this.lastCheck)));
+    }
+    setStatus(status) {
+        if (status === this.status)
+            return;
+        this.status = status;
+        this.listeners.forEach((listener) => listener());
+    }
+    cancel() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        const previous = this.controller;
+        this.controller = undefined;
+        previous?.abort();
+    }
+    networkChanged() {
+        if (!this.network.getSnapshot().online) {
+            this.cancel();
+            this.setStatus("unreachable");
+        }
+        else if (!this.controller) {
+            void this.check();
+        }
+    }
+    schedule(delay) {
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => { void this.check(); }, delay);
+    }
+    async check() {
+        if (!this.listeners.size || this.controller || !this.network.getSnapshot().online)
+            return;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        const controller = new AbortController();
+        this.controller = controller;
+        this.lastCheck = Date.now();
+        // The explicit race also bounds native/custom fetch implementations that
+        // ignore AbortSignal. Late responses cannot overwrite a newer observation.
+        let rejectAbort = () => { };
+        const aborted = new Promise((_resolve, reject) => {
+            rejectAbort = () => reject(new Error("Reachability check cancelled or timed out"));
+            controller.signal.addEventListener("abort", rejectAbort, { once: true });
+        });
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        try {
+            const response = await Promise.race([
+                Promise.resolve().then(() => this.fetchImpl(this.url, {
+                    method: "HEAD", cache: "no-store", credentials: "omit",
+                    signal: controller.signal,
+                })),
+                aborted,
+            ]);
+            if (this.controller === controller) {
+                this.setStatus(response.status > 0 ? "reachable" : "unreachable");
+            }
+        }
+        catch {
+            if (this.controller === controller)
+                this.setStatus("unreachable");
+        }
+        finally {
+            clearTimeout(timeout);
+            controller.signal.removeEventListener("abort", rejectAbort);
+            if (this.controller === controller) {
+                this.controller = undefined;
+                if (this.listeners.size)
+                    this.schedule(this.status === "reachable" ? 30000 : 5000);
+            }
+        }
+    }
+}
+exports.ServiceReachabilityMonitor = ServiceReachabilityMonitor;

package/dist/esm/client/data-client.d.ts

@@ -1,3 +1,5 @@
+import type { ServiceReachabilitySource } from "./service-reachability.js";
+import type { NetworkStatusSource } from "./network-status.js";
 import type { AgentsApi } from "../apis/agents-api.js";
 import type { AggregatesApi } from "../apis/aggregates-api.js";
 import type { AlarmsApi } from "../apis/alarms-api.js";
@@ -76,6 +78,10 @@ export interface DataClientStatus {
  * later; the invariant is that `DooverClient` always satisfies it.
  */
 export interface DataClient {
+    /** Optional platform source; React hooks otherwise use browser network status. */
+    readonly networkStatus?: NetworkStatusSource;
+    /** Optional data API reachability. Polls only while explicitly subscribed. */
+    readonly reachability?: ServiceReachabilitySource;
     readonly agents: AgentsApiLike;
     readonly channels: ChannelsApiLike;
     readonly messages: MessagesApiLike;

package/dist/esm/client/doover-client.d.ts

@@ -1,3 +1,5 @@
+import { type ServiceReachabilitySource } from "./service-reachability.js";
+import { type NetworkStatusSource } from "./network-status.js";
 import { OrganisationsApi } from "../apis/organisations-api.js";
 import type { DooverAuth } from "../auth/doover-auth.js";
 import { RestClient, type DooverClientConfig } from "../http/rest-client.js";
@@ -6,6 +8,8 @@ import { type Capability } from "./capabilities.js";
 import type { AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, AgentScope, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client.js";
 import { DooverStatsCollector, type DooverStatsSnapshot } from "./stats.js";
 export declare class DooverClient implements DataClient {
+    readonly networkStatus: NetworkStatusSource;
+    readonly reachability: ServiceReachabilitySource | undefined;
     readonly auth: DooverAuth;
     readonly rest: RestClient;
     readonly viewer: DooverDataProvider;

package/dist/esm/client/doover-client.js

@@ -1,3 +1,5 @@
+import { ServiceReachabilityMonitor } from "./service-reachability.js";
+import { browserNetworkStatus } from "./network-status.js";
 import { AgentsApi } from "../apis/agents-api.js";
 import { AggregatesApi } from "../apis/aggregates-api.js";
 import { AlarmsApi } from "../apis/alarms-api.js";
@@ -22,6 +24,7 @@ import { DooverStatsCollector } from "./stats.js";
 const ALL_CAPS_SET = new Set(ALL_CAPABILITIES);
 export class DooverClient {
     constructor(config) {
+        this.networkStatus = config.networkStatus ?? browserNetworkStatus;
         this.auth = buildAuth({
             auth: config.auth,
             profile: config.profile,
@@ -45,7 +48,9 @@ export class DooverClient {
             },
         };
         const stamper = new ProvenanceStamper(this.identity);
-        this.rest = new RestClient(config, this.auth);
+        const reachability = config.reachability === false ? undefined : new ServiceReachabilityMonitor(config.reachability?.probeUrl ?? config.dataRestUrl, this.networkStatus, config.fetchImpl ?? ((...args) => fetch(...args)));
+        this.reachability = reachability;
+        this.rest = new RestClient(config, this.auth, () => reachability?.requestFailed());
         this.gatewayImpl = new GatewayClient(config, this.auth);
         this.gatewayImpl.setProvenanceHook((value, ctx) => stamper.stampGatewayEvent(value, ctx));
         this.gateway = this.gatewayImpl;

package/dist/esm/client/index.d.ts

@@ -2,3 +2,6 @@ export { DooverClient } from "./doover-client.js";
 export { getDooverClient, peekDooverClient, resetDooverClient } from "./singleton.js";
 export type { DooverClientConfig } from "../http/rest-client.js";
 export type * from "./data-client.js";
+export { browserNetworkStatus, createNetworkStatusStore } from "./network-status.js";
+export type { NetworkStatusSource, NetworkStatusSnapshot } from "./network-status.js";
+export type { ServiceReachability, ServiceReachabilitySource, ReachabilityOptions } from "./service-reachability.js";

package/dist/esm/client/index.js

@@ -1,2 +1,3 @@
 export { DooverClient } from "./doover-client.js";
 export { getDooverClient, peekDooverClient, resetDooverClient } from "./singleton.js";
+export { browserNetworkStatus, createNetworkStatusStore } from "./network-status.js";

package/dist/esm/client/network-status.d.ts

@@ -0,0 +1,17 @@
+/** Network availability is independent of the Doover gateway connection. */
+export interface NetworkStatusSnapshot {
+    readonly online: boolean;
+    readonly at: number;
+}
+/** Snapshots must retain their identity until the status changes. */
+export interface NetworkStatusSource {
+    getSnapshot(): NetworkStatusSnapshot;
+    subscribe(listener: () => void): () => void;
+}
+/** A source that native network callbacks can update. */
+export declare function createNetworkStatusStore(initialOnline: boolean): {
+    getSnapshot: () => NetworkStatusSnapshot;
+    subscribe(listener: () => void): () => void;
+    setOnline(online: boolean): void;
+};
+export declare const browserNetworkStatus: NetworkStatusSource;

package/dist/esm/client/network-status.js

@@ -0,0 +1,66 @@
+/** A source that native network callbacks can update. */
+export function createNetworkStatusStore(initialOnline) {
+    let snapshot = { online: initialOnline, at: Date.now() };
+    const listeners = new Set();
+    return {
+        getSnapshot: () => snapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        setOnline(online) {
+            if (online === snapshot.online)
+                return;
+            snapshot = { online, at: Date.now() };
+            listeners.forEach((listener) => listener());
+        },
+    };
+}
+function readBrowserOnline() {
+    const nav = typeof window !== "undefined" ? window.navigator
+        : typeof navigator !== "undefined" ? navigator : undefined;
+    return typeof nav?.onLine === "boolean" ? nav.onLine : true;
+}
+// Listen only while observed. getSnapshot also refreshes after periods with
+// no subscribers, including initial offline loads. No browser globals at import.
+function createBrowserNetworkStatus() {
+    let snapshot = { online: true, at: 0 };
+    const listeners = new Set();
+    let detach;
+    const getSnapshot = () => {
+        const online = readBrowserOnline();
+        if (online !== snapshot.online)
+            snapshot = { online, at: Date.now() };
+        return snapshot;
+    };
+    const refresh = () => {
+        getSnapshot();
+        // A request may already have read the new snapshot before this event.
+        // Still notify mounted consumers; React ignores an unchanged snapshot.
+        listeners.forEach((listener) => listener());
+    };
+    return {
+        getSnapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            if (!detach && typeof window !== "undefined") {
+                const target = window;
+                target.addEventListener("online", refresh);
+                target.addEventListener("offline", refresh);
+                detach = () => {
+                    target.removeEventListener("online", refresh);
+                    target.removeEventListener("offline", refresh);
+                };
+            }
+            refresh();
+            return () => {
+                listeners.delete(listener);
+                if (!listeners.size) {
+                    detach?.();
+                    detach = undefined;
+                }
+            };
+        },
+    };
+}
+export const browserNetworkStatus = createBrowserNetworkStatus();