doover-js 0.5.4 → 0.6.0

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;
+}

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

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalAgentClient = void 0;
+const agents_api_1 = require("../apis/agents-api");
+const aggregates_api_1 = require("../apis/aggregates-api");
+const channels_api_1 = require("../apis/channels-api");
+const messages_api_1 = require("../apis/messages-api");
+const gateway_client_1 = require("../gateway/gateway-client");
+const rest_client_1 = require("../http/rest-client");
+const errors_1 = require("./errors");
+const provenance_1 = require("./provenance");
+const status_tracker_1 = require("./status-tracker");
+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");
+}
+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 provenance_1.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 rest_client_1.RestClient(restConfig); // no auth arg
+        this.gatewayImpl = new gateway_client_1.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 = (0, provenance_1.wrapSubclient)(new agents_api_1.AgentsApi(this.rest, config.baseUrl), "agents", stamper);
+        const realChannels = (0, provenance_1.wrapSubclient)(new channels_api_1.ChannelsApi(this.rest), "channels", stamper);
+        const realMessages = (0, provenance_1.wrapSubclient)(new messages_api_1.MessagesApi(this.rest), "messages", stamper);
+        const realAggregates = (0, provenance_1.wrapSubclient)(new aggregates_api_1.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 status_tracker_1.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 errors_1.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 errors_1.UnsupportedCapabilityError(cap, clientId));
+                };
+            },
+        });
+    }
+}
+exports.LocalAgentClient = LocalAgentClient;
+const METHOD_TO_CAPABILITY = {
+    "agents.listAgents": "agents.list",
+    "agents.getMultiAgentMessages": "agents.multiAgentMessages",
+    "agents.getMultiAgentAggregates": "agents.multiAgentAggregates",
+    "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/client/multiplex-client.d.ts

@@ -0,0 +1,151 @@
+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 type { DataClient } from "./data-client";
+export type { AgentScope } from "./data-client";
+export type { DataClientStatus } from "./data-client";
+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;
+    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;
+}