doover-js 0.1.2 → 0.2.0

package/dist/gateway/gateway-client.js

@@ -3,15 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GatewayClient = void 0;
 const errors_1 = require("../http/errors");
 const snowflake_1 = require("../utils/snowflake");
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_CAP_MS = 30000;
 class GatewayClient {
-    constructor(config) {
+    constructor(config, auth) {
         this.config = config;
         this.socket = null;
         this.session = null;
-        this.heartbeatTimer = null;
-        this.lastHeartbeatAt = null;
-        this.missedHeartbeats = 0;
         this.reconnectTimer = null;
+        this.reconnectAttempts = 0;
+        /** Set when the consumer explicitly disconnects — suppresses reconnect. */
+        this.explicitlyDisconnected = false;
+        /** Guards against concurrent connect() callers creating duplicate sockets. */
+        this.opening = false;
         this.listeners = {
             ready: new Set(),
             channelSync: new Set(),
@@ -26,31 +30,87 @@ class GatewayClient {
             sessionCancelled: new Set(),
             open: new Set(),
             close: new Set(),
-            heartbeatAck: new Set(),
         };
         this.subscriptions = new Map();
+        this.stats = null;
+        this.handleVisibilityChange = () => {
+            if (typeof document === "undefined")
+                return;
+            if (document.visibilityState !== "visible")
+                return;
+            this.tryImmediateReconnect();
+        };
+        this.handleOnline = () => {
+            this.tryImmediateReconnect();
+        };
+        this.auth = auth ?? null;
+        this.installLifecycleListeners();
+    }
+    /** Attach a stats collector. Call with `null` to detach. */
+    setStats(stats) {
+        this.stats = stats;
     }
-    connect() {
+    async connect() {
+        this.explicitlyDisconnected = false;
         if (this.socket && this.socket.readyState <= WebSocket.OPEN) {
             return;
         }
-        const WebSocketImpl = this.config.webSocketImpl ?? WebSocket;
-        this.socket = new WebSocketImpl(this.config.dataWssUrl);
-        this.socket.onopen = () => this.emit("open");
-        this.socket.onclose = (event) => {
-            this.stopHeartbeat();
+        // De-dupe concurrent callers. Without this, N simultaneous
+        // `subscribeToChannel(...)` calls each await auth, then each create
+        // their own socket — the last one wins `this.socket`, but the earlier
+        // sockets' `onmessage` handlers still fire and try to send() through
+        // `this.socket` (a newer, not-yet-open socket → throws). The flag is
+        // cleared synchronously as soon as the new socket is assigned in
+        // `openSocket`, so reconnects after close still work.
+        if (this.opening) {
+            return;
+        }
+        this.opening = true;
+        try {
+            await this.openSocket();
+        }
+        finally {
+            this.opening = false;
+        }
+    }
+    async openSocket() {
+        if (this.auth) {
+            await this.auth.ensureReady();
+        }
+        const hasFactory = !!this.config.webSocketFactory;
+        const wsParams = this.auth
+            ? await this.auth.prepareWebSocket(this.config.dataWssUrl, hasFactory)
+            : { url: this.config.dataWssUrl };
+        let socket;
+        if (this.config.webSocketFactory) {
+            socket = this.config.webSocketFactory({
+                url: wsParams.url,
+                headers: wsParams.headers,
+            });
+        }
+        else {
+            const WebSocketImpl = this.config.webSocketImpl ?? WebSocket;
+            socket = new WebSocketImpl(wsParams.url);
+        }
+        this.socket = socket;
+        // Release the concurrency gate synchronously now that the new socket is
+        // assigned — any subsequent connect() will see it via `this.socket`.
+        this.opening = false;
+        socket.onopen = () => this.emit("open");
+        socket.onclose = (event) => {
             this.emit("close", event);
             this.scheduleReconnect();
         };
-        this.socket.onerror = () => undefined;
-        this.socket.onmessage = (event) => this.handleMessage(event.data);
+        socket.onerror = () => undefined;
+        socket.onmessage = (event) => this.handleMessage(event.data);
     }
     disconnect(code, reason) {
-        this.stopHeartbeat();
+        this.explicitlyDisconnected = true;
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        this.reconnectAttempts = 0;
         this.socket?.close(code, reason);
         this.socket = null;
     }
@@ -66,7 +126,7 @@ class GatewayClient {
             diff_only: options?.diff_only ?? false,
         });
         if (!this.isConnected()) {
-            this.connect();
+            void this.connect();
             return;
         }
         this.send({
@@ -93,7 +153,7 @@ class GatewayClient {
     }
     syncChannel(channel) {
         if (!this.isConnected()) {
-            this.connect();
+            void this.connect();
             return;
         }
         this.send({
@@ -106,7 +166,7 @@ class GatewayClient {
     }
     sendOneShotMessage(channel, data) {
         if (!this.isConnected()) {
-            this.connect();
+            void this.connect();
             return;
         }
         this.send({
@@ -120,20 +180,44 @@ class GatewayClient {
     getSession() {
         return this.session;
     }
-    getLatency() {
-        return this.lastHeartbeatAt === null ? null : Date.now() - this.lastHeartbeatAt;
-    }
     isConnected() {
         return this.socket?.readyState === WebSocket.OPEN;
     }
+    /** Number of channels the gateway is currently subscribed to. */
+    getSubscriptionCount() {
+        return this.subscriptions.size;
+    }
+    /** Snapshot of currently subscribed channels (for debug/inspection). */
+    getSubscriptions() {
+        return [...this.subscriptions.values()].map((s) => s.channel);
+    }
+    /**
+     * Force a fresh connection: close the current socket (without suppressing
+     * reconnects) and immediately open a new one. Useful for a manual
+     * "reconnect now" control in debug UIs.
+     */
+    async reconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.reconnectAttempts = 0;
+        // Drop the session so the new socket identifies fresh (op 10) rather
+        // than attempting to resume a just-closed session (op 11) that the
+        // server has already torn down.
+        this.session = null;
+        if (this.socket) {
+            // Suppress the auto-reconnect path so we don't double-schedule.
+            const prev = this.socket;
+            prev.onclose = null;
+            prev.close(1000, "manual reconnect");
+            this.socket = null;
+        }
+        await this.connect();
+    }
     handleMessage(raw) {
+        this.stats?.recordGatewayReceived();
         const message = JSON.parse(raw);
-        if (message.op === 2) {
-            this.missedHeartbeats = 0;
-            const latency = this.lastHeartbeatAt === null ? null : Date.now() - this.lastHeartbeatAt;
-            this.emit("heartbeatAck", latency);
-            return;
-        }
         if (message.op === 3) {
             this.session = null;
             this.emit("sessionCancelled");
@@ -145,9 +229,9 @@ class GatewayClient {
         switch (message.t) {
             case "Hello":
                 this.identifyOrResume();
-                this.startHeartbeat();
                 break;
             case "Ready":
+                this.reconnectAttempts = 0;
                 this.session = message.d;
                 this.emit("ready", message.d);
                 this.resubscribeAll();
@@ -209,33 +293,12 @@ class GatewayClient {
             this.subscribe(entry.channel, { diff_only: entry.diff_only });
         }
     }
-    startHeartbeat() {
-        this.stopHeartbeat();
-        this.heartbeatTimer = setInterval(() => {
-            if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
-                return;
-            }
-            this.lastHeartbeatAt = Date.now();
-            this.missedHeartbeats += 1;
-            if (this.missedHeartbeats > 3) {
-                this.socket.close(4000, "Missed heartbeats");
-                return;
-            }
-            this.send({ op: 1, d: {} });
-        }, 20000);
-    }
-    stopHeartbeat() {
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = null;
-        }
-        this.missedHeartbeats = 0;
-    }
     send(payload) {
         if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
             throw new errors_1.DooverGatewayError("WebSocket is not connected");
         }
         this.socket.send(JSON.stringify(payload));
+        this.stats?.recordGatewaySent();
     }
     emit(eventName, ...args) {
         this.listeners[eventName].forEach((listener) => {
@@ -243,13 +306,45 @@ class GatewayClient {
         });
     }
     scheduleReconnect() {
-        if (this.reconnectTimer) {
+        if (this.reconnectTimer || this.explicitlyDisconnected) {
             return;
         }
+        const delay = this.computeReconnectDelay();
+        this.reconnectAttempts += 1;
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
-            this.connect();
-        }, 1000);
+            void this.connect();
+        }, delay);
+    }
+    /** Exponential backoff with full-jitter, capped at RECONNECT_CAP_MS. */
+    computeReconnectDelay() {
+        const exp = Math.min(RECONNECT_CAP_MS, RECONNECT_BASE_MS * 2 ** this.reconnectAttempts);
+        return Math.floor(Math.random() * exp);
+    }
+    installLifecycleListeners() {
+        if (this.config.disableBrowserLifecycleHooks)
+            return;
+        if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+            document.addEventListener("visibilitychange", this.handleVisibilityChange);
+        }
+        if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+            window.addEventListener("online", this.handleOnline);
+        }
+    }
+    /**
+     * Called by lifecycle hooks when we have a strong signal that the network
+     * or tab has come back — skip the backoff schedule and reconnect now.
+     */
+    tryImmediateReconnect() {
+        if (this.explicitlyDisconnected)
+            return;
+        if (this.isConnected())
+            return;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        void this.connect();
     }
     channelKey(channel) {
         return `${channel.agent_id}/${channel.name}`;

package/dist/gateway/types.d.ts

@@ -131,5 +131,4 @@ export interface GatewayListenerMap {
     sessionCancelled: () => void;
     open: () => void;
     close: (event: CloseEvent) => void;
-    heartbeatAck: (latencyMs: number | null) => void;
 }

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

@@ -1,4 +1,7 @@
-export interface DooverClientConfig {
+import type { AuthConfig } from "../auth/build-auth";
+import type { DooverAuth } from "../auth/doover-auth";
+import type { DooverStatsCollector } from "../client/stats";
+export interface DooverClientConfig extends AuthConfig {
     dataRestUrl: string;
     controlApiUrl: string;
     dataWssUrl: string;
@@ -7,6 +10,16 @@ export interface DooverClientConfig {
     impersonateUserStorageKey?: string;
     fetchImpl?: typeof fetch;
     webSocketImpl?: typeof WebSocket;
+    webSocketFactory?: (options: {
+        url: string;
+        headers?: Record<string, string>;
+    }) => WebSocket;
+    /**
+     * When true, disables the GatewayClient's browser lifecycle listeners
+     * (visibilitychange, online). Defaults to false — hooks are on by default
+     * in browsers and automatically skipped in non-browser environments.
+     */
+    disableBrowserLifecycleHooks?: boolean;
 }
 export interface RequestOptions {
     baseUrl?: string;
@@ -20,9 +33,14 @@ export interface RequestOptions {
 type QueryValue = string | number | boolean | null | undefined | Array<string | number | boolean>;
 type QueryParams = Record<string, QueryValue> | object;
 export declare class RestClient {
-    readonly config: Required<Pick<DooverClientConfig, "dataRestUrl" | "controlApiUrl" | "dataWssUrl" | "sharing" | "impersonateUserStorageKey">> & Pick<DooverClientConfig, "organisationId" | "fetchImpl" | "webSocketImpl">;
-    constructor(config: DooverClientConfig);
+    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);
+    /** Attach a stats collector. Call with `null` to detach. */
+    setStats(stats: DooverStatsCollector | null): void;
     request<T>(options: RequestOptions): Promise<T>;
+    private doRequest;
     get<T>(path: string, query?: RequestOptions["query"], baseUrl?: string): Promise<T>;
     post<T>(path: string, body?: RequestOptions["body"], query?: RequestOptions["query"], baseUrl?: string): Promise<T>;
     put<T>(path: string, body?: RequestOptions["body"], query?: RequestOptions["query"], baseUrl?: string): Promise<T>;

package/dist/http/rest-client.js

@@ -3,19 +3,47 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RestClient = void 0;
 const errors_1 = require("./errors");
 class RestClient {
-    constructor(config) {
+    constructor(config, auth) {
+        this.stats = null;
         this.config = {
             ...config,
             sharing: config.sharing ?? "internal",
             organisationId: config.organisationId ?? null,
             impersonateUserStorageKey: config.impersonateUserStorageKey ?? "impersonate_user_id",
         };
+        this.auth = auth ?? null;
+    }
+    /** Attach a stats collector. Call with `null` to detach. */
+    setStats(stats) {
+        this.stats = stats;
     }
     async request(options) {
+        const startedAt = this.stats?.recordRestStart() ?? null;
+        try {
+            const payload = await this.doRequest(options);
+            this.stats?.recordRestEnd(startedAt, true);
+            return payload;
+        }
+        catch (err) {
+            this.stats?.recordRestEnd(startedAt, false);
+            throw err;
+        }
+    }
+    async doRequest(options) {
+        if (this.auth) {
+            await this.auth.ensureReady();
+        }
         const method = options.method ?? "GET";
         const url = this.buildUrl(options.baseUrl ?? this.config.dataRestUrl, options.path, options.query);
         const headers = new Headers(options.headers);
         const body = this.normalizeBody(options.body, headers);
+        // Merge auth headers.
+        if (this.auth) {
+            const authHeaders = await this.auth.getHttpHeaders();
+            for (const [key, value] of Object.entries(authHeaders)) {
+                headers.set(key, value);
+            }
+        }
         if (!options.omitSharingHeader) {
             headers.set("X-Doover-Sharing", this.config.sharing);
         }
@@ -26,12 +54,15 @@ class RestClient {
         if (impersonated) {
             headers.set("X-Doover-Assume", impersonated);
         }
+        const credentials = this.auth
+            ? this.auth.getFetchCredentials()
+            : "include";
         const fetchImpl = this.config.fetchImpl ?? fetch;
         const response = await fetchImpl(url, {
             method,
             headers,
             body,
-            credentials: "include",
+            credentials,
         });
         const payload = await this.parseResponse(response);
         if (!response.ok) {

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { DooverClient } from "./client/doover-client";
+export { getDooverClient, peekDooverClient, resetDooverClient, } from "./client/singleton";
+export { DooverStatsCollector } from "./client/stats";
+export type { DooverStatsSnapshot, RestStatsSnapshot, GatewayStatsSnapshot, } from "./client/stats";
 export { AgentsApi } from "./apis/agents-api";
 export { AggregatesApi } from "./apis/aggregates-api";
 export { AlarmsApi } from "./apis/alarms-api";
@@ -9,6 +12,15 @@ export { NotificationsApi } from "./apis/notifications-api";
 export { PermissionsApi } from "./apis/permissions-api";
 export { ProcessorsApi } from "./apis/processors-api";
 export { TurnApi } from "./apis/turn-api";
+export { DooverAuth } from "./auth/doover-auth";
+export { CookieAuth } from "./auth/cookie-auth";
+export { DooverTokenAuth } from "./auth/doover-token-auth";
+export { AuthProfile } from "./auth/auth-profile";
+export type { AuthProfileData } from "./auth/auth-profile";
+export type { AuthProfileStore } from "./auth/auth-store";
+export { DooverAuthError } from "./auth/errors";
+export { buildAuth } from "./auth/build-auth";
+export type { AuthConfig } from "./auth/build-auth";
 export { GatewayClient } from "./gateway/gateway-client";
 export type * from "./gateway/types";
 export { RestClient } from "./http/rest-client";

package/dist/index.js

@@ -1,8 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverClient = void 0;
+exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = 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.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.DooverClient = void 0;
 var doover_client_1 = require("./client/doover-client");
 Object.defineProperty(exports, "DooverClient", { enumerable: true, get: function () { return doover_client_1.DooverClient; } });
+var singleton_1 = require("./client/singleton");
+Object.defineProperty(exports, "getDooverClient", { enumerable: true, get: function () { return singleton_1.getDooverClient; } });
+Object.defineProperty(exports, "peekDooverClient", { enumerable: true, get: function () { return singleton_1.peekDooverClient; } });
+Object.defineProperty(exports, "resetDooverClient", { enumerable: true, get: function () { return singleton_1.resetDooverClient; } });
+var stats_1 = require("./client/stats");
+Object.defineProperty(exports, "DooverStatsCollector", { enumerable: true, get: function () { return stats_1.DooverStatsCollector; } });
 var agents_api_1 = require("./apis/agents-api");
 Object.defineProperty(exports, "AgentsApi", { enumerable: true, get: function () { return agents_api_1.AgentsApi; } });
 var aggregates_api_1 = require("./apis/aggregates-api");
@@ -23,14 +29,26 @@ var processors_api_1 = require("./apis/processors-api");
 Object.defineProperty(exports, "ProcessorsApi", { enumerable: true, get: function () { return processors_api_1.ProcessorsApi; } });
 var turn_api_1 = require("./apis/turn-api");
 Object.defineProperty(exports, "TurnApi", { enumerable: true, get: function () { return turn_api_1.TurnApi; } });
+var doover_auth_1 = require("./auth/doover-auth");
+Object.defineProperty(exports, "DooverAuth", { enumerable: true, get: function () { return doover_auth_1.DooverAuth; } });
+var cookie_auth_1 = require("./auth/cookie-auth");
+Object.defineProperty(exports, "CookieAuth", { enumerable: true, get: function () { return cookie_auth_1.CookieAuth; } });
+var doover_token_auth_1 = require("./auth/doover-token-auth");
+Object.defineProperty(exports, "DooverTokenAuth", { enumerable: true, get: function () { return doover_token_auth_1.DooverTokenAuth; } });
+var auth_profile_1 = require("./auth/auth-profile");
+Object.defineProperty(exports, "AuthProfile", { enumerable: true, get: function () { return auth_profile_1.AuthProfile; } });
+var errors_1 = require("./auth/errors");
+Object.defineProperty(exports, "DooverAuthError", { enumerable: true, get: function () { return errors_1.DooverAuthError; } });
+var build_auth_1 = require("./auth/build-auth");
+Object.defineProperty(exports, "buildAuth", { enumerable: true, get: function () { return build_auth_1.buildAuth; } });
 var gateway_client_1 = require("./gateway/gateway-client");
 Object.defineProperty(exports, "GatewayClient", { enumerable: true, get: function () { return gateway_client_1.GatewayClient; } });
 var rest_client_1 = require("./http/rest-client");
 Object.defineProperty(exports, "RestClient", { enumerable: true, get: function () { return rest_client_1.RestClient; } });
-var errors_1 = require("./http/errors");
-Object.defineProperty(exports, "DooverApiError", { enumerable: true, get: function () { return errors_1.DooverApiError; } });
-Object.defineProperty(exports, "DooverGatewayError", { enumerable: true, get: function () { return errors_1.DooverGatewayError; } });
-Object.defineProperty(exports, "DooverValidationError", { enumerable: true, get: function () { return errors_1.DooverValidationError; } });
+var errors_2 = require("./http/errors");
+Object.defineProperty(exports, "DooverApiError", { enumerable: true, get: function () { return errors_2.DooverApiError; } });
+Object.defineProperty(exports, "DooverGatewayError", { enumerable: true, get: function () { return errors_2.DooverGatewayError; } });
+Object.defineProperty(exports, "DooverValidationError", { enumerable: true, get: function () { return errors_2.DooverValidationError; } });
 var doover_data_provider_1 = require("./viewer/doover-data-provider");
 Object.defineProperty(exports, "DooverDataProvider", { enumerable: true, get: function () { return doover_data_provider_1.DooverDataProvider; } });
 var path_parsing_1 = require("./viewer/path-parsing");

package/dist/node/config-manager.d.ts

@@ -0,0 +1,34 @@
+import { AuthProfile } from "../auth/auth-profile";
+import type { AuthProfileStore } from "../auth/auth-store";
+/**
+ * File-backed profile store compatible with pydoover's config format.
+ *
+ * Reads `~/.doover/config` (or a custom path) synchronously on construction,
+ * matching Python's eager-read model.
+ *
+ * Behaviour:
+ * - Doover2 `[profile=...]` blocks are parsed into `AuthProfile` entries.
+ * - Legacy Doover1 `[...]` blocks and unrecognised raw blocks are preserved
+ *   verbatim in their original order and written back unchanged.
+ * - `write()` creates the `~/.doover` directory if missing.
+ */
+export declare class ConfigManager implements AuthProfileStore {
+    currentProfile: string | null;
+    current: AuthProfile | null;
+    /** Parsed Doover2 profiles keyed by profile name. */
+    private profiles;
+    /**
+     * Ordered list of *blocks* in the file as they were originally read. Each
+     * entry is either a `{ type: "managed"; name: string }` reference into
+     * `this.profiles`, or a `{ type: "raw"; text: string }` blob that is
+     * preserved verbatim.
+     */
+    private blocks;
+    private readonly configPath;
+    constructor(configPath?: string);
+    get(profileName: string): AuthProfile | undefined;
+    create(entry: AuthProfile): void;
+    delete(profileName: string): void;
+    write(): void;
+    private read;
+}