doover-js 0.11.0 → 0.13.0

package/dist/esm/client/errors.js

@@ -0,0 +1,64 @@
+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 class UnsupportedCapabilityError extends 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);
+    }
+}
+/**
+ * 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 class AmbiguousWriteError extends 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);
+    }
+}
+/**
+ * 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 class DooverOfflineError extends DooverApiError {
+    constructor(operation, message, cacheKey) {
+        super({
+            status: 0,
+            body: { operation, cacheKey },
+            url: "",
+            method: "",
+            message: message ?? `Operation "${operation}" is unavailable while offline.`,
+        });
+        this.name = "DooverOfflineError";
+        this.operation = operation;
+        this.cacheKey = cacheKey;
+        Object.setPrototypeOf(this, DooverOfflineError.prototype);
+    }
+}

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

@@ -0,0 +1,6 @@
+export { DooverClient } from "./doover-client.js";
+export { getDooverClient, peekDooverClient, resetDooverClient } from "./singleton.js";
+export type { DooverClientConfig } from "../http/rest-client.js";
+export type * from "./data-client.js";
+export { browserNetworkStatus, createNetworkStatusStore } from "./network-status.js";
+export type { NetworkStatusSource, NetworkStatusSnapshot } from "./network-status.js";

package/dist/esm/client/index.js

@@ -0,0 +1,3 @@
+export { DooverClient } from "./doover-client.js";
+export { getDooverClient, peekDooverClient, resetDooverClient } from "./singleton.js";
+export { browserNetworkStatus, createNetworkStatusStore } from "./network-status.js";

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

@@ -0,0 +1,65 @@
+import { type DooverClientConfig } from "../http/rest-client.js";
+import type { Capability } from "./capabilities.js";
+import type { AgentScope, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client.js";
+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;
+}

package/dist/esm/client/local-agent-client.js

@@ -0,0 +1,225 @@
+import { AgentsApi } from "../apis/agents-api.js";
+import { AggregatesApi } from "../apis/aggregates-api.js";
+import { ChannelsApi } from "../apis/channels-api.js";
+import { MessagesApi } from "../apis/messages-api.js";
+import { GatewayClient } from "../gateway/gateway-client.js";
+import { RestClient } from "../http/rest-client.js";
+import { UnsupportedCapabilityError } from "./errors.js";
+import { ProvenanceStamper, wrapSubclient } from "./provenance.js";
+import { ClientStatusTracker } from "./status-tracker.js";
+const LOCAL_CAPABILITIES = [
+    "agents.list",
+    "channels.list",
+    "channels.get",
+    "aggregates.get",
+    "aggregates.put",
+    "aggregates.patch",
+    "messages.list",
+    "messages.post",
+    "messages.put",
+    "gateway.subscribe",
+    "gateway.realtime",
+    "gateway.oneShot",
+];
+function deriveSourceId(baseUrl) {
+    try {
+        const u = new URL(baseUrl);
+        return `local:${u.hostname}${u.port ? `:${u.port}` : ""}`;
+    }
+    catch {
+        return `local:${baseUrl}`;
+    }
+}
+function httpToWs(url) {
+    return url.replace(/^http/i, "ws");
+}
+export class LocalAgentClient {
+    constructor(config) {
+        /** Resolved device-agent id list; null until first resolution. */
+        this.resolvedScope = null;
+        this.scopeResolving = null;
+        const sourceId = config.sourceId ?? deriveSourceId(config.baseUrl);
+        this.identity = {
+            id: sourceId,
+            kind: "local",
+            ...(config.sourceLabel ? { label: config.sourceLabel } : {}),
+            meta: { baseUrl: config.baseUrl },
+        };
+        this.capSet = new Set(LOCAL_CAPABILITIES);
+        const stamper = new ProvenanceStamper(this.identity);
+        // RestClient / GatewayClient expect a DooverClientConfig — give them one
+        // with the local URLs, no auth, no org/sharing headers.
+        const restConfig = {
+            dataRestUrl: config.baseUrl,
+            controlApiUrl: config.baseUrl,
+            dataWssUrl: config.wssUrl ?? httpToWs(config.baseUrl),
+            organisationId: null,
+            sharing: "none",
+            fetchImpl: config.fetchImpl,
+            webSocketImpl: config.webSocketImpl,
+            webSocketFactory: config.webSocketFactory,
+            disableBrowserLifecycleHooks: config.disableBrowserLifecycleHooks,
+        };
+        this.rest = new RestClient(restConfig); // no auth arg
+        this.gatewayImpl = new GatewayClient(restConfig); // no auth arg
+        this.gatewayImpl.setProvenanceHook((value, ctx) => stamper.stampGatewayEvent(value, ctx));
+        this.gateway = this.gatewayImpl;
+        // Real subclients for advertised methods, gated so only allowed methods pass;
+        // all others throw UnsupportedCapabilityError.
+        const realAgents = wrapSubclient(new AgentsApi(this.rest, config.baseUrl), "agents", stamper);
+        const realChannels = wrapSubclient(new ChannelsApi(this.rest), "channels", stamper);
+        const realMessages = wrapSubclient(new MessagesApi(this.rest), "messages", stamper);
+        const realAggregates = wrapSubclient(new AggregatesApi(this.rest), "aggregates", stamper);
+        this.agents = this.gatedSubclient("agents", realAgents, ["listAgents"]);
+        this.channels = this.gatedSubclient("channels", realChannels, ["listChannels", "getChannel"]);
+        this.aggregates = this.gatedSubclient("aggregates", realAggregates, ["getAggregate", "putAggregate", "patchAggregate"]);
+        this.messages = this.gatedSubclient("messages", realMessages, ["listMessages", "postMessage", "putMessage", "patchMessage", "createMultipartPayload"]);
+        // Never-advertised subclients: always throw.
+        this.alarms = this.unsupportedSubclient("alarms");
+        this.connections = this.unsupportedSubclient("connections");
+        this.notifications = this.unsupportedSubclient("notifications");
+        this.permissions = this.unsupportedSubclient("permissions");
+        this.processors = this.unsupportedSubclient("processors");
+        this.turn = this.unsupportedSubclient("turn");
+        this.users = this.unsupportedSubclient("users");
+        this.rpc = this.unsupportedSubclient("rpc");
+        this.statusTracker = new ClientStatusTracker(this.identity.id, this.gateway, () => this.getKnownAgentScope());
+        // Resolve the device id on (re)connect so routing is precise before the
+        // first agent-scoped request; invalidate the cache on each new session.
+        this.gatewayImpl.on("ready", () => {
+            this.resolvedScope = null;
+            void this.getAgentScope();
+        });
+    }
+    // --- capabilities ---
+    getCapabilities() { return this.capSet; }
+    supports(cap) { return this.capSet.has(cap); }
+    // --- agent scope ---
+    getAgentScope() {
+        if (this.resolvedScope)
+            return Promise.resolve({ mode: "list", agentIds: this.resolvedScope });
+        if (this.scopeResolving)
+            return this.scopeResolving;
+        this.scopeResolving = (async () => {
+            let scope = { mode: "list", agentIds: [] };
+            try {
+                const res = await this.agents.listAgents();
+                const rawAgents = res?.agents ?? [];
+                const first = rawAgents[0];
+                const id = first?.id;
+                this.resolvedScope = id ? [String(id)] : [];
+                scope = { mode: "list", agentIds: this.resolvedScope };
+            }
+            catch {
+                // Don't cache on error — leave resolvedScope null so the next caller
+                // retries. Storing [] would permanently pin scope to no agents after a
+                // transient first-call failure (network unreachable, 503, etc.).
+            }
+            finally {
+                this.scopeResolving = null;
+                this.statusTracker.notifyScopeChanged();
+            }
+            return scope;
+        })();
+        return this.scopeResolving;
+    }
+    getKnownAgentScope() {
+        return this.resolvedScope ? { mode: "list", agentIds: this.resolvedScope } : "unknown";
+    }
+    // --- status ---
+    isConnected() { return this.gateway.isConnected(); }
+    getStatus() { return this.statusTracker.getStatus(); }
+    onStatusChange(listener) {
+        return this.statusTracker.onChange(listener);
+    }
+    /**
+     * 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.
+     */
+    gatedSubclient(name, real, allowed) {
+        const allowSet = new Set(allowed);
+        const clientId = this.identity.id;
+        return new Proxy(real, {
+            get(target, prop, receiver) {
+                if (typeof prop !== "string")
+                    return Reflect.get(target, prop, receiver);
+                if (allowSet.has(prop))
+                    return Reflect.get(target, prop, receiver);
+                return () => {
+                    const cap = METHOD_TO_CAPABILITY[`${name}.${prop}`] ?? guessCapability(name);
+                    return Promise.reject(new UnsupportedCapabilityError(cap, clientId));
+                };
+            },
+        });
+    }
+    /**
+     * Builds a Proxy that throws `UnsupportedCapabilityError` (mapped via
+     * METHOD_TO_CAPABILITY) for every method call. Used for subclients with no
+     * advertised methods.
+     */
+    unsupportedSubclient(name) {
+        const clientId = this.identity.id;
+        return new Proxy({}, {
+            get(_t, prop) {
+                if (typeof prop !== "string")
+                    return undefined;
+                return () => {
+                    const cap = METHOD_TO_CAPABILITY[`${name}.${prop}`] ?? guessCapability(name);
+                    return Promise.reject(new UnsupportedCapabilityError(cap, clientId));
+                };
+            },
+        });
+    }
+}
+const METHOD_TO_CAPABILITY = {
+    "agents.listAgents": "agents.list",
+    "agents.getMultiAgentMessages": "agents.multiAgentMessages",
+    "agents.getMultiAgentAggregates": "agents.multiAgentAggregates",
+    "agents.getTokenState": "agents.tokenRead",
+    "agents.setTokenPolicy": "agents.tokenManage",
+    "agents.setAuthLock": "agents.tokenManage",
+    "agents.revokeAllTokens": "agents.tokenManage",
+    "agents.setRevocationFloor": "agents.tokenManage",
+    "agents.createAdhocToken": "agents.tokenManage",
+    "agents.createDeviceToken": "agents.tokenManage",
+    "channels.listChannels": "channels.list",
+    "channels.getChannel": "channels.get",
+    "channels.createChannel": "channels.create",
+    "channels.putChannel": "channels.create",
+    "channels.archiveChannel": "channels.archive",
+    "channels.unarchiveChannel": "channels.archive",
+    "channels.listDataSeries": "channels.dataSeries",
+    "aggregates.getAggregate": "aggregates.get",
+    "aggregates.putAggregate": "aggregates.put",
+    "aggregates.patchAggregate": "aggregates.patch",
+    "aggregates.getAggregateAttachment": "aggregates.attachment",
+    "messages.listMessages": "messages.list",
+    "messages.postMessage": "messages.post",
+    "messages.getMessage": "messages.get",
+    "messages.putMessage": "messages.put",
+    "messages.patchMessage": "messages.put",
+    "messages.deleteMessage": "messages.delete",
+    "messages.getMessageAttachment": "messages.attachment",
+    "messages.getTimeseries": "messages.timeseries",
+    "messages.getInvocationLogs": "messages.invocationLogs",
+    "rpc.send": "rpc.send",
+    "users.getMe": "users.me",
+    "turn.createTurnToken": "turn.credentials",
+};
+function guessCapability(subclient) {
+    switch (subclient) {
+        case "alarms": return "alarms.read";
+        case "connections": return "connections.read";
+        case "notifications": return "notifications.read";
+        case "permissions": return "permissions.read";
+        case "processors": return "processors.read";
+        case "turn": return "turn.credentials";
+        case "users": return "users.me";
+        case "rpc": return "rpc.send";
+        default: return "channels.get";
+    }
+}

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

