doover-js 0.5.0-alpha.0 → 0.5.0-alpha.1

package/README.md

@@ -122,12 +122,127 @@ const client = new DooverClient({
 
 Reconnections automatically use the latest (potentially refreshed) token.
 
+## Multi-source data (`DataClient`)
+
+### The `DataClient` contract
+
+`DooverClient` now implements the `DataClient` interface — the shared contract for every client type in this library. Any hook or provider that previously accepted a `DooverClient` now accepts any `DataClient`.
+
+```ts
+import type { DataClient } from "doover-js";
+
+function useMyData(client: DataClient) {
+  return client.channels.listChannels("my-agent");
+}
+```
+
+### Capability model
+
+Each client advertises what it can do via `getCapabilities()` and the `supports(cap)` helper. Calling an unsupported method throws `UnsupportedCapabilityError`.
+
+```ts
+import { UnsupportedCapabilityError } from "doover-js";
+
+if (client.supports("aggregates.write")) {
+  await client.aggregates.putAggregate(channelId, data);
+} else {
+  console.warn("Client does not support aggregate writes");
+}
+```
+
+### `LocalAgentClient` — LAN / direct access
+
+Connect directly to a local Doover agent without cloud auth:
+
+```ts
+import { LocalAgentClient } from "doover-js";
+
+const local = new LocalAgentClient({
+  baseUrl: "http://192.168.0.7:49100",
+  sourceId: "local:192.168.0.7:49100", // stable id for cache keys
+});
+const channels = await local.channels.listChannels("my-agent");
+```
+
+`LocalAgentClient` exposes a narrowed capability set — reads for agents, channels, messages, aggregates, and the gateway are supported; cloud-only operations (alarms, notifications, permissions, etc.) are not.
+
+### `MultiplexClient` — fan-out reads, routed writes
+
+`MultiplexClient` manages a registry of named sources (cloud or local) and fans reads out across all active sources, merging the results. Writes are routed to the single source that owns the target agent.
+
+```ts
+import { MultiplexClient, LocalAgentClient, getDooverClient } from "doover-js";
+
+const mux = new MultiplexClient({
+  factory: (d) =>
+    d.kind === "cloud"
+      ? getDooverClient({ /* cloud config */ })
+      : new LocalAgentClient({ baseUrl: `http://${(d.params as any).host}:${(d.params as any).port}`, sourceId: d.id }),
+  register: [{ id: "cloud", kind: "cloud" }],
+  enable: ["cloud"],
+});
+mux.setActiveSources(["cloud", { id: "local:192.168.0.7:49100", kind: "local", params: { host: "192.168.0.7", port: 49100 } }]);
+const channels = await mux.channels.listChannels("dev7"); // merged cloud + local
+mux.on("conflict", (c) => console.warn("source disagreement", c));
+```
+
+Use `getLastConflicts()` to inspect the most recent per-key disagreements between sources after a read.
+
+### `__source` provenance
+
+Every datum returned by any `DataClient` carries a `__source` field (type `SourceProvenance`) recording which client returned it, when, and via which transport.
+
+```ts
+const ch = await client.channels.getChannel("my-channel");
+console.log(ch.__source?.client.id); // e.g. "cloud" or "local:192.168.0.7:49100"
+```
+
+### React: hooks, `DooverProvider`, and `useClientStatus`
+
+`DooverProvider` accepts any `DataClient`:
+
+```tsx
+import { DooverProvider } from "doover-js/react";
+import { MultiplexClient } from "doover-js";
+
+<DooverProvider client={mux}>
+  <App />
+</DooverProvider>
+```
+
+All data hooks gained an optional `sources?: string[]` prop that restricts fan-out to specific sources:
+
+```tsx
+const { data } = useChannelAggregate(channelId, { sources: ["local:192.168.0.7:49100"] });
+```
+
+The new `useClientStatus()` hook surfaces the connection status of every registered source:
+
+```tsx
+import { useClientStatus } from "doover-js/react";
+
+const statuses = useClientStatus();
+// statuses is DataClientStatus[] — one entry per registered source
+```
+
+`useConnectionState` is soft-deprecated in favour of `useClientStatus`. It still works and remains exported, but new code should prefer `useClientStatus`.
+
 ## 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.
 
+## 0.5.0-alpha.1
+
+- **`DataClient` contract + capability model** — `DooverClient` now implements the `DataClient` interface. Every client type advertises its capability set; unsupported calls throw `UnsupportedCapabilityError`. `AmbiguousWriteError` is raised when a `MultiplexClient` write has more than one candidate source. (Additive, no breaking changes.)
+- **`__source` provenance** — every datum carries a `__source: SourceProvenance` field recording which client returned it, when, and via which transport.
+- **`LocalAgentClient`** — new client for direct LAN connections to a local Doover agent (no cloud auth required).
+- **`MultiplexClient`** — new client that manages a registry of named sources, fans reads out across all active sources, merges results, and routes writes to the owning source.
+- **React `sources` option** — all data hooks accept `sources?: string[]` to restrict fan-out to specific sources; query keys are source-dimensioned.
+- **`useClientStatus()`** — new react hook that surfaces `DataClientStatus` for each registered source.
+- **`useConnectionState` soft-deprecated** — still exported and working; prefer `useClientStatus` for new code.
+
 ## Migrating to 0.6.0
 
 `DooverDataProvider` (`client.viewer`) is deprecated in 0.5.0 and removed in 0.6.0. The replacements are subclients on `DooverClient`:

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,40 +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 { UsersApi } from "../apis/users-api";
 import type { DooverAuth } from "../auth/doover-auth";
-import { GatewayClient } from "../gateway/gateway-client";
 import { RestClient, type DooverClientConfig } from "../http/rest-client";
-import { RpcDispatcher } from "../rpc/rpc-dispatcher";
 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 users: UsersApi;
-    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;
-    readonly rpc: RpcDispatcher;
+    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);
     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/client/doover-client.js

@@ -17,7 +17,11 @@ 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)({
@@ -32,32 +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.gateway = new gateway_client_1.GatewayClient(config, this.auth);
+        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.gateway,
+            gateway: this.gatewayImpl,
             controlApiUrl: config.controlApiUrl,
         });
-        this.users = new users_api_1.UsersApi(this.rest, config.controlApiUrl);
-        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, config.controlApiUrl);
-        this.rpc = new rpc_dispatcher_1.RpcDispatcher(this.gateway, this.messages);
+        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.gateway.setStats(this.stats);
-        this.rpc.setStats(this.stats);
+        this.gatewayImpl.setStats(this.stats);
+        this.rpcImpl.setStats(this.stats);
+        this.statusTracker = new status_tracker_1.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);
+    }
 }
 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;

package/dist/client/local-agent-client.d.ts

@@ -0,0 +1,65 @@
+import { type DooverClientConfig } from "../http/rest-client";
+import type { Capability } from "./capabilities";
+import type { AgentScope, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client";
+export interface LocalAgentClientConfig {
+    /** Base URL of the local agent's REST API, e.g. "http://192.168.0.7:49100". */
+    baseUrl: string;
+    /** Base URL of the local agent's WebSocket gateway. Defaults to `baseUrl`
+     *  with http(s)→ws(s). */
+    wssUrl?: string;
+    fetchImpl?: typeof fetch;
+    webSocketImpl?: typeof WebSocket;
+    webSocketFactory?: DooverClientConfig["webSocketFactory"];
+    disableBrowserLifecycleHooks?: boolean;
+    /** Stable source id. Defaults to `local:<host>:<port>` derived from baseUrl. */
+    sourceId?: string;
+    sourceLabel?: string;
+    /** Reserved for a future LAN auth blob — ignored in v1. */
+    auth?: unknown;
+}
+export declare class LocalAgentClient implements 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;
+    private readonly identity;
+    private readonly capSet;
+    private readonly rest;
+    private readonly gatewayImpl;
+    private readonly statusTracker;
+    /** Resolved device-agent id list; null until first resolution. */
+    private resolvedScope;
+    private scopeResolving;
+    constructor(config: LocalAgentClientConfig);
+    getCapabilities(): ReadonlySet<Capability>;
+    supports(cap: Capability): boolean;
+    getAgentScope(): Promise<AgentScope>;
+    getKnownAgentScope(): AgentScope | "unknown";
+    isConnected(): boolean;
+    getStatus(): DataClientStatus;
+    onStatusChange(listener: (status: DataClientStatus) => void): () => void;
+    /**
+     * Wraps a real (provenance-wrapped) subclient so only `allowed` method names
+     * pass through; any other method call throws `UnsupportedCapabilityError`.
+     *
+     * Typing `real` as `WrappedSubclient<T>` and `allowed` as
+     * `ReadonlyArray<keyof WrappedSubclient<T> & string>` ensures the compiler
+     * catches typos in the allowed-method list at the call site.
+     */
+    private gatedSubclient;
+    /**
+     * Builds a Proxy that throws `UnsupportedCapabilityError` (mapped via
+     * METHOD_TO_CAPABILITY) for every method call. Used for subclients with no
+     * advertised methods.
+     */
+    private unsupportedSubclient;
+}