doover-js 0.1.2 → 0.2.0-alpha.0

package/README.md

@@ -4,22 +4,27 @@ TypeScript client for Doover.
 
 ## Exports
 
+### Root (`doover-js`)
+
 - `DooverClient`
 - `DooverDataProvider`
 - `GatewayClient`
-- `AgentsApi`
-- `ChannelsApi`
-- `MessagesApi`
-- `AggregatesApi`
-- `AlarmsApi`
-- `ConnectionsApi`
-- `NotificationsApi`
-- `PermissionsApi`
-- `ProcessorsApi`
-- `TurnApi`
+- `RestClient`
+- `DooverAuth`, `CookieAuth`, `DooverTokenAuth`
+- `AuthProfile`, `DooverAuthError`
+- `buildAuth`
+- `AgentsApi`, `ChannelsApi`, `MessagesApi`, `AggregatesApi`, `AlarmsApi`, `ConnectionsApi`, `NotificationsApi`, `PermissionsApi`, `ProcessorsApi`, `TurnApi`
+
+### Node subpath (`doover-js/node`)
+
+- `ConfigManager` — file-backed profile store (Node-only, uses `fs`)
 
 ## Usage
 
+### Cookie-only browser usage (default)
+
+When no auth inputs are provided, the client uses ambient cookies (`credentials: "include"`). This is the default browser behaviour and matches the original API.
+
 ```ts
 import { DooverClient } from "doover-js";
 
@@ -32,4 +37,93 @@ const client = new DooverClient({
 const channels = await client.viewer.getChannels({ agentId: "123" });
 ```
 
+### Explicit token usage
+
+Pass a token directly to use bearer auth. The client will send `Authorization: Bearer <token>` on every HTTP request and use `credentials: "omit"`.
+
+```ts
+import { DooverClient } from "doover-js";
+
+const client = new DooverClient({
+  dataRestUrl: "https://example.com/api",
+  controlApiUrl: "https://example.com/control",
+  dataWssUrl: "wss://example.com/gateway",
+  token: "your-access-token",
+  refreshToken: "your-refresh-token",
+  authServerUrl: "https://auth.example.com",
+  authServerClientId: "your-client-id",
+});
+
+// Token refresh happens automatically when the token expires
+const me = await client.rest.get("/users/me", undefined, client.rest.config.controlApiUrl);
+```
+
+### Profile / ConfigManager usage (Node)
+
+Use the `ConfigManager` from the `doover-js/node` subpath to load profiles from `~/.doover/config`, matching pydoover's config format.
+
+```ts
+import { DooverClient } from "doover-js";
+import { ConfigManager } from "doover-js/node";
+
+const configManager = new ConfigManager(); // reads ~/.doover/config
+const client = new DooverClient({
+  dataRestUrl: "https://example.com/api",
+  controlApiUrl: "https://example.com/control",
+  dataWssUrl: "wss://example.com/gateway",
+  profile: "production",
+  configManager,
+});
+```
+
+You can also pass an `AuthProfile` instance directly:
+
+```ts
+import { DooverClient, AuthProfile } from "doover-js";
+
+const profile = new AuthProfile({
+  profile: "custom",
+  token: "my-token",
+  refreshToken: "my-refresh-token",
+  authServerUrl: "https://auth.example.com",
+  authServerClientId: "client-id",
+});
+
+const client = new DooverClient({
+  dataRestUrl: "https://example.com/api",
+  controlApiUrl: "https://example.com/control",
+  dataWssUrl: "wss://example.com/gateway",
+  profile,
+});
+```
+
+### WebSocket auth behaviour
+
+The auth layer automatically handles websocket authentication:
+
+- **Cookie auth**: Uses the original websocket URL and relies on ambient cookies.
+- **Token auth with `webSocketFactory`**: Passes `Authorization: Bearer <token>` via headers.
+- **Token auth with standard `WebSocket`**: Appends `?token=<token>` to the websocket URL.
+
+For Node.js websocket clients that support custom headers, provide a `webSocketFactory`:
+
+```ts
+import WebSocket from "ws";
+import { DooverClient } from "doover-js";
+
+const client = new DooverClient({
+  dataRestUrl: "https://example.com/api",
+  controlApiUrl: "https://example.com/control",
+  dataWssUrl: "wss://example.com/gateway",
+  token: "your-token",
+  webSocketFactory: ({ url, headers }) => new WebSocket(url, { headers }),
+});
+```
+
+Reconnections automatically use the latest (potentially refreshed) token.
+
+## Architecture
+
+`DooverClient` builds one shared `DooverAuth` instance and injects it into `RestClient`, `DooverDataProvider`, and `GatewayClient`. Token refreshes propagate everywhere automatically.
+
 `DooverDataProvider` preserves the older viewer-oriented interface. `DooverClient` exposes the broader API surface through subclients.

