doover-js 0.11.0 → 0.13.0

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

@@ -0,0 +1,217 @@
+import { DooverAuth } from "./doover-auth.js";
+import { DooverAuthError } from "./errors.js";
+import { decodeTokenExpiry } from "./jwt.js";
+/** Buffer in milliseconds before expiry at which we trigger a refresh (30 s). */
+const REFRESH_BUFFER_MS = 30000;
+export class DooverTokenAuth extends DooverAuth {
+    constructor(options) {
+        super();
+        this.refreshInFlight = null;
+        this.authInvalid = false;
+        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);
+        if (token) {
+            this.authInvalid = false;
+        }
+        this.persistToProfile();
+    }
+    setRefreshToken(refreshToken) {
+        this.refreshToken = refreshToken;
+        if (refreshToken) {
+            this.authInvalid = false;
+        }
+        this.persistToProfile();
+    }
+    async ensureReady() {
+        if (this.authInvalid) {
+            throw new DooverAuthError("Authentication is invalid; sign in again");
+        }
+        if (!this.needsRefresh()) {
+            return;
+        }
+        // Deduplicate concurrent refresh attempts.
+        if (!this.refreshInFlight) {
+            this.refreshInFlight = this.refresh().finally(() => {
+                this.refreshInFlight = null;
+            });
+        }
+        return this.refreshInFlight;
+    }
+    async handleUnauthorized() {
+        if (this.authInvalid) {
+            return false;
+        }
+        if (!this.refreshInFlight) {
+            this.refreshInFlight = this.refresh().finally(() => {
+                this.refreshInFlight = null;
+            });
+        }
+        try {
+            await this.refreshInFlight;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ------------------------------------------------------------------
+    // 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 = 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) {
+            this.markAuthInvalid();
+            throw new 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 DooverAuthError(`Token refresh request failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!response.ok) {
+            if (response.status >= 400 && response.status < 500) {
+                this.markAuthInvalid();
+            }
+            throw new DooverAuthError(`Token refresh failed with status ${response.status}`);
+        }
+        const body = (await response.json());
+        if (!body.access_token) {
+            this.markAuthInvalid();
+            throw new DooverAuthError("Token refresh response did not contain an access_token");
+        }
+        this.authInvalid = false;
+        this.token = body.access_token;
+        this.tokenExpires =
+            typeof body.expires_in === "number"
+                ? new Date(Date.now() + body.expires_in * 1000)
+                : 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;
+        this.profile.refreshToken = this.refreshToken;
+        if (this.configManager) {
+            try {
+                this.configManager.create(this.profile);
+                this.configManager.write();
+            }
+            catch (err) {
+                throw new DooverAuthError(`Failed to persist refreshed token: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    markAuthInvalid() {
+        this.authInvalid = true;
+        this.token = null;
+        this.tokenExpires = null;
+        this.refreshToken = null;
+        this.persistToProfile();
+    }
+    resolveExpiry(explicit, token) {
+        if (explicit instanceof Date) {
+            return explicit;
+        }
+        if (typeof explicit === "number") {
+            return new Date(explicit);
+        }
+        if (token) {
+            return decodeTokenExpiry(token);
+        }
+        return null;
+    }
+}

package/dist/esm/auth/errors.d.ts

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

package/dist/esm/auth/errors.js

@@ -0,0 +1,6 @@
+export class DooverAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DooverAuthError";
+    }
+}

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

@@ -0,0 +1,10 @@
+export { DooverAuth } from "./doover-auth.js";
+export { CookieAuth } from "./cookie-auth.js";
+export type { CookieAuthOptions } from "./cookie-auth.js";
+export { DooverTokenAuth } from "./doover-token-auth.js";
+export { AuthProfile } from "./auth-profile.js";
+export type { AuthProfileData } from "./auth-profile.js";
+export type { AuthProfileStore } from "./auth-store.js";
+export { DooverAuthError } from "./errors.js";
+export { buildAuth } from "./build-auth.js";
+export type { AuthConfig } from "./build-auth.js";

package/dist/esm/auth/index.js

@@ -0,0 +1,6 @@
+export { DooverAuth } from "./doover-auth.js";
+export { CookieAuth } from "./cookie-auth.js";
+export { DooverTokenAuth } from "./doover-token-auth.js";
+export { AuthProfile } from "./auth-profile.js";
+export { DooverAuthError } from "./errors.js";
+export { buildAuth } from "./build-auth.js";

