doover-js 0.11.0 → 0.13.0

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

@@ -0,0 +1,60 @@
+import type { SourceProvenance } from "../types/provenance.js";
+/** A stamped value: adds `__source` to plain objects and their array elements.
+ *  For object values, also adds `__source` to any known nested-object props
+ *  (aggregate, message) and stamps elements of array-valued props. */
+type StampedElement<T> = T extends Record<string, unknown> ? T & {
+    __source?: SourceProvenance;
+} : T;
+type StampedProp<V> = V extends (infer E)[] ? StampedElement<E>[] : V extends Record<string, unknown> ? V & {
+    __source?: SourceProvenance;
+} : V;
+type Stamped<T> = T extends (infer E)[] ? StampedElement<E>[] : T extends Record<string, unknown> ? {
+    [K in keyof T]: StampedProp<T[K]>;
+} & {
+    __source?: SourceProvenance;
+} : T;
+/** Map a subclient type so that async methods return Stamped results. */
+export type WrappedSubclient<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Stamped<R>> : T[K];
+};
+export interface ClientIdentity {
+    id: string;
+    kind: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+interface RestContext {
+    /** e.g. "messages.listMessages" */
+    method: string;
+    /** caller inputs (agentId, channelName, params, body summary) */
+    request: Record<string, unknown>;
+    startedAt: number;
+    durationMs: number;
+    status?: number;
+}
+interface GatewayContext {
+    event: string;
+    sessionId?: string;
+}
+export declare class ProvenanceStamper {
+    private readonly identity;
+    constructor(identity: ClientIdentity);
+    stampRest<T>(value: T, ctx: RestContext): Stamped<T>;
+    stampGatewayEvent<T>(value: T, ctx: GatewayContext): Stamped<T>;
+    /** Build the full provenance envelope from a `via`. */
+    private prov;
+    /**
+     * Arrays → stamp each plain-object element. Plain objects → set `__source`,
+     * then shallow-stamp array-valued props' elements and known nested-object
+     * props (`aggregate`, `message`). Everything else (Blob, primitives,
+     * undefined, FormData, class instances) → returned unchanged.
+     */
+    private stampGraph;
+}
+/**
+ * Returns a Proxy over `api` whose methods, when they return a Promise, stamp
+ * the resolved value with `via.method = "<subclientName>.<methodName>"`.
+ * Synchronous returns (e.g. `createMultipartPayload`) pass through untouched.
+ */
+export declare function wrapSubclient<T extends object>(api: T, subclientName: string, stamper: ProvenanceStamper): WrappedSubclient<T>;
+export {};

package/dist/esm/client/provenance.js

@@ -0,0 +1,108 @@
+/** Property names whose (object) value should also be stamped, for the known
+ *  gateway envelopes ({ ..., aggregate }, { ..., message }). */
+const NESTED_OBJECT_PROPS = ["aggregate", "message"];
+function isPlainObject(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    if (Array.isArray(v))
+        return false;
+    if (typeof Blob !== "undefined" && v instanceof Blob)
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+export class ProvenanceStamper {
+    constructor(identity) {
+        this.identity = identity;
+    }
+    stampRest(value, ctx) {
+        const via = {
+            transport: "rest",
+            method: ctx.method,
+            request: ctx.request,
+            startedAt: ctx.startedAt,
+            durationMs: ctx.durationMs,
+            ...(ctx.status !== undefined ? { status: ctx.status } : {}),
+        };
+        return this.stampGraph(value, via);
+    }
+    stampGatewayEvent(value, ctx) {
+        const via = {
+            transport: "gateway",
+            event: ctx.event,
+            ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}),
+            receivedAt: Date.now(),
+        };
+        return this.stampGraph(value, via);
+    }
+    /** Build the full provenance envelope from a `via`. */
+    prov(via) {
+        return { client: this.identity, retrievedAt: Date.now(), via };
+    }
+    /**
+     * Arrays → stamp each plain-object element. Plain objects → set `__source`,
+     * then shallow-stamp array-valued props' elements and known nested-object
+     * props (`aggregate`, `message`). Everything else (Blob, primitives,
+     * undefined, FormData, class instances) → returned unchanged.
+     */
+    stampGraph(value, via) {
+        const prov = this.prov(via);
+        if (Array.isArray(value)) {
+            return value.map((el) => (isPlainObject(el) ? { ...el, __source: prov } : el));
+        }
+        if (!isPlainObject(value))
+            return value;
+        const out = { ...value, __source: prov };
+        for (const [k, v] of Object.entries(out)) {
+            if (k === "__source")
+                continue;
+            if (Array.isArray(v)) {
+                out[k] = v.map((el) => (isPlainObject(el) ? { ...el, __source: prov } : el));
+            }
+            else if (NESTED_OBJECT_PROPS.includes(k) && isPlainObject(v)) {
+                out[k] = { ...v, __source: prov };
+            }
+        }
+        return out;
+    }
+}
+/**
+ * Returns a Proxy over `api` whose methods, when they return a Promise, stamp
+ * the resolved value with `via.method = "<subclientName>.<methodName>"`.
+ * Synchronous returns (e.g. `createMultipartPayload`) pass through untouched.
+ */
+export function wrapSubclient(api, subclientName, stamper) {
+    return new Proxy(api, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function" || typeof prop !== "string")
+                return value;
+            const methodName = `${subclientName}.${prop}`;
+            return function (...args) {
+                const startedAt = Date.now();
+                const out = value.apply(target, args);
+                if (out instanceof Promise) {
+                    return out.then((result) => stamper.stampRest(result, {
+                        method: methodName,
+                        request: { args: summariseArgs(args) },
+                        startedAt,
+                        durationMs: Date.now() - startedAt,
+                    }));
+                }
+                return out;
+            };
+        },
+    });
+}
+/** Keep `via.request` small: drop FormData/Blob bodies, cap string length. */
+function summariseArgs(args) {
+    return args.map((a) => {
+        if (typeof FormData !== "undefined" && a instanceof FormData)
+            return "[FormData]";
+        if (typeof Blob !== "undefined" && a instanceof Blob)
+            return "[Blob]";
+        if (typeof a === "string" && a.length > 200)
+            return `${a.slice(0, 200)}…`;
+        return a;
+    });
+}