package/dist/auth/auth-profile.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Browser-safe value object representing a single Doover auth profile.
+ *
+ * Property names use camelCase JS conventions. The static helpers `parse` and
+ * `dump` translate to/from the on-disk format shared with pydoover.
+ */
+export interface AuthProfileData {
+    profile?: string;
+    token?: string | null;
+    tokenExpires?: string | null;
+    agentId?: string | null;
+    controlBaseUrl?: string | null;
+    dataBaseUrl?: string | null;
+    refreshToken?: string | null;
+    refreshTokenId?: string | null;
+    authServerUrl?: string | null;
+    authServerClientId?: string | null;
+}
+export declare class AuthProfile {
+    profile: string;
+    token: string | null;
+    tokenExpires: string | null;
+    agentId: string | null;
+    controlBaseUrl: string | null;
+    dataBaseUrl: string | null;
+    refreshToken: string | null;
+    refreshTokenId: string | null;
+    authServerUrl: string | null;
+    authServerClientId: string | null;
+    constructor(data: AuthProfileData & {
+        profile: string;
+    });
+    /**
+     * Parse a block of lines (excluding the `[profile=...]` header) into an
+     * `AuthProfile`. The profile name must be provided separately.
+     */
+    static parse(profileName: string, lines: string[]): AuthProfile;
+    /**
+     * Serialise to the on-disk reduced format (without the `[profile=...]`
+     * header line, which the caller is responsible for).
+     */
+    dump(): string;
+    /** Full block including the header line. */
+    dumpBlock(): string;
+}