package/dist/esm/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/esm/auth/jwt.js

@@ -0,0 +1,26 @@
+/**
+ * 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 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/esm/client/capabilities.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One capability per distinct endpoint-or-ability across the full `DataClient`
+ * surface. A backend advertises exactly what it can do; callers gate calls on
+ * these and an unsupported call throws `UnsupportedCapabilityError`.
+ *
+ * String-literal union (not a TS enum) so values serialise cleanly and can
+ * appear in error messages / debug UIs verbatim.
+ */
+export type Capability = "agents.list" | "agents.multiAgentMessages" | "agents.multiAgentAggregates" | "agents.tokenRead" | "agents.tokenManage" | "channels.list" | "channels.get" | "channels.create" | "channels.archive" | "channels.dataSeries" | "aggregates.get" | "aggregates.put" | "aggregates.patch" | "aggregates.attachment" | "messages.list" | "messages.listHistorical" | "messages.get" | "messages.post" | "messages.put" | "messages.delete" | "messages.attachment" | "messages.timeseries" | "messages.invocationLogs" | "gateway.subscribe" | "gateway.realtime" | "gateway.oneShot" | "rpc.send" | "alarms.read" | "alarms.write" | "connections.read" | "connections.write" | "notifications.read" | "notifications.write" | "permissions.read" | "permissions.write" | "processors.read" | "processors.write" | "turn.credentials" | "users.me";
+export declare const ALL_CAPABILITIES: readonly Capability[];

package/dist/esm/client/capabilities.js

@@ -0,0 +1,42 @@
+export const ALL_CAPABILITIES = [
+    "agents.list",
+    "agents.multiAgentMessages",
+    "agents.multiAgentAggregates",
+    "agents.tokenRead",
+    "agents.tokenManage",
+    "channels.list",
+    "channels.get",
+    "channels.create",
+    "channels.archive",
+    "channels.dataSeries",
+    "aggregates.get",
+    "aggregates.put",
+    "aggregates.patch",
+    "aggregates.attachment",
+    "messages.list",
+    "messages.listHistorical",
+    "messages.get",
+    "messages.post",
+    "messages.put",
+    "messages.delete",
+    "messages.attachment",
+    "messages.timeseries",
+    "messages.invocationLogs",
+    "gateway.subscribe",
+    "gateway.realtime",
+    "gateway.oneShot",
+    "rpc.send",
+    "alarms.read",
+    "alarms.write",
+    "connections.read",
+    "connections.write",
+    "notifications.read",
+    "notifications.write",
+    "permissions.read",
+    "permissions.write",
+    "processors.read",
+    "processors.write",
+    "turn.credentials",
+    "users.me",
+];
+void true;

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