@@ -0,0 +1,165 @@
+import type { Capability } from "./capabilities.js";
+import type { AgentScope, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client.js";
+export type { DataClient } from "./data-client.js";
+export type { AgentScope } from "./data-client.js";
+export type { DataClientStatus } from "./data-client.js";
+export interface MultiplexConflict {
+    method: string;
+    agentId: string;
+    channelName: string;
+    /** All owning members that returned a value (in member order). */
+    sourceIds: string[];
+    /** The values, parallel to `sourceIds`. The chosen one is index 0. */
+    values: unknown[];
+    at: number;
+}
+/** A serialisable description of a source. */
+export interface SourceDescriptor {
+    id: string;
+    kind: string;
+    params?: Record<string, unknown>;
+    label?: string;
+}
+export interface RegisteredSource {
+    descriptor: SourceDescriptor;
+    client?: DataClient;
+    enabled: boolean;
+}
+export interface MultiplexClientOptions {
+    factory: (descriptor: SourceDescriptor) => DataClient | Promise<DataClient>;
+    register?: SourceDescriptor[];
+    enable?: string[];
+    enableAll?: boolean;
+    disconnectOnDisable?: boolean;
+    clientId?: string;
+}
+type MuxEvent = "change" | "conflict";
+export declare class MultiplexClient 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 registry;
+    private readonly factory;
+    private readonly disconnectOnDisable;
+    private readonly clientId;
+    private readonly eventListeners;
+    private capabilitiesCache;
+    private lastConflicts;
+    private readonly maxConflicts;
+    private readonly statusListeners;
+    /** sourceId → member unsubscribe fn for its onStatusChange. */
+    private readonly memberStatusUnsubs;
+    constructor(options: MultiplexClientOptions);
+    registerSource(descriptor: SourceDescriptor): void;
+    setActiveSources(idsOrDescriptors: Array<string | SourceDescriptor>): void;
+    enableSource(id: string, opts?: {
+        silent?: boolean;
+    }): void;
+    disableSource(id: string, opts?: {
+        silent?: boolean;
+    }): void;
+    removeSource(id: string): void;
+    getActiveSources(): readonly RegisteredSource[];
+    getRegisteredSources(): readonly RegisteredSource[];
+    /** Enabled members that have a built `client`. */
+    protected enabledClients(): Array<{
+        id: string;
+        src: RegisteredSource;
+        client: DataClient;
+    }>;
+    on(event: MuxEvent, handler: (...args: unknown[]) => void): void;
+    off(event: MuxEvent, handler: (...args: unknown[]) => void): void;
+    protected emit(event: MuxEvent, ...args: unknown[]): void;
+    private invalidateCapabilities;
+    private attachMemberListeners;
+    private detachMemberListeners;
+    private makeCompositeGateway;
+    /** Resolve the optional `{ sources?: string[] }` bag from a method's trailing
+     *  arg: returns the candidate members, narrowed to `sources` if given (each
+     *  must be enabled), still capability-filtered by the caller. The bag is the
+     *  LAST argument if it is a plain object with a `sources` array. */
+    private splitSourcesOption;
+    private candidates;
+    /** Extract the agent id from the first positional arg (string or identifier object). */
+    private extractAgentId;
+    /** Throw if no enabled member supports `cap` at all (regardless of agent). */
+    private assertSomeMemberSupports;
+    private isNotFound;
+    private requiredMessagesCapability;
+    private unsupportedMethod;
+    /**
+     * Route a cross-agent batch mutation.
+     *
+     * A batch can name agents served by different members, so unlike
+     * `routedWrite` there is no single target. Each item is resolved to its own
+     * member using the same rules (unsupported and ambiguous both throw), the
+     * batch is split into one sub-batch per member, and results are stitched
+     * back into the caller's original item order.
+     *
+     * Resolution happens for every item up front so an unroutable item fails
+     * the whole call before any member is written to, rather than leaving a
+     * half-applied batch behind.
+     */
+    private routedBatchWrite;
+    private guessNonCoreCap;
+    protected recordConflict(method: string, agentId: string, channelName: string, values: Array<{
+        value: unknown;
+        id: string;
+    }>): void;
+    getLastConflicts(): readonly MultiplexConflict[];
+    /**
+     * Returns a method that routes a write to exactly one member:
+     *  (a) `{ sources: [oneId] }` scoping → that member;
+     *  (b) else the single enabled member that owns the targeted agent and has `cap`;
+     *  (c) else `UnsupportedCapabilityError` (none) or `AmbiguousWriteError` (>1).
+     * The targeted agent id is `args[0]` (string form) or `args[0].agentId` (identifier form).
+     * Writes are never fanned out.
+     */
+    private routedWrite;
+    /** Agent-scoped "first success" — used by messages.getTimeseries / getInvocationLogs. */
+    private makeFanoutFirst;
+    /** Used by messages.getMessageAttachment — returns the first member that yields a Blob. */
+    private makeBlobFanout;
+    private makeChannelsFacade;
+    private makeAggregatesFacade;
+    private makeMessagesFacade;
+    private makeAgentsFacade;
+    private makeReadFacade;
+    private makeRpcFacade;
+    getCapabilities(): ReadonlySet<Capability>;
+    supports(cap: Capability): boolean;
+    /**
+     * Enabled members eligible for a request targeting `agentId`: those whose
+     * scope is `{ mode: "all" }` (the cloud — no enumeration), those whose list
+     * contains `agentId`, and those whose scope is still `"unknown"` (included
+     * optimistically; their scope settles for the next call). If `agentId` is
+     * undefined, all enabled members are eligible.
+     */
+    protected membersForAgent(agentId?: string): Array<{
+        id: string;
+        src: RegisteredSource;
+        client: DataClient;
+    }>;
+    /** Members (enabled) that both own `agentId` and advertise `cap`. */
+    protected membersForAgentWithCapability(agentId: string | undefined, cap: Capability): {
+        id: string;
+        src: RegisteredSource;
+        client: DataClient;
+    }[];
+    getAgentScope(): Promise<AgentScope>;
+    getKnownAgentScope(): AgentScope | "unknown";
+    isConnected(): boolean;
+    getStatus(): DataClientStatus;
+    onStatusChange(listener: (status: DataClientStatus) => void): () => void;
+    private emitStatus;
+}