package/dist/auth/auth-profile.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthProfile = void 0;
+/** On-disk key → JS property mapping (pydoover reduced-format Doover2). */
+const DISK_KEY_MAP = {
+    TOKEN: "token",
+    TOKEN_EXPIRES: "tokenExpires",
+    AGENT_ID: "agentId",
+    BASE_URL: "controlBaseUrl",
+    BASE_DATA_URL: "dataBaseUrl",
+    REFRESH_TOKEN: "refreshToken",
+    REFRESH_TOKEN_ID: "refreshTokenId",
+    AUTH_SERVER_URL: "authServerUrl",
+    AUTH_SERVER_CLIENT_ID: "authServerClientId",
+};
+/** JS property → on-disk key mapping. */
+const JS_KEY_MAP = Object.fromEntries(Object.entries(DISK_KEY_MAP).map(([disk, js]) => [js, disk]));
+class AuthProfile {
+    constructor(data) {
+        this.profile = data.profile;
+        this.token = data.token ?? null;
+        this.tokenExpires = data.tokenExpires ?? null;
+        this.agentId = data.agentId ?? null;
+        this.controlBaseUrl = data.controlBaseUrl ?? null;
+        this.dataBaseUrl = data.dataBaseUrl ?? null;
+        this.refreshToken = data.refreshToken ?? null;
+        this.refreshTokenId = data.refreshTokenId ?? null;
+        this.authServerUrl = data.authServerUrl ?? null;
+        this.authServerClientId = data.authServerClientId ?? null;
+    }
+    /**
+     * Parse a block of lines (excluding the `[profile=...]` header) into an
+     * `AuthProfile`. The profile name must be provided separately.
+     */
+    static parse(profileName, lines) {
+        const data = { profile: profileName };
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eqIdx = trimmed.indexOf("=");
+            if (eqIdx === -1)
+                continue;
+            const key = trimmed.slice(0, eqIdx).trim();
+            const value = trimmed.slice(eqIdx + 1).trim();
+            const jsProp = DISK_KEY_MAP[key];
+            if (jsProp) {
+                data[jsProp] = value || null;
+            }
+        }
+        return new AuthProfile(data);
+    }
+    /**
+     * Serialise to the on-disk reduced format (without the `[profile=...]`
+     * header line, which the caller is responsible for).
+     */
+    dump() {
+        const lines = [];
+        for (const jsProp of Object.keys(JS_KEY_MAP)) {
+            const value = this[jsProp];
+            if (value !== null && value !== undefined) {
+                lines.push(`${JS_KEY_MAP[jsProp]}=${value}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    /** Full block including the header line. */
+    dumpBlock() {
+        return `[profile=${this.profile}]\n${this.dump()}`;
+    }
+}
+exports.AuthProfile = AuthProfile;

package/dist/auth/auth-store.d.ts

@@ -0,0 +1,14 @@
+import type { AuthProfile } from "./auth-profile";
+/**
+ * Structural interface for profile stores accepted by auth classes.
+ * Implementations may be backed by files (ConfigManager in the Node subpath)
+ * or by in-memory stores for testing.
+ */
+export interface AuthProfileStore {
+    currentProfile: string | null;
+    current: AuthProfile | null;
+    get(profileName: string): AuthProfile | undefined;
+    create(entry: AuthProfile): void;
+    delete(profileName: string): void;
+    write(): void;
+}

package/dist/auth/auth-store.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/build-auth.d.ts

@@ -0,0 +1,37 @@
+import type { AuthProfile } from "./auth-profile";
+import type { AuthProfileStore } from "./auth-store";
+import { DooverAuth } from "./doover-auth";
+/**
+ * Raw auth inputs that can be provided in client configs.
+ *
+ * If `auth` is provided it is used as-is and raw inputs must not be combined
+ * with it. Otherwise these fields are used to build the appropriate auth
+ * instance automatically.
+ */
+export interface AuthConfig {
+    auth?: DooverAuth;
+    profile?: string | AuthProfile;
+    configManager?: AuthProfileStore;
+    token?: string | null;
+    tokenExpires?: Date | number | null;
+    refreshToken?: string | null;
+    refreshTokenId?: string | null;
+    authServerUrl?: string | null;
+    authServerClientId?: string | null;
+}
+/** Fetch implementation to thread through to DooverTokenAuth. */
+interface BuildAuthOptions extends AuthConfig {
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Build a `DooverAuth` instance from the provided configuration.
+ *
+ * Rules:
+ * 1. If `auth` is provided it is returned as-is.
+ * 2. If any token-related field is present, build `DooverTokenAuth`.
+ * 3. If `profile` is an `AuthProfile`, use it to seed a `DooverTokenAuth`.
+ * 4. If `profile` is a string, look it up via `configManager`.
+ * 5. Otherwise fall back to `CookieAuth`.
+ */
+export declare function buildAuth(options: BuildAuthOptions): DooverAuth;
+export {};

package/dist/auth/build-auth.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAuth = buildAuth;
+const cookie_auth_1 = require("./cookie-auth");
+const doover_token_auth_1 = require("./doover-token-auth");
+const errors_1 = require("./errors");
+const TOKEN_FIELDS = [
+    "token",
+    "tokenExpires",
+    "refreshToken",
+    "refreshTokenId",
+    "authServerUrl",
+    "authServerClientId",
+];
+/**
+ * Build a `DooverAuth` instance from the provided configuration.
+ *
+ * Rules:
+ * 1. If `auth` is provided it is returned as-is.
+ * 2. If any token-related field is present, build `DooverTokenAuth`.
+ * 3. If `profile` is an `AuthProfile`, use it to seed a `DooverTokenAuth`.
+ * 4. If `profile` is a string, look it up via `configManager`.
+ * 5. Otherwise fall back to `CookieAuth`.
+ */
+function buildAuth(options) {
+    if (options.auth) {
+        // Validate mutual exclusivity.
+        const hasRaw = TOKEN_FIELDS.some((k) => options[k] !== undefined);
+        if (hasRaw || options.profile !== undefined || options.configManager !== undefined) {
+            throw new errors_1.DooverAuthError("Cannot combine 'auth' with raw auth config fields (token, profile, configManager, etc.)");
+        }
+        return options.auth;
+    }
+    // Resolve the profile object.
+    let resolvedProfile = null;
+    if (typeof options.profile === "string") {
+        if (!options.configManager) {
+            throw new errors_1.DooverAuthError("A 'configManager' (AuthProfileStore) is required when 'profile' is a string. " +
+                "Use the doover-js/node subpath to import ConfigManager, or provide an AuthProfile directly.");
+        }
+        resolvedProfile = options.configManager.get(options.profile) ?? null;
+        if (!resolvedProfile) {
+            throw new errors_1.DooverAuthError(`Profile '${options.profile}' not found in the config manager`);
+        }
+    }
+    else if (options.profile instanceof Object && "profile" in options.profile) {
+        // AuthProfile instance
+        resolvedProfile = options.profile;
+    }
+    // Determine whether we need token auth.
+    const hasTokenInput = TOKEN_FIELDS.some((k) => options[k] !== undefined);
+    const profileHasToken = resolvedProfile?.token != null;
+    if (!hasTokenInput && !profileHasToken) {
+        // No token data at all — fall back to cookie auth.
+        const auth = new cookie_auth_1.CookieAuth();
+        if (resolvedProfile) {
+            auth.attachProfile(resolvedProfile, options.configManager);
+        }
+        return auth;
+    }
+    // Build DooverTokenAuth with explicit fields overriding profile values.
+    const auth = new doover_token_auth_1.DooverTokenAuth({
+        token: options.token ?? undefined,
+        tokenExpires: options.tokenExpires ?? undefined,
+        refreshToken: options.refreshToken ?? undefined,
+        refreshTokenId: options.refreshTokenId ?? undefined,
+        authServerUrl: options.authServerUrl ?? undefined,
+        authServerClientId: options.authServerClientId ?? undefined,
+        fetchImpl: options.fetchImpl,
+    });
+    if (resolvedProfile) {
+        auth.attachProfile(resolvedProfile, options.configManager);
+    }
+    return auth;
+}

package/dist/auth/cookie-auth.d.ts

@@ -0,0 +1,17 @@
+import { DooverAuth } from "./doover-auth";
+/**
+ * Cookie-based auth — the default browser strategy.
+ *
+ * Relies on ambient cookies (`credentials: "include"`) and does not add any
+ * `Authorization` header. Token refresh is not applicable.
+ */
+export declare class CookieAuth extends DooverAuth {
+    getHttpHeaders(): Promise<Record<string, string>>;
+    getFetchCredentials(): RequestCredentials;
+    prepareWebSocket(url: string, _canUseHeaders: boolean): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    setToken(_token: string | null, _tokenExpires?: Date | number | null): void;
+    ensureReady(): Promise<void>;
+}

package/dist/auth/cookie-auth.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CookieAuth = void 0;
+const doover_auth_1 = require("./doover-auth");
+/**
+ * Cookie-based auth — the default browser strategy.
+ *
+ * Relies on ambient cookies (`credentials: "include"`) and does not add any
+ * `Authorization` header. Token refresh is not applicable.
+ */
+class CookieAuth extends doover_auth_1.DooverAuth {
+    async getHttpHeaders() {
+        return {};
+    }
+    getFetchCredentials() {
+        return "include";
+    }
+    async prepareWebSocket(url, _canUseHeaders) {
+        // Cookie auth relies on ambient cookies — no URL or header changes.
+        return { url };
+    }
+    setToken(_token, _tokenExpires) {
+        // No-op for cookie auth.
+    }
+    async ensureReady() {
+        // Nothing to prepare for cookie auth.
+    }
+}
+exports.CookieAuth = CookieAuth;

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

@@ -0,0 +1,41 @@
+import type { AuthProfile } from "./auth-profile";
+import type { AuthProfileStore } from "./auth-store";
+/**
+ * Abstract base class shared by cookie and token auth strategies.
+ *
+ * Every client (`RestClient`, `GatewayClient`, `DooverDataProvider`) holds a
+ * reference to one `DooverAuth` instance so that refreshed tokens propagate
+ * everywhere automatically.
+ */
+export declare abstract class DooverAuth {
+    protected profile: AuthProfile | null;
+    protected configManager: AuthProfileStore | null;
+    /** Headers to merge into every outgoing HTTP request. */
+    abstract getHttpHeaders(): Promise<Record<string, string>>;
+    /** The `credentials` value for `fetch()`. */
+    abstract getFetchCredentials(): RequestCredentials;
+    /**
+     * Prepare websocket connection parameters.
+     *
+     * @param url          The base websocket URL.
+     * @param canUseHeaders `true` when a `webSocketFactory` that supports
+     *                       custom headers is available.
+     * @returns An object with the (possibly modified) URL and optional headers.
+     */
+    abstract prepareWebSocket(url: string, canUseHeaders: boolean): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    /**
+     * Imperatively set or clear the current access token.
+     * Subclasses that do not use tokens may no-op.
+     */
+    abstract setToken(token: string | null, tokenExpires?: Date | number | null): void;
+    /**
+     * Ensure the auth layer is ready (e.g. token refreshed if needed).
+     * Called before every HTTP request and before opening a websocket.
+     */
+    abstract ensureReady(): Promise<void>;
+    /** Attach a profile and optional config manager for refresh persistence. */
+    attachProfile(profile: AuthProfile, configManager?: AuthProfileStore): void;
+}

package/dist/auth/doover-auth.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DooverAuth = void 0;
+/**
+ * Abstract base class shared by cookie and token auth strategies.
+ *
+ * Every client (`RestClient`, `GatewayClient`, `DooverDataProvider`) holds a
+ * reference to one `DooverAuth` instance so that refreshed tokens propagate
+ * everywhere automatically.
+ */
+class DooverAuth {
+    constructor() {
+        this.profile = null;
+        this.configManager = null;
+    }
+    /** Attach a profile and optional config manager for refresh persistence. */
+    attachProfile(profile, configManager) {
+        this.profile = profile;
+        if (configManager) {
+            this.configManager = configManager;
+        }
+    }
+}
+exports.DooverAuth = DooverAuth;

package/dist/auth/doover-token-auth.d.ts

@@ -0,0 +1,35 @@
+import { DooverAuth } from "./doover-auth";
+import type { AuthProfile } from "./auth-profile";
+import type { AuthProfileStore } from "./auth-store";
+export declare class DooverTokenAuth extends DooverAuth {
+    private token;
+    private tokenExpires;
+    private refreshToken;
+    private refreshTokenId;
+    private authServerUrl;
+    private authServerClientId;
+    private fetchImpl;
+    private refreshInFlight;
+    constructor(options: {
+        token?: string | null;
+        tokenExpires?: Date | number | null;
+        refreshToken?: string | null;
+        refreshTokenId?: string | null;
+        authServerUrl?: string | null;
+        authServerClientId?: string | null;
+        fetchImpl?: typeof fetch;
+    });
+    getHttpHeaders(): Promise<Record<string, string>>;
+    getFetchCredentials(): RequestCredentials;
+    prepareWebSocket(url: string, canUseHeaders: boolean): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    setToken(token: string | null, tokenExpires?: Date | number | null): void;
+    ensureReady(): Promise<void>;
+    attachProfile(profile: AuthProfile, configManager?: AuthProfileStore): void;
+    private needsRefresh;
+    private refresh;
+    private persistToProfile;
+    private resolveExpiry;
+}