@@ -0,0 +1,107 @@
+import type { NetworkStatusSource } from "./network-status.js";
+import type { AgentsApi } from "../apis/agents-api.js";
+import type { AggregatesApi } from "../apis/aggregates-api.js";
+import type { AlarmsApi } from "../apis/alarms-api.js";
+import type { ChannelsApi } from "../apis/channels-api.js";
+import type { ConnectionsApi } from "../apis/connections-api.js";
+import type { MessagesApi } from "../apis/messages-api.js";
+import type { NotificationsApi } from "../apis/notifications-api.js";
+import type { PermissionsApi } from "../apis/permissions-api.js";
+import type { ProcessorsApi } from "../apis/processors-api.js";
+import type { TurnApi } from "../apis/turn-api.js";
+import type { UsersApi } from "../apis/users-api.js";
+import type { GatewayClient } from "../gateway/gateway-client.js";
+import type { RpcDispatcher } from "../rpc/rpc-dispatcher.js";
+import type { Capability } from "./capabilities.js";
+/**
+ * Public structural shape of each concrete subclient — `Pick<Class, keyof Class>`
+ * yields just the public members as a plain object type (no nominal/private-member
+ * coupling), so a non-`DooverClient` implementation can satisfy it structurally.
+ */
+export type AgentsApiLike = Pick<AgentsApi, keyof AgentsApi>;
+export type AggregatesApiLike = Pick<AggregatesApi, keyof AggregatesApi>;
+export type AlarmsApiLike = Pick<AlarmsApi, keyof AlarmsApi>;
+export type ChannelsApiLike = Pick<ChannelsApi, keyof ChannelsApi>;
+export type ConnectionsApiLike = Pick<ConnectionsApi, keyof ConnectionsApi>;
+export type MessagesApiLike = Pick<MessagesApi, keyof MessagesApi>;
+export type NotificationsApiLike = Pick<NotificationsApi, keyof NotificationsApi>;
+export type PermissionsApiLike = Pick<PermissionsApi, keyof PermissionsApi>;
+export type ProcessorsApiLike = Pick<ProcessorsApi, keyof ProcessorsApi>;
+export type TurnApiLike = Pick<TurnApi, keyof TurnApi>;
+export type UsersApiLike = Pick<UsersApi, keyof UsersApi>;
+export type GatewayClientLike = Pick<GatewayClient, keyof GatewayClient>;
+export type RpcDispatcherLike = Pick<RpcDispatcher, keyof RpcDispatcher>;
+/** Which agents a `DataClient` can serve. */
+export type AgentScope = 
+/** Serves every agent (the cloud). Routing treats this as a wildcard. */
+{
+    mode: "all";
+}
+/** Serves exactly these agent ids (a local device agent → typically one id). */
+ | {
+    mode: "list";
+    agentIds: string[];
+};
+export type DataClientConnectionState = "connected" | "connecting" | "disconnected" | "degraded" | "error";
+export interface DataClientStatus {
+    /** This client's id ("cloud", "local:…", "multiplex", …). */
+    clientId: string;
+    /** True when the realtime link is up. Mirrors `isConnected()`. */
+    connected: boolean;
+    state: DataClientConnectionState;
+    /** Gateway session, when applicable. */
+    session?: {
+        id: string;
+    } | null;
+    /** Last lifecycle event seen ("init" | "open" | "ready" | "close" | "error" | …). */
+    lastEvent?: string;
+    /** Round-trip latency estimate in ms, if measured. */
+    latencyMs?: number | null;
+    /** Last error message, if the last event was an error. */
+    lastError?: string;
+    /** Best-effort agent scope at snapshot time ("unknown" before first resolution). */
+    agentScope: AgentScope | "unknown";
+    /** When this snapshot was taken (epoch ms). */
+    at: number;
+    /** Per-member statuses — present only for `MultiplexClient`. */
+    members?: Array<{
+        sourceId: string;
+        label?: string;
+        status: DataClientStatus;
+    }>;
+}
+/**
+ * The capability-aware data-access contract. `DooverClient`, `LocalAgentClient`
+ * and `MultiplexClient` all implement it. Deliberately excludes `DooverClient`'s
+ * `auth`/`rest`/`stats`/`viewer` (construction/internals/legacy). May be widened
+ * later; the invariant is that `DooverClient` always satisfies it.
+ */
+export interface DataClient {
+    /** Optional platform source; React hooks otherwise use browser network status. */
+    readonly networkStatus?: NetworkStatusSource;
+    readonly agents: AgentsApiLike;
+    readonly channels: ChannelsApiLike;
+    readonly messages: MessagesApiLike;
+    readonly aggregates: AggregatesApiLike;
+    readonly alarms: AlarmsApiLike;
+    readonly connections: ConnectionsApiLike;
+    readonly notifications: NotificationsApiLike;
+    readonly permissions: PermissionsApiLike;
+    readonly processors: ProcessorsApiLike;
+    readonly turn: TurnApiLike;
+    readonly users: UsersApiLike;
+    readonly gateway: GatewayClientLike;
+    readonly rpc: RpcDispatcherLike;
+    getCapabilities(): ReadonlySet<Capability>;
+    /** Convenience: `getCapabilities().has(cap)`. */
+    supports(cap: Capability): boolean;
+    /** True when the client's realtime link is up (multiplex: all members with `gateway.subscribe`). */
+    isConnected(): boolean;
+    getStatus(): DataClientStatus;
+    /** Subscribe to status changes; returns an idempotent unsubscribe fn. */
+    onStatusChange(listener: (status: DataClientStatus) => void): () => void;
+    /** Which agents this client can serve. Cloud → `{ mode: "all" }` with no round-trip. */
+    getAgentScope(): Promise<AgentScope>;
+    /** Synchronous best-effort snapshot; `"unknown"` until the first resolution. */
+    getKnownAgentScope(): AgentScope | "unknown";
+}

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

