doover-js 0.12.1 → 0.13.0

package/README.md

@@ -389,3 +389,30 @@ 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.

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

@@ -1,3 +1,4 @@
+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 +77,8 @@ 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;
     readonly agents: AgentsApiLike;
     readonly channels: ChannelsApiLike;
     readonly messages: MessagesApiLike;

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

@@ -1,3 +1,4 @@
+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 +7,7 @@ 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 auth: DooverAuth;
     readonly rest: RestClient;
     readonly viewer: DooverDataProvider;

package/dist/client/doover-client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DooverClient = void 0;
+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 +26,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,

package/dist/client/index.d.ts

@@ -2,3 +2,5 @@ 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";

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,4 @@
+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 +84,22 @@ 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;
+    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,7 @@ class OfflineDataClient {
         this.offlineStatus = INITIAL_OFFLINE_STATUS;
         this.persistQueue = Promise.resolve();
         this.client = options.client;
+        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 +92,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 +695,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/esm/client/data-client.d.ts

@@ -1,3 +1,4 @@
+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 +77,8 @@ 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;
     readonly agents: AgentsApiLike;
     readonly channels: ChannelsApiLike;
     readonly messages: MessagesApiLike;

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

@@ -1,3 +1,4 @@
+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 +7,7 @@ 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 auth: DooverAuth;
     readonly rest: RestClient;
     readonly viewer: DooverDataProvider;

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

@@ -1,3 +1,4 @@
+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 +23,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,

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

@@ -2,3 +2,5 @@ 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";

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();

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

@@ -1,3 +1,4 @@
+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 +84,22 @@ 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;
+    private unsubscribeNetwork?;
     readonly agents: AgentsApiLike;
     readonly channels: ChannelsApiLike;
     readonly messages: MessagesApiLike;

package/dist/esm/client/offline-cache.js

@@ -1,3 +1,4 @@
+import { browserNetworkStatus } from "./network-status.js";
 import { DooverOfflineError } from "./errors.js";
 import { delegateRequestOptions, splitRequestOptions, } from "./request-options.js";
 export const DEFAULT_OFFLINE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
@@ -53,6 +54,7 @@ export class OfflineDataClient {
         this.offlineStatus = INITIAL_OFFLINE_STATUS;
         this.persistQueue = Promise.resolve();
         this.client = options.client;
+        this.networkStatus = options.networkStatus ?? options.client.networkStatus ?? browserNetworkStatus;
         this.storage = options.storage;
         this.scope = options.scope;
         this.defaultRetentionMs = options.defaultRetentionMs ?? DEFAULT_OFFLINE_RETENTION_MS;
@@ -86,19 +88,30 @@ export 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) {
@@ -678,8 +691,7 @@ export 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/esm/http/rest-client.d.ts

@@ -1,7 +1,9 @@
+import type { NetworkStatusSource } from "../client/network-status.js";
 import type { AuthConfig } from "../auth/build-auth.js";
 import type { DooverAuth } from "../auth/doover-auth.js";
 import type { DooverStatsCollector } from "../client/stats.js";
 export interface DooverClientConfig extends AuthConfig {
+    networkStatus?: NetworkStatusSource;
     dataRestUrl: string;
     controlApiUrl: string;
     dataWssUrl: string;

package/dist/esm/index.d.ts

@@ -60,3 +60,5 @@ export type * from "./types/viewer.js";
 export type * from "./types/audit.js";
 export { DV_AUDIT_CHANNEL } from "./types/audit.js";
 export { addTimestampToMessage, extractSnowflakeId, generateSnowflakeIdAtTime, } from "./utils/snowflake.js";
+export { browserNetworkStatus, createNetworkStatusStore } from "./client/network-status.js";
+export type { NetworkStatusSource, NetworkStatusSnapshot } from "./client/network-status.js";

package/dist/esm/index.js

@@ -35,3 +35,4 @@ export { DooverDataProvider } from "./viewer/doover-data-provider.js";
 export { getIdentifierFromPath } from "./viewer/path-parsing.js";
 export { DV_AUDIT_CHANNEL } from "./types/audit.js";
 export { addTimestampToMessage, extractSnowflakeId, generateSnowflakeIdAtTime, } from "./utils/snowflake.js";
+export { browserNetworkStatus, createNetworkStatusStore } from "./client/network-status.js";

package/dist/esm/package.json

@@ -1 +1 @@
-{"type":"module","sideEffects":false}
+{"name":"doover-js","version":"0.13.0","type":"module","sideEffects":false}

package/dist/esm/react/useOfflineStatus.js

@@ -1,23 +1,37 @@
-import { useSyncExternalStore } from "react";
+import { useMemo, useSyncExternalStore } from "react";
+import { browserNetworkStatus } from "../client/network-status.js";
 import { useDooverClient } from "./context.js";
 export function hasOfflineStatus(client) {
-    return (!!client &&
-        typeof client === "object" &&
-        typeof client.getOfflineStatus === "function" &&
-        typeof client.onOfflineStatusChange === "function");
+    return !!client && typeof client === "object" &&
+        "getOfflineStatus" in client && typeof client.getOfflineStatus === "function" &&
+        "onOfflineStatusChange" in client && typeof client.onOfflineStatusChange === "function";
 }
-const UNAVAILABLE_OFFLINE_STATUS = {
-    online: true,
-    state: "online",
-    isOfflineFallback: false,
-    isExpired: false,
-    at: 0,
+const SERVER_OFFLINE_STATUS = {
+    online: true, state: "online", isOfflineFallback: false, isExpired: false, at: 0,
 };
 export function useOfflineStatus() {
     const client = useDooverClient();
-    return useSyncExternalStore((listener) => hasOfflineStatus(client)
-        ? client.onOfflineStatusChange(listener)
-        : () => undefined, () => hasOfflineStatus(client)
-        ? client.getOfflineStatus()
-        : UNAVAILABLE_OFFLINE_STATUS, () => UNAVAILABLE_OFFLINE_STATUS);
+    const store = useMemo(() => {
+        if (hasOfflineStatus(client)) {
+            return {
+                subscribe: (listener) => client.onOfflineStatusChange(listener),
+                getSnapshot: () => client.getOfflineStatus(),
+            };
+        }
+        const network = client.networkStatus ?? browserNetworkStatus;
+        let previous = network.getSnapshot();
+        let snapshot = { ...SERVER_OFFLINE_STATUS, ...previous };
+        return {
+            subscribe: (listener) => network.subscribe(listener),
+            getSnapshot: () => {
+                const next = network.getSnapshot();
+                if (next !== previous) {
+                    previous = next;
+                    snapshot = { ...SERVER_OFFLINE_STATUS, ...next };
+                }
+                return snapshot;
+            },
+        };
+    }, [client]);
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, () => SERVER_OFFLINE_STATUS);
 }

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

@@ -1,7 +1,9 @@
+import type { NetworkStatusSource } from "../client/network-status.js";
 import type { AuthConfig } from "../auth/build-auth.js";
 import type { DooverAuth } from "../auth/doover-auth.js";
 import type { DooverStatsCollector } from "../client/stats.js";
 export interface DooverClientConfig extends AuthConfig {
+    networkStatus?: NetworkStatusSource;
     dataRestUrl: string;
     controlApiUrl: string;
     dataWssUrl: string;

package/dist/index.d.ts

@@ -60,3 +60,5 @@ export type * from "./types/viewer.js";
 export type * from "./types/audit.js";
 export { DV_AUDIT_CHANNEL } from "./types/audit.js";
 export { addTimestampToMessage, extractSnowflakeId, generateSnowflakeIdAtTime, } from "./utils/snowflake.js";
+export { browserNetworkStatus, createNetworkStatusStore } from "./client/network-status.js";
+export type { NetworkStatusSource, NetworkStatusSnapshot } from "./client/network-status.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractSnowflakeId = exports.addTimestampToMessage = exports.DV_AUDIT_CHANNEL = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.mergeBatchResponses = exports.chunkBatchItems = exports.MAX_BATCH_ITEMS = exports.splitRequestOptions = exports.isDooverRequestOptions = exports.requestOptions = exports.DEFAULT_OFFLINE_RETENTION_MS = exports.MemoryOfflineStorageAdapter = exports.OfflineDataClient = exports.DooverOfflineError = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = exports.ALL_CAPABILITIES = exports.DooverRpcError = exports.RpcDispatcher = exports.UsersApi = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.OrganisationsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.MultiplexClient = exports.LocalAgentClient = exports.DooverClient = void 0;
-exports.generateSnowflakeIdAtTime = void 0;
+exports.createNetworkStatusStore = exports.browserNetworkStatus = exports.generateSnowflakeIdAtTime = void 0;
 var doover_client_js_1 = require("./client/doover-client.js");
 Object.defineProperty(exports, "DooverClient", { enumerable: true, get: function () { return doover_client_js_1.DooverClient; } });
 var local_agent_client_js_1 = require("./client/local-agent-client.js");
@@ -90,3 +90,6 @@ var snowflake_js_1 = require("./utils/snowflake.js");
 Object.defineProperty(exports, "addTimestampToMessage", { enumerable: true, get: function () { return snowflake_js_1.addTimestampToMessage; } });
 Object.defineProperty(exports, "extractSnowflakeId", { enumerable: true, get: function () { return snowflake_js_1.extractSnowflakeId; } });
 Object.defineProperty(exports, "generateSnowflakeIdAtTime", { enumerable: true, get: function () { return snowflake_js_1.generateSnowflakeIdAtTime; } });
+var network_status_js_1 = require("./client/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/react/useOfflineStatus.js

@@ -3,25 +3,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasOfflineStatus = hasOfflineStatus;
 exports.useOfflineStatus = useOfflineStatus;
 const react_1 = require("react");
+const network_status_js_1 = require("../client/network-status.js");
 const context_js_1 = require("./context.js");
 function hasOfflineStatus(client) {
-    return (!!client &&
-        typeof client === "object" &&
-        typeof client.getOfflineStatus === "function" &&
-        typeof client.onOfflineStatusChange === "function");
+    return !!client && typeof client === "object" &&
+        "getOfflineStatus" in client && typeof client.getOfflineStatus === "function" &&
+        "onOfflineStatusChange" in client && typeof client.onOfflineStatusChange === "function";
 }
-const UNAVAILABLE_OFFLINE_STATUS = {
-    online: true,
-    state: "online",
-    isOfflineFallback: false,
-    isExpired: false,
-    at: 0,
+const SERVER_OFFLINE_STATUS = {
+    online: true, state: "online", isOfflineFallback: false, isExpired: false, at: 0,
 };
 function useOfflineStatus() {
     const client = (0, context_js_1.useDooverClient)();
-    return (0, react_1.useSyncExternalStore)((listener) => hasOfflineStatus(client)
-        ? client.onOfflineStatusChange(listener)
-        : () => undefined, () => hasOfflineStatus(client)
-        ? client.getOfflineStatus()
-        : UNAVAILABLE_OFFLINE_STATUS, () => UNAVAILABLE_OFFLINE_STATUS);
+    const store = (0, react_1.useMemo)(() => {
+        if (hasOfflineStatus(client)) {
+            return {
+                subscribe: (listener) => client.onOfflineStatusChange(listener),
+                getSnapshot: () => client.getOfflineStatus(),
+            };
+        }
+        const network = client.networkStatus ?? network_status_js_1.browserNetworkStatus;
+        let previous = network.getSnapshot();
+        let snapshot = { ...SERVER_OFFLINE_STATUS, ...previous };
+        return {
+            subscribe: (listener) => network.subscribe(listener),
+            getSnapshot: () => {
+                const next = network.getSnapshot();
+                if (next !== previous) {
+                    previous = next;
+                    snapshot = { ...SERVER_OFFLINE_STATUS, ...next };
+                }
+                return snapshot;
+            },
+        };
+    }, [client]);
+    return (0, react_1.useSyncExternalStore)(store.subscribe, store.getSnapshot, () => SERVER_OFFLINE_STATUS);
 }

package/package.json

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