package/dist/esm/client/request-options.d.ts

@@ -0,0 +1,23 @@
+import type { OfflineReadCacheOptions } from "./offline-cache.js";
+export declare const REQUEST_OPTIONS_SYMBOL: unique symbol;
+export interface DooverRequestOptions {
+    /**
+     * Restrict a call to these source ids on a `MultiplexClient`.
+     */
+    sources?: string[];
+    /**
+     * Offline cache behavior for this specific call. `false` opts out even when
+     * a stored channel policy would otherwise match.
+     */
+    cache?: OfflineReadCacheOptions | false;
+    [REQUEST_OPTIONS_SYMBOL]?: true;
+}
+export declare function requestOptions<T extends Omit<DooverRequestOptions, typeof REQUEST_OPTIONS_SYMBOL>>(options: T): T & {
+    [REQUEST_OPTIONS_SYMBOL]: true;
+};
+export declare function isDooverRequestOptions(value: unknown): value is DooverRequestOptions;
+export declare function splitRequestOptions(args: unknown[]): {
+    args: unknown[];
+    request?: DooverRequestOptions;
+};
+export declare function delegateRequestOptions(request?: DooverRequestOptions): DooverRequestOptions | undefined;

package/dist/esm/client/request-options.js

@@ -0,0 +1,23 @@
+export const REQUEST_OPTIONS_SYMBOL = Symbol.for("doover.requestOptions");
+export function requestOptions(options) {
+    return { ...options, [REQUEST_OPTIONS_SYMBOL]: true };
+}
+export function isDooverRequestOptions(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (candidate[REQUEST_OPTIONS_SYMBOL] === true ||
+        Array.isArray(candidate.sources) ||
+        "cache" in candidate);
+}
+export function splitRequestOptions(args) {
+    const last = args[args.length - 1];
+    if (!isDooverRequestOptions(last))
+        return { args };
+    return { args: args.slice(0, -1), request: last };
+}
+export function delegateRequestOptions(request) {
+    if (!request?.sources)
+        return undefined;
+    return requestOptions({ sources: request.sources });
+}

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

@@ -0,0 +1,26 @@
+import type { DooverClientConfig } from "../http/rest-client.js";
+import { DooverClient } from "./doover-client.js";
+/**
+ * Get the process-wide `DooverClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_client__` to survive module-level duplicates
+ * — if this module is loaded more than once (HMR, federation boundaries,
+ * multiple bundles) each load still returns the same instance and therefore
+ * the same WebSocket + REST configuration.
+ *
+ * The first caller's `config` wins. Subsequent calls ignore the `config`
+ * arg and return the existing instance — log a warning if they differ so
+ * drift is visible in dev tools.
+ */
+export declare function getDooverClient(config: DooverClientConfig): DooverClient;
+/**
+ * Returns the current singleton if one has been initialised, otherwise
+ * `null`. Useful for callers that want to read the client opportunistically
+ * without forcing construction.
+ */
+export declare function peekDooverClient(): DooverClient | null;
+/**
+ * Clear the singleton. Primarily for tests — not recommended in production
+ * code since any active subscriptions reference the old instance.
+ */
+export declare function resetDooverClient(): void;

