doover-js 0.13.0 → 0.13.2

package/README.md

@@ -416,3 +416,33 @@ 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 a trailing slash and
+`cache: "no-store"`. For example, a base URL ending in `/api` is probed at `/api/`,
+inside the API routing prefix rather than a possible static CDN fallback. An
+explicit `probeUrl` is used unchanged. 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,4 @@
+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";
@@ -79,6 +80,8 @@ export interface DataClientStatus {
 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,4 @@
+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";
@@ -8,6 +9,7 @@ import type { AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike,
 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,7 @@
 "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");
@@ -50,7 +51,12 @@ 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(
+        // Probe inside the API prefix: the bare prefix may route to a static CDN
+        // fallback without CORS, even though every real API request succeeds.
+        config.reachability?.probeUrl ?? `${config.dataRestUrl.replace(/\/+$/, "")}/`, 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

@@ -4,3 +4,4 @@ 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/offline-cache.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -99,6 +100,7 @@ export interface OfflineDataClientOptions {
 }
 export declare class OfflineDataClient implements DataClient {
     readonly networkStatus: NetworkStatusSource;
+    readonly reachability: ServiceReachabilitySource | undefined;
     private unsubscribeNetwork?;
     readonly agents: AgentsApiLike;
     readonly channels: ChannelsApiLike;

package/dist/client/offline-cache.js

@@ -58,6 +58,7 @@ 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;

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 with a trailing slash.
+     * 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,4 @@
+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";
@@ -79,6 +80,8 @@ export interface DataClientStatus {
 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,4 @@
+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";
@@ -8,6 +9,7 @@ import type { AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike,
 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,4 @@
+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";
@@ -47,7 +48,12 @@ export class DooverClient {
             },
         };
         const stamper = new ProvenanceStamper(this.identity);
-        this.rest = new RestClient(config, this.auth);
+        const reachability = config.reachability === false ? undefined : new ServiceReachabilityMonitor(
+        // Probe inside the API prefix: the bare prefix may route to a static CDN
+        // fallback without CORS, even though every real API request succeeds.
+        config.reachability?.probeUrl ?? `${config.dataRestUrl.replace(/\/+$/, "")}/`, 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

@@ -4,3 +4,4 @@ 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/offline-cache.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -99,6 +100,7 @@ export interface OfflineDataClientOptions {
 }
 export declare class OfflineDataClient implements DataClient {
     readonly networkStatus: NetworkStatusSource;
+    readonly reachability: ServiceReachabilitySource | undefined;
     private unsubscribeNetwork?;
     readonly agents: AgentsApiLike;
     readonly channels: ChannelsApiLike;

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

@@ -54,6 +54,7 @@ export 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 ?? browserNetworkStatus;
         this.storage = options.storage;
         this.scope = options.scope;

package/dist/esm/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 with a trailing slash.
+     * 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/esm/client/service-reachability.js

@@ -0,0 +1,103 @@
+/** One polling loop per observed client. No requests or timers until subscribed. */
+export 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);
+            }
+        }
+    }
+}

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

@@ -1,9 +1,12 @@
+import type { ReachabilityOptions } from "../client/service-reachability.js";
 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;
+    /** Data API reachability checks while reachability is observed. Set false to disable. */
+    reachability?: ReachabilityOptions | false;
     dataRestUrl: string;
     controlApiUrl: string;
     dataWssUrl: string;
@@ -40,10 +43,11 @@ export interface RequestOptions {
 type QueryValue = string | number | boolean | null | undefined | Array<string | number | boolean>;
 type QueryParams = Record<string, QueryValue> | object;
 export declare class RestClient {
+    private readonly onTransportFailure?;
     readonly config: Required<Pick<DooverClientConfig, "dataRestUrl" | "controlApiUrl" | "dataWssUrl" | "sharing" | "impersonateUserStorageKey">> & Pick<DooverClientConfig, "organisationId" | "fetchImpl" | "webSocketImpl" | "webSocketFactory">;
     readonly auth: DooverAuth | null;
     private stats;
-    constructor(config: DooverClientConfig, auth?: DooverAuth);
+    constructor(config: DooverClientConfig, auth?: DooverAuth, onTransportFailure?: (() => void) | undefined);
     /** Attach a stats collector. Call with `null` to detach. */
     setStats(stats: DooverStatsCollector | null): void;
     request<T>(options: RequestOptions): Promise<T>;

package/dist/esm/http/rest-client.js

@@ -1,6 +1,7 @@
 import { DooverApiError } from "./errors.js";
 export class RestClient {
-    constructor(config, auth) {
+    constructor(config, auth, onTransportFailure) {
+        this.onTransportFailure = onTransportFailure;
         this.stats = null;
         this.config = {
             ...config,
@@ -91,12 +92,19 @@ export class RestClient {
             }
         }
         const fetchImpl = this.config.fetchImpl ?? fetch;
-        return fetchImpl(request.url, {
-            method: request.method,
-            headers: request.headers,
-            body: request.body,
-            credentials: request.credentials,
-        });
+        try {
+            return await fetchImpl(request.url, {
+                method: request.method,
+                headers: request.headers,
+                body: request.body,
+                credentials: request.credentials,
+            });
+        }
+        catch (error) {
+            // Auth preparation, HTTP errors and JSON parsing are outside this boundary.
+            this.onTransportFailure?.();
+            throw error;
+        }
     }
     get(path, query, baseUrl) {
         return this.request({ path, query, baseUrl });

package/dist/esm/index.d.ts

@@ -62,3 +62,4 @@ 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";
+export type { ServiceReachability, ServiceReachabilitySource, ReachabilityOptions } from "./client/service-reachability.js";

package/dist/esm/package.json

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

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

@@ -36,3 +36,4 @@ export { useTurnCredentials } from "./useTurnCredentials.js";
 export { useAgentTokenState, useSetAgentTokenPolicy, useSetAgentAuthLock, useRevokeAgentTokens, useSetRevocationFloor, useCreateAdhocToken, useCreateDeviceToken, agentTokenStateQueryKey, } from "./useAgentTokenState.js";
 export type { UseAgentTokenStateOptions } from "./useAgentTokenState.js";
 export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient.js";
+export { useServiceReachability } from "./useServiceReachability.js";

package/dist/esm/react/index.js

@@ -19,3 +19,4 @@ export { useDeviceMap } from "./useDeviceMap.js";
 export { useTurnCredentials } from "./useTurnCredentials.js";
 export { useAgentTokenState, useSetAgentTokenPolicy, useSetAgentAuthLock, useRevokeAgentTokens, useSetRevocationFloor, useCreateAdhocToken, useCreateDeviceToken, agentTokenStateQueryKey, } from "./useAgentTokenState.js";
 export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient.js";
+export { useServiceReachability } from "./useServiceReachability.js";

package/dist/esm/react/useServiceReachability.d.ts

@@ -0,0 +1,5 @@
+import type { ServiceReachability } from "../client/service-reachability.js";
+/** Observe data API reachability even when the browser incorrectly reports online.
+ * Shares one polling loop per client; the final unmount stops checks.
+ * Clients without a reachability source return unknown and make no requests. */
+export declare function useServiceReachability(): ServiceReachability;

package/dist/esm/react/useServiceReachability.js

@@ -0,0 +1,13 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { useDooverClient } from "./context.js";
+const unknownSnapshot = () => "unknown";
+const noop = () => { };
+/** Observe data API reachability even when the browser incorrectly reports online.
+ * Shares one polling loop per client; the final unmount stops checks.
+ * Clients without a reachability source return unknown and make no requests. */
+export function useServiceReachability() {
+    const source = useDooverClient().reachability;
+    const subscribe = useCallback((listener) => source?.subscribe(listener) ?? noop, [source]);
+    const getSnapshot = useCallback(() => source?.getSnapshot() ?? "unknown", [source]);
+    return useSyncExternalStore(subscribe, getSnapshot, unknownSnapshot);
+}

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

@@ -1,9 +1,12 @@
+import type { ReachabilityOptions } from "../client/service-reachability.js";
 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;
+    /** Data API reachability checks while reachability is observed. Set false to disable. */
+    reachability?: ReachabilityOptions | false;
     dataRestUrl: string;
     controlApiUrl: string;
     dataWssUrl: string;
@@ -40,10 +43,11 @@ export interface RequestOptions {
 type QueryValue = string | number | boolean | null | undefined | Array<string | number | boolean>;
 type QueryParams = Record<string, QueryValue> | object;
 export declare class RestClient {
+    private readonly onTransportFailure?;
     readonly config: Required<Pick<DooverClientConfig, "dataRestUrl" | "controlApiUrl" | "dataWssUrl" | "sharing" | "impersonateUserStorageKey">> & Pick<DooverClientConfig, "organisationId" | "fetchImpl" | "webSocketImpl" | "webSocketFactory">;
     readonly auth: DooverAuth | null;
     private stats;
-    constructor(config: DooverClientConfig, auth?: DooverAuth);
+    constructor(config: DooverClientConfig, auth?: DooverAuth, onTransportFailure?: (() => void) | undefined);
     /** Attach a stats collector. Call with `null` to detach. */
     setStats(stats: DooverStatsCollector | null): void;
     request<T>(options: RequestOptions): Promise<T>;

package/dist/http/rest-client.js

@@ -3,7 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RestClient = void 0;
 const errors_js_1 = require("./errors.js");
 class RestClient {
-    constructor(config, auth) {
+    constructor(config, auth, onTransportFailure) {
+        this.onTransportFailure = onTransportFailure;
         this.stats = null;
         this.config = {
             ...config,
@@ -94,12 +95,19 @@ class RestClient {
             }
         }
         const fetchImpl = this.config.fetchImpl ?? fetch;
-        return fetchImpl(request.url, {
-            method: request.method,
-            headers: request.headers,
-            body: request.body,
-            credentials: request.credentials,
-        });
+        try {
+            return await fetchImpl(request.url, {
+                method: request.method,
+                headers: request.headers,
+                body: request.body,
+                credentials: request.credentials,
+            });
+        }
+        catch (error) {
+            // Auth preparation, HTTP errors and JSON parsing are outside this boundary.
+            this.onTransportFailure?.();
+            throw error;
+        }
     }
     get(path, query, baseUrl) {
         return this.request({ path, query, baseUrl });

package/dist/index.d.ts

@@ -62,3 +62,4 @@ 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";
+export type { ServiceReachability, ServiceReachabilitySource, ReachabilityOptions } from "./client/service-reachability.js";

package/dist/react/index.d.ts

@@ -36,3 +36,4 @@ export { useTurnCredentials } from "./useTurnCredentials.js";
 export { useAgentTokenState, useSetAgentTokenPolicy, useSetAgentAuthLock, useRevokeAgentTokens, useSetRevocationFloor, useCreateAdhocToken, useCreateDeviceToken, agentTokenStateQueryKey, } from "./useAgentTokenState.js";
 export type { UseAgentTokenStateOptions } from "./useAgentTokenState.js";
 export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient.js";
+export { useServiceReachability } from "./useServiceReachability.js";

package/dist/react/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.agentTokenStateQueryKey = exports.useCreateDeviceToken = exports.useCreateAdhocToken = exports.useSetRevocationFloor = exports.useRevokeAgentTokens = exports.useSetAgentAuthLock = exports.useSetAgentTokenPolicy = exports.useAgentTokenState = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
+exports.useServiceReachability = exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.agentTokenStateQueryKey = exports.useCreateDeviceToken = exports.useCreateAdhocToken = exports.useSetRevocationFloor = exports.useRevokeAgentTokens = exports.useSetAgentAuthLock = exports.useSetAgentTokenPolicy = exports.useAgentTokenState = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
 var context_js_1 = require("./context.js");
 Object.defineProperty(exports, "DooverProvider", { enumerable: true, get: function () { return context_js_1.DooverProvider; } });
 Object.defineProperty(exports, "useDooverClient", { enumerable: true, get: function () { return context_js_1.useDooverClient; } });
@@ -60,3 +60,5 @@ Object.defineProperty(exports, "agentTokenStateQueryKey", { enumerable: true, ge
 var sharedQueryClient_js_1 = require("./sharedQueryClient.js");
 Object.defineProperty(exports, "getSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_js_1.getSharedQueryClient; } });
 Object.defineProperty(exports, "resetSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_js_1.resetSharedQueryClient; } });
+var useServiceReachability_js_1 = require("./useServiceReachability.js");
+Object.defineProperty(exports, "useServiceReachability", { enumerable: true, get: function () { return useServiceReachability_js_1.useServiceReachability; } });

package/dist/react/useServiceReachability.d.ts

@@ -0,0 +1,5 @@
+import type { ServiceReachability } from "../client/service-reachability.js";
+/** Observe data API reachability even when the browser incorrectly reports online.
+ * Shares one polling loop per client; the final unmount stops checks.
+ * Clients without a reachability source return unknown and make no requests. */
+export declare function useServiceReachability(): ServiceReachability;

package/dist/react/useServiceReachability.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useServiceReachability = useServiceReachability;
+const react_1 = require("react");
+const context_js_1 = require("./context.js");
+const unknownSnapshot = () => "unknown";
+const noop = () => { };
+/** Observe data API reachability even when the browser incorrectly reports online.
+ * Shares one polling loop per client; the final unmount stops checks.
+ * Clients without a reachability source return unknown and make no requests. */
+function useServiceReachability() {
+    const source = (0, context_js_1.useDooverClient)().reachability;
+    const subscribe = (0, react_1.useCallback)((listener) => source?.subscribe(listener) ?? noop, [source]);
+    const getSnapshot = (0, react_1.useCallback)(() => source?.getSnapshot() ?? "unknown", [source]);
+    return (0, react_1.useSyncExternalStore)(subscribe, getSnapshot, unknownSnapshot);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -641,7 +641,19 @@
       },
       "default": "./dist/react/useUpdateMessage.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./react/useServiceReachability": {
+      "module": "./dist/esm/react/useServiceReachability.js",
+      "import": {
+        "types": "./dist/esm/react/useServiceReachability.d.ts",
+        "default": "./dist/esm/react/useServiceReachability.js"
+      },
+      "require": {
+        "types": "./dist/react/useServiceReachability.d.ts",
+        "default": "./dist/react/useServiceReachability.js"
+      },
+      "default": "./dist/react/useServiceReachability.js"
+    }
   },
   "repository": {
     "type": "git",
@@ -866,6 +878,9 @@
       ],
       "react/useUpdateMessage": [
         "dist/react/useUpdateMessage.d.ts"
+      ],
+      "react/useServiceReachability": [
+        "dist/react/useServiceReachability.d.ts"
       ]
     }
   }