doover-js 0.5.3 → 0.6.0

package/dist/apis/processors-api.d.ts

@@ -4,18 +4,53 @@ export declare class ProcessorsApi {
     private readonly rest;
     constructor(rest: RestClient);
     createProcessorSchedule(agentId: string, scheduleId: string, body: PutScheduleRequest): Promise<unknown>;
+    createProcessorSchedule(identifier: {
+        agentId: string;
+    }, scheduleId: string, body: PutScheduleRequest): Promise<unknown>;
+    private _createProcessorSchedule;
     deleteProcessorSchedule(agentId: string, scheduleId: string): Promise<unknown>;
+    deleteProcessorSchedule(identifier: {
+        agentId: string;
+    }, scheduleId: string): Promise<unknown>;
+    private _deleteProcessorSchedule;
     regenerateScheduleToken(agentId: string, scheduleId: string): Promise<unknown>;
+    regenerateScheduleToken(identifier: {
+        agentId: string;
+    }, scheduleId: string): Promise<unknown>;
+    private _regenerateScheduleToken;
     getScheduleInfo(scheduleId: string): Promise<ScheduleInfo>;
     getScheduleInfoAlias(scheduleId: string): Promise<ScheduleInfo>;
     createProcessorSubscription(agentId: string, subscriptionId: string, body: PutSubscriptionRequest): Promise<unknown>;
+    createProcessorSubscription(identifier: {
+        agentId: string;
+    }, subscriptionId: string, body: PutSubscriptionRequest): Promise<unknown>;
+    private _createProcessorSubscription;
     deleteProcessorSubscription(agentId: string, subscriptionId: string): Promise<unknown>;
+    deleteProcessorSubscription(identifier: {
+        agentId: string;
+    }, subscriptionId: string): Promise<unknown>;
+    private _deleteProcessorSubscription;
     getProcessorSubscriptionInfo(subscriptionName: string): Promise<SubscriptionInfo>;
     getProcessorSubscriptionInfoAlias(subscriptionArn: string): Promise<SubscriptionInfo>;
     createIngestionEndpoint(agentId: string, ingestionId: string, body: CreateIngestionRequest): Promise<unknown>;
+    createIngestionEndpoint(identifier: {
+        agentId: string;
+    }, ingestionId: string, body: CreateIngestionRequest): Promise<unknown>;
+    private _createIngestionEndpoint;
     deleteIngestionEndpoint(agentId: string, ingestionId: string): Promise<unknown>;
+    deleteIngestionEndpoint(identifier: {
+        agentId: string;
+    }, ingestionId: string): Promise<unknown>;
+    private _deleteIngestionEndpoint;
     invokeIngestionEndpoint(agentId: string, ingestionId: string, body: unknown, params?: {
         wait?: boolean;
         json_response?: boolean;
     }): Promise<unknown>;
+    invokeIngestionEndpoint(identifier: {
+        agentId: string;
+    }, ingestionId: string, body: unknown, params?: {
+        wait?: boolean;
+        json_response?: boolean;
+    }): Promise<unknown>;
+    private _invokeIngestionEndpoint;
 }

package/dist/apis/processors-api.js

