doover-js 0.1.2 → 0.2.0

package/dist/auth/doover-token-auth.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DooverTokenAuth = void 0;
+const doover_auth_1 = require("./doover-auth");
+const errors_1 = require("./errors");
+const jwt_1 = require("./jwt");
+/** Buffer in milliseconds before expiry at which we trigger a refresh (30 s). */
+const REFRESH_BUFFER_MS = 30000;
+class DooverTokenAuth extends doover_auth_1.DooverAuth {
+    constructor(options) {
+        super();
+        this.refreshInFlight = null;
+        this.token = options.token ?? null;
+        this.tokenExpires = this.resolveExpiry(options.tokenExpires, options.token ?? null);
+        this.refreshToken = options.refreshToken ?? null;
+        this.refreshTokenId = options.refreshTokenId ?? null;
+        this.authServerUrl = options.authServerUrl ?? null;
+        this.authServerClientId = options.authServerClientId ?? null;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    // ------------------------------------------------------------------
+    // DooverAuth interface
+    // ------------------------------------------------------------------
+    async getHttpHeaders() {
+        if (!this.token) {
+            return {};
+        }
+        return { Authorization: `Bearer ${this.token}` };
+    }
+    getFetchCredentials() {
+        return "omit";
+    }
+    async prepareWebSocket(url, canUseHeaders) {
+        if (!this.token) {
+            return { url };
+        }
+        if (canUseHeaders) {
+            return {
+                url,
+                headers: { Authorization: `Bearer ${this.token}` },
+            };
+        }
+        // Append token as a query parameter for browser-style WebSocket.
+        const parsed = new URL(url);
+        parsed.searchParams.set("token", this.token);
+        return { url: parsed.toString() };
+    }
+    setToken(token, tokenExpires) {
+        this.token = token;
+        this.tokenExpires = this.resolveExpiry(tokenExpires, token);
+    }
+    async ensureReady() {
+        if (!this.needsRefresh()) {
+            return;
+        }
+        // Deduplicate concurrent refresh attempts.
+        if (!this.refreshInFlight) {
+            this.refreshInFlight = this.refresh().finally(() => {
+                this.refreshInFlight = null;
+            });
+        }
+        return this.refreshInFlight;
+    }
+    // ------------------------------------------------------------------
+    // Profile attachment override — load refresh metadata from profile
+    // ------------------------------------------------------------------
+    attachProfile(profile, configManager) {
+        super.attachProfile(profile, configManager);
+        // Back-fill fields from the profile where not already set.
+        if (!this.token && profile.token) {
+            this.token = profile.token;
+        }
+        if (!this.tokenExpires && profile.tokenExpires) {
+            this.tokenExpires = new Date(profile.tokenExpires);
+        }
+        if (!this.tokenExpires && this.token) {
+            this.tokenExpires = (0, jwt_1.decodeTokenExpiry)(this.token);
+        }
+        if (!this.refreshToken && profile.refreshToken) {
+            this.refreshToken = profile.refreshToken;
+        }
+        if (!this.refreshTokenId && profile.refreshTokenId) {
+            this.refreshTokenId = profile.refreshTokenId;
+        }
+        if (!this.authServerUrl && profile.authServerUrl) {
+            this.authServerUrl = profile.authServerUrl;
+        }
+        if (!this.authServerClientId && profile.authServerClientId) {
+            this.authServerClientId = profile.authServerClientId;
+        }
+    }
+    // ------------------------------------------------------------------
+    // Internal
+    // ------------------------------------------------------------------
+    needsRefresh() {
+        if (!this.token) {
+            return true;
+        }
+        if (!this.tokenExpires) {
+            return false;
+        }
+        return this.tokenExpires.getTime() - Date.now() < REFRESH_BUFFER_MS;
+    }
+    async refresh() {
+        if (!this.authServerUrl ||
+            !this.refreshToken ||
+            !this.authServerClientId) {
+            throw new errors_1.DooverAuthError("Cannot refresh token: missing authServerUrl, refreshToken, or authServerClientId");
+        }
+        const url = new URL(`${this.authServerUrl}/oauth2/token`);
+        url.searchParams.set("grant_type", "refresh_token");
+        if (this.token) {
+            url.searchParams.set("access_token", this.token);
+        }
+        url.searchParams.set("refresh_token", this.refreshToken);
+        url.searchParams.set("client_id", this.authServerClientId);
+        let response;
+        try {
+            response = await this.fetchImpl(url.toString(), {
+                method: "POST",
+            });
+        }
+        catch (err) {
+            throw new errors_1.DooverAuthError(`Token refresh request failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!response.ok) {
+            throw new errors_1.DooverAuthError(`Token refresh failed with status ${response.status}`);
+        }
+        const body = (await response.json());
+        if (!body.access_token) {
+            throw new errors_1.DooverAuthError("Token refresh response did not contain an access_token");
+        }
+        this.token = body.access_token;
+        this.tokenExpires =
+            typeof body.expires_in === "number"
+                ? new Date(Date.now() + body.expires_in * 1000)
+                : (0, jwt_1.decodeTokenExpiry)(body.access_token);
+        if (body.refresh_token) {
+            this.refreshToken = body.refresh_token;
+        }
+        // Persist back to profile / config manager.
+        this.persistToProfile();
+    }
+    persistToProfile() {
+        if (!this.profile) {
+            return;
+        }
+        this.profile.token = this.token;
+        this.profile.tokenExpires = this.tokenExpires
+            ? this.tokenExpires.toISOString()
+            : null;
+        if (this.refreshToken) {
+            this.profile.refreshToken = this.refreshToken;
+        }
+        if (this.configManager) {
+            try {
+                this.configManager.create(this.profile);
+                this.configManager.write();
+            }
+            catch (err) {
+                throw new errors_1.DooverAuthError(`Failed to persist refreshed token: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    resolveExpiry(explicit, token) {
+        if (explicit instanceof Date) {
+            return explicit;
+        }
+        if (typeof explicit === "number") {
+            return new Date(explicit);
+        }
+        if (token) {
+            return (0, jwt_1.decodeTokenExpiry)(token);
+        }
+        return null;
+    }
+}
+exports.DooverTokenAuth = DooverTokenAuth;

package/dist/auth/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class DooverAuthError extends Error {
+    constructor(message: string);
+}

package/dist/auth/errors.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DooverAuthError = void 0;
+class DooverAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DooverAuthError";
+    }
+}
+exports.DooverAuthError = DooverAuthError;

package/dist/auth/jwt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Decode the `exp` claim from a JWT without verifying the signature.
+ * Returns the expiry as a `Date`, or `null` if the token has no `exp` claim
+ * or cannot be decoded.
+ */
+export declare function decodeTokenExpiry(token: string): Date | null;

package/dist/auth/jwt.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeTokenExpiry = decodeTokenExpiry;
+/**
+ * Decode the `exp` claim from a JWT without verifying the signature.
+ * Returns the expiry as a `Date`, or `null` if the token has no `exp` claim
+ * or cannot be decoded.
+ */
+function decodeTokenExpiry(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length < 2) {
+            return null;
+        }
+        // Base64url → Base64 → decode
+        const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const json = typeof atob === "function"
+            ? atob(base64)
+            : Buffer.from(base64, "base64").toString("utf-8");
+        const payload = JSON.parse(json);
+        if (typeof payload.exp !== "number") {
+            return null;
+        }
+        return new Date(payload.exp * 1000);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -8,10 +8,13 @@ import { NotificationsApi } from "../apis/notifications-api";
 import { PermissionsApi } from "../apis/permissions-api";
 import { ProcessorsApi } from "../apis/processors-api";
 import { TurnApi } from "../apis/turn-api";
+import type { DooverAuth } from "../auth/doover-auth";
 import { GatewayClient } from "../gateway/gateway-client";
 import { RestClient, type DooverClientConfig } from "../http/rest-client";
 import { DooverDataProvider } from "../viewer/doover-data-provider";
+import { DooverStatsCollector, type DooverStatsSnapshot } from "./stats";
 export declare class DooverClient {
+    readonly auth: DooverAuth;
     readonly rest: RestClient;
     readonly viewer: DooverDataProvider;
     readonly channels: ChannelsApi;
@@ -25,5 +28,17 @@ export declare class DooverClient {
     readonly turn: TurnApi;
     readonly agents: AgentsApi;
     readonly gateway: GatewayClient;
+    /** Opt-in instrumentation. Disabled by default — see {@link enableStats}. */
+    readonly stats: DooverStatsCollector;
     constructor(config: DooverClientConfig);
+    /** Start capturing request/message stats. Off by default. */
+    enableStats(): void;
+    /** Stop capturing stats. Existing counters are retained; call `stats.reset()` to clear. */
+    disableStats(): void;
+    /**
+     * Snapshot the current stats. Returns zeroed counters if stats were
+     * never enabled. Combine with {@link GatewayClient.getSubscriptionCount}
+     * and {@link GatewayClient.getSession} for a full debug view.
+     */
+    getStats(): DooverStatsSnapshot;
 }

package/dist/client/doover-client.js

@@ -11,13 +11,26 @@ const notifications_api_1 = require("../apis/notifications-api");
 const permissions_api_1 = require("../apis/permissions-api");
 const processors_api_1 = require("../apis/processors-api");
 const turn_api_1 = require("../apis/turn-api");
-const gateway_client_1 = require("../gateway/gateway-client");
+const build_auth_1 = require("../auth/build-auth");
 const rest_client_1 = require("../http/rest-client");
 const doover_data_provider_1 = require("../viewer/doover-data-provider");
+const stats_1 = require("./stats");
 class DooverClient {
     constructor(config) {
-        this.rest = new rest_client_1.RestClient(config);
-        this.viewer = new doover_data_provider_1.DooverDataProvider(config);
+        this.auth = (0, build_auth_1.buildAuth)({
+            auth: config.auth,
+            profile: config.profile,
+            configManager: config.configManager,
+            token: config.token,
+            tokenExpires: config.tokenExpires,
+            refreshToken: config.refreshToken,
+            refreshTokenId: config.refreshTokenId,
+            authServerUrl: config.authServerUrl,
+            authServerClientId: config.authServerClientId,
+            fetchImpl: config.fetchImpl,
+        });
+        this.rest = new rest_client_1.RestClient(config, this.auth);
+        this.viewer = new doover_data_provider_1.DooverDataProvider(config, this.auth);
         this.channels = new channels_api_1.ChannelsApi(this.rest);
         this.messages = new messages_api_1.MessagesApi(this.rest);
         this.aggregates = new aggregates_api_1.AggregatesApi(this.rest);
@@ -28,7 +41,35 @@ class DooverClient {
         this.processors = new processors_api_1.ProcessorsApi(this.rest);
         this.turn = new turn_api_1.TurnApi(this.rest);
         this.agents = new agents_api_1.AgentsApi(this.rest);
-        this.gateway = new gateway_client_1.GatewayClient(config);
+        // Reuse the viewer's gateway so `client.gateway` and
+        // `client.viewer.gateway` are the same instance → one WebSocket per
+        // client. Without this, `client.gateway.connect()` and
+        // `client.viewer.subscribeToChannel(...)` each opened their own socket.
+        this.gateway = this.viewer.gateway;
+        // Stats collector, disabled by default. Attached to both REST clients
+        // (facade + viewer's internal) and the shared gateway so every recorded
+        // call flows through the same counters. Pay-to-play: record methods
+        // short-circuit when disabled.
+        this.stats = new stats_1.DooverStatsCollector();
+        this.rest.setStats(this.stats);
+        this.viewer.rest.setStats(this.stats);
+        this.gateway.setStats(this.stats);
+    }
+    /** Start capturing request/message stats. Off by default. */
+    enableStats() {
+        this.stats.setEnabled(true);
+    }
+    /** Stop capturing stats. Existing counters are retained; call `stats.reset()` to clear. */
+    disableStats() {
+        this.stats.setEnabled(false);
+    }
+    /**
+     * Snapshot the current stats. Returns zeroed counters if stats were
+     * never enabled. Combine with {@link GatewayClient.getSubscriptionCount}
+     * and {@link GatewayClient.getSession} for a full debug view.
+     */
+    getStats() {
+        return this.stats.snapshot();
     }
 }
 exports.DooverClient = DooverClient;

package/dist/client/singleton.d.ts

@@ -0,0 +1,26 @@
+import type { DooverClientConfig } from "../http/rest-client";
+import { DooverClient } from "./doover-client";
+/**
+ * Get the process-wide `DooverClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_client__` to survive module-level duplicates
+ * — if this module is loaded more than once (HMR, federation boundaries,
+ * multiple bundles) each load still returns the same instance and therefore
+ * the same WebSocket + REST configuration.
+ *
+ * The first caller's `config` wins. Subsequent calls ignore the `config`
+ * arg and return the existing instance — log a warning if they differ so
+ * drift is visible in dev tools.
+ */
+export declare function getDooverClient(config: DooverClientConfig): DooverClient;
+/**
+ * Returns the current singleton if one has been initialised, otherwise
+ * `null`. Useful for callers that want to read the client opportunistically
+ * without forcing construction.
+ */
+export declare function peekDooverClient(): DooverClient | null;
+/**
+ * Clear the singleton. Primarily for tests — not recommended in production
+ * code since any active subscriptions reference the old instance.
+ */
+export declare function resetDooverClient(): void;

package/dist/client/singleton.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDooverClient = getDooverClient;
+exports.peekDooverClient = peekDooverClient;
+exports.resetDooverClient = resetDooverClient;
+const doover_client_1 = require("./doover-client");
+const GLOBAL_KEY = "__doover_js_client__";
+function globalBag() {
+    return globalThis;
+}
+/**
+ * Get the process-wide `DooverClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_client__` to survive module-level duplicates
+ * — if this module is loaded more than once (HMR, federation boundaries,
+ * multiple bundles) each load still returns the same instance and therefore
+ * the same WebSocket + REST configuration.
+ *
+ * The first caller's `config` wins. Subsequent calls ignore the `config`
+ * arg and return the existing instance — log a warning if they differ so
+ * drift is visible in dev tools.
+ */
+function getDooverClient(config) {
+    const bag = globalBag();
+    const existing = bag[GLOBAL_KEY];
+    if (existing) {
+        if (configsDiffer(existing, config)) {
+            // eslint-disable-next-line no-console
+            console.warn("[doover-js] getDooverClient called with a config that differs " +
+                "from the already-initialised singleton. The existing client is " +
+                "being reused; the new config is ignored.");
+        }
+        return existing;
+    }
+    const client = new doover_client_1.DooverClient(config);
+    bag[GLOBAL_KEY] = client;
+    return client;
+}
+/**
+ * Returns the current singleton if one has been initialised, otherwise
+ * `null`. Useful for callers that want to read the client opportunistically
+ * without forcing construction.
+ */
+function peekDooverClient() {
+    return globalBag()[GLOBAL_KEY] ?? null;
+}
+/**
+ * Clear the singleton. Primarily for tests — not recommended in production
+ * code since any active subscriptions reference the old instance.
+ */
+function resetDooverClient() {
+    delete globalBag()[GLOBAL_KEY];
+}
+function configsDiffer(existing, next) {
+    const a = existing.rest.config;
+    return (a.dataRestUrl !== next.dataRestUrl ||
+        a.dataWssUrl !== next.dataWssUrl ||
+        a.controlApiUrl !== next.controlApiUrl);
+}

package/dist/client/stats.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Opt-in instrumentation for `DooverClient`. When enabled, counts REST
+ * requests and gateway messages and keeps running latency stats. Disabled
+ * by default — the record methods short-circuit so production apps pay
+ * nothing unless a debug UI turns it on.
+ */
+export interface RestStatsSnapshot {
+    enabled: boolean;
+    /** Total requests started since stats were enabled (or last reset). */
+    totalRequests: number;
+    /** Requests currently in flight. */
+    pendingRequests: number;
+    /** Requests that resolved successfully. */
+    completedRequests: number;
+    /** Requests that threw / rejected. */
+    failedRequests: number;
+    /** Mean latency of settled requests, ms. Null until at least one lands. */
+    averageLatencyMs: number | null;
+    /** Latency of the most recently settled request, ms. */
+    lastLatencyMs: number | null;
+}
+export interface GatewayStatsSnapshot {
+    enabled: boolean;
+    /** Frames we've sent on the gateway socket. */
+    messagesSent: number;
+    /** Frames we've received on the gateway socket. */
+    messagesReceived: number;
+}
+export interface DooverStatsSnapshot {
+    rest: RestStatsSnapshot;
+    gateway: GatewayStatsSnapshot;
+}
+export declare class DooverStatsCollector {
+    private enabled;
+    private rTotal;
+    private rPending;
+    private rCompleted;
+    private rFailed;
+    private rLatencySum;
+    private rLastLatency;
+    private gSent;
+    private gReceived;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    reset(): void;
+    /**
+     * Record the start of a REST request. Returns the start timestamp the
+     * caller must hand back to `recordRestEnd`, or `null` if stats are off.
+     */
+    recordRestStart(): number | null;
+    recordRestEnd(startedAt: number | null, succeeded: boolean): void;
+    recordGatewaySent(): void;
+    recordGatewayReceived(): void;
+    snapshot(): DooverStatsSnapshot;
+}

package/dist/client/stats.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Opt-in instrumentation for `DooverClient`. When enabled, counts REST
+ * requests and gateway messages and keeps running latency stats. Disabled
+ * by default — the record methods short-circuit so production apps pay
+ * nothing unless a debug UI turns it on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DooverStatsCollector = void 0;
+class DooverStatsCollector {
+    constructor() {
+        this.enabled = false;
+        this.rTotal = 0;
+        this.rPending = 0;
+        this.rCompleted = 0;
+        this.rFailed = 0;
+        this.rLatencySum = 0;
+        this.rLastLatency = null;
+        this.gSent = 0;
+        this.gReceived = 0;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    reset() {
+        this.rTotal = 0;
+        this.rPending = 0;
+        this.rCompleted = 0;
+        this.rFailed = 0;
+        this.rLatencySum = 0;
+        this.rLastLatency = null;
+        this.gSent = 0;
+        this.gReceived = 0;
+    }
+    /**
+     * Record the start of a REST request. Returns the start timestamp the
+     * caller must hand back to `recordRestEnd`, or `null` if stats are off.
+     */
+    recordRestStart() {
+        if (!this.enabled)
+            return null;
+        this.rTotal += 1;
+        this.rPending += 1;
+        return now();
+    }
+    recordRestEnd(startedAt, succeeded) {
+        if (!this.enabled || startedAt === null)
+            return;
+        this.rPending = Math.max(0, this.rPending - 1);
+        if (succeeded)
+            this.rCompleted += 1;
+        else
+            this.rFailed += 1;
+        const latency = now() - startedAt;
+        this.rLastLatency = latency;
+        this.rLatencySum += latency;
+    }
+    recordGatewaySent() {
+        if (!this.enabled)
+            return;
+        this.gSent += 1;
+    }
+    recordGatewayReceived() {
+        if (!this.enabled)
+            return;
+        this.gReceived += 1;
+    }
+    snapshot() {
+        const settled = this.rCompleted + this.rFailed;
+        return {
+            rest: {
+                enabled: this.enabled,
+                totalRequests: this.rTotal,
+                pendingRequests: this.rPending,
+                completedRequests: this.rCompleted,
+                failedRequests: this.rFailed,
+                averageLatencyMs: settled > 0 ? this.rLatencySum / settled : null,
+                lastLatencyMs: this.rLastLatency,
+            },
+            gateway: {
+                enabled: this.enabled,
+                messagesSent: this.gSent,
+                messagesReceived: this.gReceived,
+            },
+        };
+    }
+}
+exports.DooverStatsCollector = DooverStatsCollector;
+function now() {
+    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+        return performance.now();
+    }
+    return Date.now();
+}

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

@@ -1,3 +1,5 @@
+import type { DooverAuth } from "../auth/doover-auth";
+import type { DooverStatsCollector } from "../client/stats";
 import type { DooverClientConfig } from "../http/rest-client";
 import type { GatewayListenerMap, WebSocketSession } from "./types";
 import type { ChannelRef, JSONValue } from "../types/common";
@@ -5,14 +7,21 @@ export declare class GatewayClient {
     private readonly config;
     private socket;
     private session;
-    private heartbeatTimer;
-    private lastHeartbeatAt;
-    private missedHeartbeats;
     private reconnectTimer;
+    private reconnectAttempts;
+    /** Set when the consumer explicitly disconnects — suppresses reconnect. */
+    private explicitlyDisconnected;
+    /** Guards against concurrent connect() callers creating duplicate sockets. */
+    private opening;
     private listeners;
     private subscriptions;
-    constructor(config: DooverClientConfig);
-    connect(): void;
+    private readonly auth;
+    private stats;
+    constructor(config: DooverClientConfig, auth?: DooverAuth);
+    /** Attach a stats collector. Call with `null` to detach. */
+    setStats(stats: DooverStatsCollector | null): void;
+    connect(): Promise<void>;
+    private openSocket;
     disconnect(code?: number, reason?: string): void;
     on<K extends keyof GatewayListenerMap>(eventName: K, listener: GatewayListenerMap[K]): void;
     off<K extends keyof GatewayListenerMap>(eventName: K, listener: GatewayListenerMap[K]): void;
@@ -23,15 +32,32 @@ export declare class GatewayClient {
     syncChannel(channel: ChannelRef): void;
     sendOneShotMessage(channel: ChannelRef, data: JSONValue): void;
     getSession(): WebSocketSession | null;
-    getLatency(): number | null;
     isConnected(): boolean;
+    /** Number of channels the gateway is currently subscribed to. */
+    getSubscriptionCount(): number;
+    /** Snapshot of currently subscribed channels (for debug/inspection). */
+    getSubscriptions(): ChannelRef[];
+    /**
+     * 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.
+     */
+    reconnect(): Promise<void>;
     private handleMessage;
     private identifyOrResume;
     private resubscribeAll;
-    private startHeartbeat;
-    private stopHeartbeat;
     private send;
     private emit;
     private scheduleReconnect;
+    /** Exponential backoff with full-jitter, capped at RECONNECT_CAP_MS. */
+    private computeReconnectDelay;
+    private installLifecycleListeners;
+    private handleVisibilityChange;
+    private 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.
+     */
+    private tryImmediateReconnect;
     private channelKey;
 }