package/dist/esm/client/singleton.js

@@ -0,0 +1,54 @@
+import { DooverClient } from "./doover-client.js";
+const GLOBAL_KEY = "__doover_js_client__";
+function globalBag() {
+    return globalThis;
+}
+/**
+ * Get the process-wide `DooverClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_client__` to survive module-level duplicates
+ * — if this module is loaded more than once (HMR, federation boundaries,
+ * multiple bundles) each load still returns the same instance and therefore
+ * the same WebSocket + REST configuration.
+ *
+ * The first caller's `config` wins. Subsequent calls ignore the `config`
+ * arg and return the existing instance — log a warning if they differ so
+ * drift is visible in dev tools.
+ */
+export function getDooverClient(config) {
+    const bag = globalBag();
+    const existing = bag[GLOBAL_KEY];
+    if (existing) {
+        if (configsDiffer(existing, config)) {
+            // eslint-disable-next-line no-console
+            console.warn("[doover-js] getDooverClient called with a config that differs " +
+                "from the already-initialised singleton. The existing client is " +
+                "being reused; the new config is ignored.");
+        }
+        return existing;
+    }
+    const client = new DooverClient(config);
+    bag[GLOBAL_KEY] = client;
+    return client;
+}
+/**
+ * Returns the current singleton if one has been initialised, otherwise
+ * `null`. Useful for callers that want to read the client opportunistically
+ * without forcing construction.
+ */
+export function peekDooverClient() {
+    return globalBag()[GLOBAL_KEY] ?? null;
+}
+/**
+ * Clear the singleton. Primarily for tests — not recommended in production
+ * code since any active subscriptions reference the old instance.
+ */
+export function resetDooverClient() {
+    delete globalBag()[GLOBAL_KEY];
+}
+function configsDiffer(existing, next) {
+    const a = existing.rest.config;
+    return (a.dataRestUrl !== next.dataRestUrl ||
+        a.dataWssUrl !== next.dataWssUrl ||
+        a.controlApiUrl !== next.controlApiUrl);
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Opt-in instrumentation for `DooverClient`. When enabled, counts REST
+ * requests and gateway messages and keeps running latency stats. Disabled
+ * by default — the record methods short-circuit so production apps pay
+ * nothing unless a debug UI turns it on.
+ */
+export interface RestStatsSnapshot {
+    enabled: boolean;
+    /** Total requests started since stats were enabled (or last reset). */
+    totalRequests: number;
+    /** Requests currently in flight. */
+    pendingRequests: number;
+    /** Requests that resolved successfully. */
+    completedRequests: number;
+    /** Requests that threw / rejected. */
+    failedRequests: number;
+    /** Mean latency of settled requests, ms. Null until at least one lands. */
+    averageLatencyMs: number | null;
+    /** Latency of the most recently settled request, ms. */
+    lastLatencyMs: number | null;
+}
+export interface GatewayStatsSnapshot {
+    enabled: boolean;
+    /** Frames we've sent on the gateway socket. */
+    messagesSent: number;
+    /** Frames we've received on the gateway socket. */
+    messagesReceived: number;
+}
+export interface RpcStatsSnapshot {
+    enabled: boolean;
+    totalRpcs: number;
+    pendingRpcs: number;
+    completedRpcs: number;
+    failedRpcs: number;
+    timedOutRpcs: number;
+    abortedRpcs: number;
+    averageLatencyMs: number | null;
+    lastLatencyMs: number | null;
+    peakPendingRpcs: number;
+}
+export interface DooverStatsSnapshot {
+    rest: RestStatsSnapshot;
+    gateway: GatewayStatsSnapshot;
+    rpc: RpcStatsSnapshot;
+}
+export declare class DooverStatsCollector {
+    private enabled;
+    private rTotal;
+    private rPending;
+    private rCompleted;
+    private rFailed;
+    private rLatencySum;
+    private rLastLatency;
+    private gSent;
+    private gReceived;
+    private rpTotal;
+    private rpPending;
+    private rpCompleted;
+    private rpFailed;
+    private rpTimedOut;
+    private rpAborted;
+    private rpLatencySum;
+    private rpLastLatency;
+    private rpPeakPending;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    reset(): void;
+    /**
+     * Record the start of a REST request. Returns the start timestamp the
+     * caller must hand back to `recordRestEnd`, or `null` if stats are off.
+     */
+    recordRestStart(): number | null;
+    recordRestEnd(startedAt: number | null, succeeded: boolean): void;
+    recordGatewaySent(): void;
+    recordGatewayReceived(): void;
+    recordRpcStart(): number | null;
+    recordRpcEnd(startedAt: number | null, outcome: "success" | "error" | "timeout" | "abort"): void;
+    snapshot(): DooverStatsSnapshot;
+}

package/dist/esm/client/stats.js

@@ -0,0 +1,155 @@
+/**
+ * Opt-in instrumentation for `DooverClient`. When enabled, counts REST
+ * requests and gateway messages and keeps running latency stats. Disabled
+ * by default — the record methods short-circuit so production apps pay
+ * nothing unless a debug UI turns it on.
+ */
+export class DooverStatsCollector {
+    constructor() {
+        this.enabled = false;
+        this.rTotal = 0;
+        this.rPending = 0;
+        this.rCompleted = 0;
+        this.rFailed = 0;
+        this.rLatencySum = 0;
+        this.rLastLatency = null;
+        this.gSent = 0;
+        this.gReceived = 0;
+        this.rpTotal = 0;
+        this.rpPending = 0;
+        this.rpCompleted = 0;
+        this.rpFailed = 0;
+        this.rpTimedOut = 0;
+        this.rpAborted = 0;
+        this.rpLatencySum = 0;
+        this.rpLastLatency = null;
+        this.rpPeakPending = 0;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    reset() {
+        this.rTotal = 0;
+        this.rPending = 0;
+        this.rCompleted = 0;
+        this.rFailed = 0;
+        this.rLatencySum = 0;
+        this.rLastLatency = null;
+        this.gSent = 0;
+        this.gReceived = 0;
+        this.rpTotal = 0;
+        this.rpPending = 0;
+        this.rpCompleted = 0;
+        this.rpFailed = 0;
+        this.rpTimedOut = 0;
+        this.rpAborted = 0;
+        this.rpLatencySum = 0;
+        this.rpLastLatency = null;
+        this.rpPeakPending = 0;
+    }
+    /**
+     * Record the start of a REST request. Returns the start timestamp the
+     * caller must hand back to `recordRestEnd`, or `null` if stats are off.
+     */
+    recordRestStart() {
+        if (!this.enabled)
+            return null;
+        this.rTotal += 1;
+        this.rPending += 1;
+        return now();
+    }
+    recordRestEnd(startedAt, succeeded) {
+        if (!this.enabled || startedAt === null)
+            return;
+        this.rPending = Math.max(0, this.rPending - 1);
+        if (succeeded)
+            this.rCompleted += 1;
+        else
+            this.rFailed += 1;
+        const latency = now() - startedAt;
+        this.rLastLatency = latency;
+        this.rLatencySum += latency;
+    }
+    recordGatewaySent() {
+        if (!this.enabled)
+            return;
+        this.gSent += 1;
+    }
+    recordGatewayReceived() {
+        if (!this.enabled)
+            return;
+        this.gReceived += 1;
+    }
+    recordRpcStart() {
+        if (!this.enabled)
+            return null;
+        this.rpTotal += 1;
+        this.rpPending += 1;
+        if (this.rpPending > this.rpPeakPending)
+            this.rpPeakPending = this.rpPending;
+        return now();
+    }
+    recordRpcEnd(startedAt, outcome) {
+        if (!this.enabled || startedAt === null)
+            return;
+        this.rpPending = Math.max(0, this.rpPending - 1);
+        switch (outcome) {
+            case "success":
+                this.rpCompleted += 1;
+                break;
+            case "error":
+                this.rpFailed += 1;
+                break;
+            case "timeout":
+                this.rpTimedOut += 1;
+                break;
+            case "abort":
+                this.rpAborted += 1;
+                break;
+        }
+        const latency = now() - startedAt;
+        this.rpLastLatency = latency;
+        this.rpLatencySum += latency;
+    }
+    snapshot() {
+        const settled = this.rCompleted + this.rFailed;
+        const rpcSettled = this.rpCompleted + this.rpFailed + this.rpTimedOut + this.rpAborted;
+        return {
+            rest: {
+                enabled: this.enabled,
+                totalRequests: this.rTotal,
+                pendingRequests: this.rPending,
+                completedRequests: this.rCompleted,
+                failedRequests: this.rFailed,
+                averageLatencyMs: settled > 0 ? this.rLatencySum / settled : null,
+                lastLatencyMs: this.rLastLatency,
+            },
+            gateway: {
+                enabled: this.enabled,
+                messagesSent: this.gSent,
+                messagesReceived: this.gReceived,
+            },
+            rpc: {
+                enabled: this.enabled,
+                totalRpcs: this.rpTotal,
+                pendingRpcs: this.rpPending,
+                completedRpcs: this.rpCompleted,
+                failedRpcs: this.rpFailed,
+                timedOutRpcs: this.rpTimedOut,
+                abortedRpcs: this.rpAborted,
+                averageLatencyMs: rpcSettled > 0 ? this.rpLatencySum / rpcSettled : null,
+                lastLatencyMs: this.rpLastLatency,
+                peakPendingRpcs: this.rpPeakPending,
+            },
+        };
+    }
+}
+function now() {
+    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+        return performance.now();
+    }
+    return Date.now();
+}

package/dist/esm/client/status-tracker.d.ts

@@ -0,0 +1,24 @@
+import type { AgentScope, DataClientStatus, GatewayClientLike } from "./data-client.js";
+/**
+ * Tracks a `DataClient`'s realtime status by subscribing to its gateway's
+ * `open` / `ready` / `close` / `wssError` events. Emits a fresh
+ * `DataClientStatus` to listeners whenever the derived snapshot changes.
+ */
+export declare class ClientStatusTracker {
+    private readonly clientId;
+    private readonly gateway;
+    private readonly knownScope;
+    private lastEvent;
+    private lastError;
+    private session;
+    private listeners;
+    private detach;
+    constructor(clientId: string, gateway: GatewayClientLike, knownScope: () => AgentScope | "unknown" | string);
+    /** Call when the agent scope resolves (so listeners re-render). */
+    notifyScopeChanged(): void;
+    getStatus(): DataClientStatus;
+    onChange(listener: (status: DataClientStatus) => void): () => void;
+    dispose(): void;
+    private transition;
+    private emit;
+}

package/dist/esm/client/status-tracker.js

@@ -0,0 +1,86 @@
+/**
+ * Tracks a `DataClient`'s realtime status by subscribing to its gateway's
+ * `open` / `ready` / `close` / `wssError` events. Emits a fresh
+ * `DataClientStatus` to listeners whenever the derived snapshot changes.
+ */
+export class ClientStatusTracker {
+    constructor(clientId, gateway, knownScope) {
+        this.clientId = clientId;
+        this.gateway = gateway;
+        this.knownScope = knownScope;
+        this.lastEvent = "init";
+        this.session = null;
+        this.listeners = new Set();
+        this.detach = [];
+        const onOpen = () => this.transition("open");
+        const onReady = (s) => {
+            if (s?.session_id)
+                this.session = { id: s.session_id };
+            this.transition("ready");
+        };
+        const onClose = () => this.transition("close");
+        const onErr = (e) => {
+            this.lastError = e?.message ?? "gateway error";
+            this.transition("error");
+        };
+        gateway.on("open", onOpen);
+        gateway.on("ready", onReady);
+        gateway.on("close", onClose);
+        gateway.on("wssError", onErr);
+        this.detach.push(() => gateway.off("open", onOpen), () => gateway.off("ready", onReady), () => gateway.off("close", onClose), () => gateway.off("wssError", onErr));
+    }
+    /** Call when the agent scope resolves (so listeners re-render). */
+    notifyScopeChanged() {
+        this.emit();
+    }
+    getStatus() {
+        const connected = this.gateway.isConnected();
+        let state;
+        if (this.lastEvent === "error")
+            state = "error";
+        else if (connected)
+            state = "connected";
+        else if (this.lastEvent === "init")
+            state = "disconnected";
+        else
+            state = "connecting"; // saw open/close but not currently connected → reconnecting
+        return {
+            clientId: this.clientId,
+            connected,
+            state,
+            session: this.session,
+            lastEvent: this.lastEvent,
+            latencyMs: null,
+            ...(this.lastError ? { lastError: this.lastError } : {}),
+            agentScope: this.knownScope(),
+            at: Date.now(),
+        };
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            this.listeners.delete(listener);
+        };
+    }
+    dispose() {
+        this.detach.forEach((fn) => fn());
+        this.detach = [];
+        this.listeners.clear();
+    }
+    transition(event) {
+        this.lastEvent = event;
+        if (event !== "error") {
+            // a successful lifecycle event clears a stale error so state can recover
+            this.lastError = undefined;
+        }
+        this.emit();
+    }
+    emit() {
+        const snapshot = this.getStatus();
+        this.listeners.forEach((l) => l(snapshot));
+    }
+}