@@ -5,13 +5,34 @@ class ProcessorsApi {
     constructor(rest) {
         this.rest = rest;
     }
-    createProcessorSchedule(agentId, scheduleId, body) {
+    createProcessorSchedule(...args) {
+        if (typeof args[0] === "string") {
+            return this._createProcessorSchedule(args[0], args[1], args[2]);
+        }
+        const id = args[0];
+        return this._createProcessorSchedule(id.agentId, args[1], args[2]);
+    }
+    _createProcessorSchedule(agentId, scheduleId, body) {
         return this.rest.put(`/agents/${agentId}/processors/schedules/${scheduleId}`, body);
     }
-    deleteProcessorSchedule(agentId, scheduleId) {
+    deleteProcessorSchedule(...args) {
+        if (typeof args[0] === "string") {
+            return this._deleteProcessorSchedule(args[0], args[1]);
+        }
+        const id = args[0];
+        return this._deleteProcessorSchedule(id.agentId, args[1]);
+    }
+    _deleteProcessorSchedule(agentId, scheduleId) {
         return this.rest.delete(`/agents/${agentId}/processors/schedules/${scheduleId}`);
     }
-    regenerateScheduleToken(agentId, scheduleId) {
+    regenerateScheduleToken(...args) {
+        if (typeof args[0] === "string") {
+            return this._regenerateScheduleToken(args[0], args[1]);
+        }
+        const id = args[0];
+        return this._regenerateScheduleToken(id.agentId, args[1]);
+    }
+    _regenerateScheduleToken(agentId, scheduleId) {
         return this.rest.post(`/agents/${agentId}/processors/schedules/${scheduleId}/token`, {});
     }
     getScheduleInfo(scheduleId) {
@@ -20,10 +41,24 @@ class ProcessorsApi {
     getScheduleInfoAlias(scheduleId) {
         return this.rest.get(`/processors/schedules/${scheduleId}/info`);
     }
-    createProcessorSubscription(agentId, subscriptionId, body) {
+    createProcessorSubscription(...args) {
+        if (typeof args[0] === "string") {
+            return this._createProcessorSubscription(args[0], args[1], args[2]);
+        }
+        const id = args[0];
+        return this._createProcessorSubscription(id.agentId, args[1], args[2]);
+    }
+    _createProcessorSubscription(agentId, subscriptionId, body) {
         return this.rest.put(`/agents/${agentId}/processors/subscriptions/${subscriptionId}`, body);
     }
-    deleteProcessorSubscription(agentId, subscriptionId) {
+    deleteProcessorSubscription(...args) {
+        if (typeof args[0] === "string") {
+            return this._deleteProcessorSubscription(args[0], args[1]);
+        }
+        const id = args[0];
+        return this._deleteProcessorSubscription(id.agentId, args[1]);
+    }
+    _deleteProcessorSubscription(agentId, subscriptionId) {
         return this.rest.delete(`/agents/${agentId}/processors/subscriptions/${subscriptionId}`);
     }
     getProcessorSubscriptionInfo(subscriptionName) {
@@ -32,13 +67,34 @@ class ProcessorsApi {
     getProcessorSubscriptionInfoAlias(subscriptionArn) {
         return this.rest.get(`/processors/subscriptions/${subscriptionArn}/info`);
     }
-    createIngestionEndpoint(agentId, ingestionId, body) {
+    createIngestionEndpoint(...args) {
+        if (typeof args[0] === "string") {
+            return this._createIngestionEndpoint(args[0], args[1], args[2]);
+        }
+        const id = args[0];
+        return this._createIngestionEndpoint(id.agentId, args[1], args[2]);
+    }
+    _createIngestionEndpoint(agentId, ingestionId, body) {
         return this.rest.put(`/agents/${agentId}/processors/ingestions/${ingestionId}`, body);
     }
-    deleteIngestionEndpoint(agentId, ingestionId) {
+    deleteIngestionEndpoint(...args) {
+        if (typeof args[0] === "string") {
+            return this._deleteIngestionEndpoint(args[0], args[1]);
+        }
+        const id = args[0];
+        return this._deleteIngestionEndpoint(id.agentId, args[1]);
+    }
+    _deleteIngestionEndpoint(agentId, ingestionId) {
         return this.rest.delete(`/agents/${agentId}/processors/ingestions/${ingestionId}`);
     }
-    invokeIngestionEndpoint(agentId, ingestionId, body, params) {
+    invokeIngestionEndpoint(...args) {
+        if (typeof args[0] === "string") {
+            return this._invokeIngestionEndpoint(args[0], args[1], args[2], args[3]);
+        }
+        const id = args[0];
+        return this._invokeIngestionEndpoint(id.agentId, args[1], args[2], args[3]);
+    }
+    _invokeIngestionEndpoint(agentId, ingestionId, body, params) {
         return this.rest.post(`/agents/${agentId}/processors/ingestions/${ingestionId}/invoke`, body, params);
     }
 }

package/dist/apis/users-api.d.ts

@@ -0,0 +1,8 @@
+import type { RestClient } from "../http/rest-client";
+import type { User } from "../types/viewer";
+export declare class UsersApi {
+    private readonly rest;
+    private readonly controlApiUrl?;
+    constructor(rest: RestClient, controlApiUrl?: string | undefined);
+    getMe(): Promise<User>;
+}

package/dist/apis/users-api.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsersApi = void 0;
+class UsersApi {
+    constructor(rest, controlApiUrl) {
+        this.rest = rest;
+        this.controlApiUrl = controlApiUrl;
+    }
+    getMe() {
+        return this.rest.get("/users/me", undefined, this.controlApiUrl);
+    }
+}
+exports.UsersApi = UsersApi;

package/dist/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" | "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/client/capabilities.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_CAPABILITIES = void 0;
+exports.ALL_CAPABILITIES = [
+    "agents.list",
+    "agents.multiAgentMessages",
+    "agents.multiAgentAggregates",
+    "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/client/data-client.d.ts

@@ -0,0 +1,104 @@
+import type { AgentsApi } from "../apis/agents-api";
+import type { AggregatesApi } from "../apis/aggregates-api";
+import type { AlarmsApi } from "../apis/alarms-api";
+import type { ChannelsApi } from "../apis/channels-api";
+import type { ConnectionsApi } from "../apis/connections-api";
+import type { MessagesApi } from "../apis/messages-api";
+import type { NotificationsApi } from "../apis/notifications-api";
+import type { PermissionsApi } from "../apis/permissions-api";
+import type { ProcessorsApi } from "../apis/processors-api";
+import type { TurnApi } from "../apis/turn-api";
+import type { UsersApi } from "../apis/users-api";
+import type { GatewayClient } from "../gateway/gateway-client";
+import type { RpcDispatcher } from "../rpc/rpc-dispatcher";
+import type { Capability } from "./capabilities";
+/**
+ * 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 {
+    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/client/data-client.js

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

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

@@ -1,44 +1,44 @@
-import { AgentsApi } from "../apis/agents-api";
-import { AggregatesApi } from "../apis/aggregates-api";
-import { AlarmsApi } from "../apis/alarms-api";
-import { ChannelsApi } from "../apis/channels-api";
-import { ConnectionsApi } from "../apis/connections-api";
-import { MessagesApi } from "../apis/messages-api";
-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 { type Capability } from "./capabilities";
+import type { AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, AgentScope, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client";
 import { DooverStatsCollector, type DooverStatsSnapshot } from "./stats";
-export declare class DooverClient {
+export declare class DooverClient implements DataClient {
     readonly auth: DooverAuth;
     readonly rest: RestClient;
     readonly viewer: DooverDataProvider;
-    readonly channels: ChannelsApi;
-    readonly messages: MessagesApi;
-    readonly aggregates: AggregatesApi;
-    readonly alarms: AlarmsApi;
-    readonly connections: ConnectionsApi;
-    readonly notifications: NotificationsApi;
-    readonly permissions: PermissionsApi;
-    readonly processors: ProcessorsApi;
-    readonly turn: TurnApi;
-    readonly agents: AgentsApi;
-    readonly gateway: GatewayClient;
-    /** Opt-in instrumentation. Disabled by default — see {@link enableStats}. */
+    readonly users: UsersApiLike;
+    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 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);
-    /** 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;
+    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/client/doover-client.js

@@ -11,10 +11,17 @@ 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 users_api_1 = require("../apis/users-api");
 const build_auth_1 = require("../auth/build-auth");
+const gateway_client_1 = require("../gateway/gateway-client");
 const rest_client_1 = require("../http/rest-client");
+const rpc_dispatcher_1 = require("../rpc/rpc-dispatcher");
 const doover_data_provider_1 = require("../viewer/doover-data-provider");
+const capabilities_1 = require("./capabilities");
+const provenance_1 = require("./provenance");
+const status_tracker_1 = require("./status-tracker");
 const stats_1 = require("./stats");
+const ALL_CAPS_SET = new Set(capabilities_1.ALL_CAPABILITIES);
 class DooverClient {
     constructor(config) {
         this.auth = (0, build_auth_1.buildAuth)({
@@ -29,47 +36,61 @@ class DooverClient {
             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 provenance_1.ProvenanceStamper(this.identity);
         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);
-        this.alarms = new alarms_api_1.AlarmsApi(this.rest);
-        this.connections = new connections_api_1.ConnectionsApi(this.rest);
-        this.notifications = new notifications_api_1.NotificationsApi(this.rest);
-        this.permissions = new permissions_api_1.PermissionsApi(this.rest);
-        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);
-        // 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.gatewayImpl = new gateway_client_1.GatewayClient(config, this.auth);
+        this.gatewayImpl.setProvenanceHook((value, ctx) => stamper.stampGatewayEvent(value, ctx));
+        this.gateway = this.gatewayImpl;
+        this.viewer = new doover_data_provider_1.DooverDataProvider({
+            rest: this.rest,
+            gateway: this.gatewayImpl,
+            controlApiUrl: config.controlApiUrl,
+        });
+        this.users = (0, provenance_1.wrapSubclient)(new users_api_1.UsersApi(this.rest, config.controlApiUrl), "users", stamper);
+        this.channels = (0, provenance_1.wrapSubclient)(new channels_api_1.ChannelsApi(this.rest), "channels", stamper);
+        this.messages = (0, provenance_1.wrapSubclient)(new messages_api_1.MessagesApi(this.rest), "messages", stamper);
+        this.aggregates = (0, provenance_1.wrapSubclient)(new aggregates_api_1.AggregatesApi(this.rest), "aggregates", stamper);
+        this.alarms = (0, provenance_1.wrapSubclient)(new alarms_api_1.AlarmsApi(this.rest), "alarms", stamper);
+        this.connections = (0, provenance_1.wrapSubclient)(new connections_api_1.ConnectionsApi(this.rest), "connections", stamper);
+        this.notifications = (0, provenance_1.wrapSubclient)(new notifications_api_1.NotificationsApi(this.rest), "notifications", stamper);
+        this.permissions = (0, provenance_1.wrapSubclient)(new permissions_api_1.PermissionsApi(this.rest), "permissions", stamper);
+        this.processors = (0, provenance_1.wrapSubclient)(new processors_api_1.ProcessorsApi(this.rest), "processors", stamper);
+        this.turn = (0, provenance_1.wrapSubclient)(new turn_api_1.TurnApi(this.rest), "turn", stamper);
+        this.agents = (0, provenance_1.wrapSubclient)(new agents_api_1.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 rpc_dispatcher_1.RpcDispatcher(this.gatewayImpl, new messages_api_1.MessagesApi(this.rest));
+        this.rpc = this.rpcImpl;
         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);
+        this.gatewayImpl.setStats(this.stats);
+        this.rpcImpl.setStats(this.stats);
+        this.statusTracker = new status_tracker_1.ClientStatusTracker(this.identity.id, this.gateway, () => this.getKnownAgentScope());
     }
-    /**
-     * 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();
+    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);
     }
 }
 exports.DooverClient = DooverClient;

package/dist/client/errors.d.ts

@@ -0,0 +1,23 @@
+import type { Capability } from "./capabilities";
+import { DooverApiError } from "../http/errors";
+/**
+ * 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[]);
+}

package/dist/client/errors.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = void 0;
+const errors_1 = require("../http/errors");
+/**
+ * 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.
+ */
+class UnsupportedCapabilityError extends errors_1.DooverApiError {
+    constructor(capability, clientId) {
+        super({
+            status: 0,
+            body: { capability, clientId },
+            url: "",
+            method: "",
+            message: `Capability "${capability}" is not supported` +
+                (clientId ? ` by client "${clientId}"` : "") + ".",
+        });
+        this.name = "UnsupportedCapabilityError";
+        this.capability = capability;
+        this.clientId = clientId;
+        Object.setPrototypeOf(this, UnsupportedCapabilityError.prototype);
+    }
+}
+exports.UnsupportedCapabilityError = UnsupportedCapabilityError;
+/**
+ * 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.
+ */
+class AmbiguousWriteError extends errors_1.DooverApiError {
+    constructor(capability, candidateSourceIds) {
+        super({
+            status: 0,
+            body: { capability, candidateSourceIds },
+            url: "",
+            method: "",
+            message: `Ambiguous write for "${capability}": ${candidateSourceIds.length} ` +
+                `members are eligible (${candidateSourceIds.join(", ")}). ` +
+                `Scope the call with { sources: [<one-id>] }.`,
+        });
+        this.name = "AmbiguousWriteError";
+        this.capability = capability;
+        this.candidateSourceIds = candidateSourceIds;
+        Object.setPrototypeOf(this, AmbiguousWriteError.prototype);
+    }
+}
+exports.AmbiguousWriteError = AmbiguousWriteError;