@@ -0,0 +1,48 @@
+import { type NetworkStatusSource } from "./network-status.js";
+import { OrganisationsApi } from "../apis/organisations-api.js";
+import type { DooverAuth } from "../auth/doover-auth.js";
+import { RestClient, type DooverClientConfig } from "../http/rest-client.js";
+import { DooverDataProvider } from "../viewer/doover-data-provider.js";
+import { type Capability } from "./capabilities.js";
+import type { AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, AgentScope, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client.js";
+import { DooverStatsCollector, type DooverStatsSnapshot } from "./stats.js";
+export declare class DooverClient implements DataClient {
+    readonly networkStatus: NetworkStatusSource;
+    readonly auth: DooverAuth;
+    readonly rest: RestClient;
+    readonly viewer: DooverDataProvider;
+    readonly users: UsersApiLike;
+    readonly channels: ChannelsApiLike;
+    readonly messages: MessagesApiLike;
+    readonly aggregates: AggregatesApiLike;
+    readonly alarms: AlarmsApiLike;
+    readonly connections: ConnectionsApiLike;
+    readonly notifications: NotificationsApiLike;
+    readonly organisations: OrganisationsApi;
+    readonly permissions: PermissionsApiLike;
+    readonly processors: ProcessorsApiLike;
+    readonly turn: TurnApiLike;
+    readonly agents: AgentsApiLike;
+    readonly gateway: GatewayClientLike;
+    readonly rpc: RpcDispatcherLike;
+    readonly stats: DooverStatsCollector;
+    private readonly identity;
+    private readonly statusTracker;
+    /** Underlying concrete gateway (the public `gateway` is the same object,
+     *  typed as the structural `GatewayClientLike`). */
+    private readonly gatewayImpl;
+    /** Underlying concrete RPC dispatcher (the public `rpc` is the same object,
+     *  typed as the structural `RpcDispatcherLike`). */
+    private readonly rpcImpl;
+    constructor(config: DooverClientConfig);
+    enableStats(): void;
+    disableStats(): void;
+    getStats(): DooverStatsSnapshot;
+    getCapabilities(): ReadonlySet<Capability>;
+    supports(cap: Capability): boolean;
+    getAgentScope(): Promise<AgentScope>;
+    getKnownAgentScope(): AgentScope | "unknown";
+    isConnected(): boolean;
+    getStatus(): DataClientStatus;
+    onStatusChange(listener: (status: DataClientStatus) => void): () => void;
+}

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

@@ -0,0 +1,96 @@
+import { browserNetworkStatus } from "./network-status.js";
+import { AgentsApi } from "../apis/agents-api.js";
+import { AggregatesApi } from "../apis/aggregates-api.js";
+import { AlarmsApi } from "../apis/alarms-api.js";
+import { ChannelsApi } from "../apis/channels-api.js";
+import { ConnectionsApi } from "../apis/connections-api.js";
+import { MessagesApi } from "../apis/messages-api.js";
+import { NotificationsApi } from "../apis/notifications-api.js";
+import { OrganisationsApi } from "../apis/organisations-api.js";
+import { PermissionsApi } from "../apis/permissions-api.js";
+import { ProcessorsApi } from "../apis/processors-api.js";
+import { TurnApi } from "../apis/turn-api.js";
+import { UsersApi } from "../apis/users-api.js";
+import { buildAuth } from "../auth/build-auth.js";
+import { GatewayClient } from "../gateway/gateway-client.js";
+import { RestClient } from "../http/rest-client.js";
+import { RpcDispatcher } from "../rpc/rpc-dispatcher.js";
+import { DooverDataProvider } from "../viewer/doover-data-provider.js";
+import { ALL_CAPABILITIES } from "./capabilities.js";
+import { ProvenanceStamper, wrapSubclient } from "./provenance.js";
+import { ClientStatusTracker } from "./status-tracker.js";
+import { DooverStatsCollector } from "./stats.js";
+const ALL_CAPS_SET = new Set(ALL_CAPABILITIES);
+export class DooverClient {
+    constructor(config) {
+        this.networkStatus = config.networkStatus ?? browserNetworkStatus;
+        this.auth = buildAuth({
+            auth: config.auth,
+            profile: config.profile,
+            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.identity = {
+            id: config.sourceId ?? "cloud",
+            kind: "cloud",
+            ...(config.sourceLabel ? { label: config.sourceLabel } : {}),
+            meta: {
+                dataRestUrl: config.dataRestUrl,
+                controlApiUrl: config.controlApiUrl,
+                ...(config.organisationId ? { organisationId: config.organisationId } : {}),
+            },
+        };
+        const stamper = new ProvenanceStamper(this.identity);
+        this.rest = new RestClient(config, this.auth);
+        this.gatewayImpl = new GatewayClient(config, this.auth);
+        this.gatewayImpl.setProvenanceHook((value, ctx) => stamper.stampGatewayEvent(value, ctx));
+        this.gateway = this.gatewayImpl;
+        this.viewer = new DooverDataProvider({
+            rest: this.rest,
+            gateway: this.gatewayImpl,
+            controlApiUrl: config.controlApiUrl,
+        });
+        this.users = wrapSubclient(new UsersApi(this.rest, config.controlApiUrl), "users", stamper);
+        this.channels = wrapSubclient(new ChannelsApi(this.rest), "channels", stamper);
+        this.messages = wrapSubclient(new MessagesApi(this.rest), "messages", stamper);
+        this.aggregates = wrapSubclient(new AggregatesApi(this.rest), "aggregates", stamper);
+        this.alarms = wrapSubclient(new AlarmsApi(this.rest), "alarms", stamper);
+        this.connections = wrapSubclient(new ConnectionsApi(this.rest), "connections", stamper);
+        this.notifications = wrapSubclient(new NotificationsApi(this.rest), "notifications", stamper);
+        this.organisations = wrapSubclient(new OrganisationsApi(this.rest, config.controlApiUrl), "organisations", stamper);
+        this.permissions = wrapSubclient(new PermissionsApi(this.rest), "permissions", stamper);
+        this.processors = wrapSubclient(new ProcessorsApi(this.rest), "processors", stamper);
+        this.turn = wrapSubclient(new TurnApi(this.rest), "turn", stamper);
+        this.agents = wrapSubclient(new AgentsApi(this.rest, config.controlApiUrl), "agents", stamper);
+        // RpcDispatcher needs the concrete MessagesApi (it calls postMessage internally);
+        // give it an *unwrapped* one so stamping happens once at the public boundary.
+        this.rpcImpl = new RpcDispatcher(this.gatewayImpl, new MessagesApi(this.rest));
+        this.rpc = this.rpcImpl;
+        this.stats = new DooverStatsCollector();
+        this.rest.setStats(this.stats);
+        this.gatewayImpl.setStats(this.stats);
+        this.rpcImpl.setStats(this.stats);
+        this.statusTracker = new ClientStatusTracker(this.identity.id, this.gateway, () => this.getKnownAgentScope());
+    }
+    enableStats() { this.stats.setEnabled(true); }
+    disableStats() { this.stats.setEnabled(false); }
+    getStats() { return this.stats.snapshot(); }
+    // --- DataClient: capabilities ---
+    getCapabilities() { return ALL_CAPS_SET; }
+    supports(cap) { return ALL_CAPS_SET.has(cap); }
+    // --- DataClient: agent scope (cloud serves every agent) ---
+    getAgentScope() { return Promise.resolve({ mode: "all" }); }
+    getKnownAgentScope() { return { mode: "all" }; }
+    // --- DataClient: status ---
+    isConnected() { return this.gateway.isConnected(); }
+    getStatus() { return this.statusTracker.getStatus(); }
+    onStatusChange(listener) {
+        return this.statusTracker.onChange(listener);
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { Capability } from "./capabilities.js";
+import { DooverApiError } from "../http/errors.js";
+/**
+ * Thrown when a `DataClient` method is called whose backing capability the
+ * client does not advertise. Extends `DooverApiError` so existing
+ * `instanceof DooverApiError` error handling catches it; the HTTP-ish fields
+ * are placeholders since no request was made.
+ */
+export declare class UnsupportedCapabilityError extends DooverApiError {
+    readonly capability: Capability;
+    readonly clientId?: string;
+    constructor(capability: Capability, clientId?: string);
+}
+/**
+ * Thrown by `MultiplexClient` when a write cannot be routed to a single
+ * member — more than one enabled member owns the targeted agent and has the
+ * write capability, and the call was not `sources`-scoped to one of them.
+ */
+export declare class AmbiguousWriteError extends DooverApiError {
+    readonly capability: Capability;
+    readonly candidateSourceIds: string[];
+    constructor(capability: Capability, candidateSourceIds: string[]);
+}
+/**
+ * Thrown by offline-aware clients when a network-only operation is attempted
+ * while offline, or when an offline read has no usable cached value.
+ */
+export declare class DooverOfflineError extends DooverApiError {
+    readonly operation: string;
+    readonly cacheKey?: string;
+    constructor(operation: string, message?: string, cacheKey?: string);
+}