doover-js 0.11.0 → 0.13.0

package/dist/esm/react/useConnectionState.d.ts

@@ -0,0 +1,26 @@
+export type ConnectionStatus = "connecting" | "open";
+export interface ConnectionState {
+    /**
+     * `"open"` once the gateway has received a `Ready` frame;
+     * `"connecting"` any time the socket is reconnecting or awaiting Ready.
+     */
+    status: ConnectionStatus;
+    /** Timestamp of the most recent `Ready` frame, or `null` until the first one. */
+    lastOpenedAt: number | null;
+}
+/**
+ * @deprecated Prefer `useClientStatus()` — it works for both `DooverClient` and
+ * `MultiplexClient`, and carries session, latency, last error and per-source
+ * state. `useConnectionState` is gateway-flavoured and single-source only;
+ * it will remain but new code should not use it.
+ *
+ * Subscribes to the gateway's connection lifecycle and returns a snapshot
+ * suitable for a connection-indicator UI.
+ *
+ * The gateway doesn't measure application-level latency — liveness is
+ * handled at the WebSocket-protocol layer via ping/pong frames (opcodes
+ * 0x9 / 0xA) which browsers answer automatically but don't expose to JS.
+ * Dead connections surface as the `close` event, which we already handle
+ * via auto-reconnect.
+ */
+export declare function useConnectionState(): ConnectionState;

package/dist/esm/react/useConnectionState.js

@@ -0,0 +1,45 @@
+import { useEffect, useState } from "react";
+import { useDooverClient } from "./context.js";
+const INITIAL = {
+    status: "connecting",
+    lastOpenedAt: null,
+};
+/**
+ * @deprecated Prefer `useClientStatus()` — it works for both `DooverClient` and
+ * `MultiplexClient`, and carries session, latency, last error and per-source
+ * state. `useConnectionState` is gateway-flavoured and single-source only;
+ * it will remain but new code should not use it.
+ *
+ * Subscribes to the gateway's connection lifecycle and returns a snapshot
+ * suitable for a connection-indicator UI.
+ *
+ * The gateway doesn't measure application-level latency — liveness is
+ * handled at the WebSocket-protocol layer via ping/pong frames (opcodes
+ * 0x9 / 0xA) which browsers answer automatically but don't expose to JS.
+ * Dead connections surface as the `close` event, which we already handle
+ * via auto-reconnect.
+ */
+export function useConnectionState() {
+    const client = useDooverClient();
+    const [state, setState] = useState(() => client.gateway.isConnected() && client.gateway.getSession()
+        ? {
+            status: "open",
+            lastOpenedAt: Date.now(),
+        }
+        : INITIAL);
+    useEffect(() => {
+        const onReady = () => setState((prev) => ({
+            ...prev,
+            status: "open",
+            lastOpenedAt: Date.now(),
+        }));
+        const onClose = () => setState((prev) => ({ ...prev, status: "connecting" }));
+        client.gateway.on("ready", onReady);
+        client.gateway.on("close", onClose);
+        return () => {
+            client.gateway.off("ready", onReady);
+            client.gateway.off("close", onClose);
+        };
+    }, [client]);
+    return state;
+}

package/dist/esm/react/useDeviceMap.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Default shape for entries in an agent's `DEVICE_MAP` — covers every field
+ * an app may request via `x-extraDeviceFields` on its
+ * `dv_proc_extended_permissions` schema (see doover-control's
+ * `ALLOWED_DEVICE_MAP_EXTRA_FIELDS` / `COMPOUND_DEVICE_MAP_SUBFIELDS`). All
+ * fields are optional because the app picks which to include — `id` is the
+ * one constant (the platform always uses it as the dict key, and the hook
+ * ensures it's also present on the entry value).
+ *
+ * Pass a narrower type as the hook's generic argument when you know exactly
+ * which fields your app requested.
+ */
+export interface DeviceMapEntry {
+    /** Snowflake id — always present (the hook fills it from the dict key). */
+    id: string;
+    name?: string | null;
+    display_name?: string | null;
+    type?: {
+        id?: string | number | null;
+        name?: string | null;
+        /** `type.config` is the device-type's JSON config; shape depends on the type. */
+        config?: Record<string, unknown> | null;
+    } | null;
+    group?: {
+        id?: string | number | null;
+        name?: string | null;
+    } | null;
+    organisation?: {
+        id?: string | number | null;
+        name?: string | null;
+    } | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    fa_icon?: string | null;
+    notes?: string | null;
+    /** `extra_config` is a free-form JSON dict on the device; shape depends on org/usage. */
+    extra_config?: Record<string, unknown> | null;
+    /** Each app installation visible to this app, when `app_installs` (or any subfield) was requested. */
+    app_installs?: Array<{
+        id?: string | number | null;
+        name?: string | null;
+        display_name?: string | null;
+        application_id?: string | number | null;
+        application_name?: string | null;
+    }>;
+    /** Each solution installation, when `solution_installs` (or any subfield) was requested. */
+    solution_installs?: Array<{
+        id?: string | number | null;
+        display_name?: string | null;
+        solution_id?: string | number | null;
+        solution_display_name?: string | null;
+    }>;
+    /** Any other field requested via `x-extraDeviceFields` ends up here. */
+    [extra: string]: unknown;
+}
+export interface UseDeviceMapOptions {
+    /**
+     * Drop the agent's own id from the returned set. Defaults true — a
+     * dashboard generally doesn't want to render itself as a "device". Set
+     * false to include it.
+     */
+    excludeSelf?: boolean;
+}
+export interface UseDeviceMapResult<TEntry extends DeviceMapEntry> {
+    /** The device entries, in `DEVICE_MAP` insertion order, with `id` populated from each entry's dict key. */
+    devices: TEntry[];
+    /** Just the device ids — handy as the input to `useMultiAgentAggregates` etc. */
+    deviceIds: string[];
+    /** The `DEVICE_MAP` keyed by id — for O(1) per-device lookups. */
+    raw: Record<string, TEntry>;
+    /** True while the agent's `deployment_config` is loading for the first time. */
+    isLoading: boolean;
+    /** True if the underlying channel fetch errored. */
+    isError: boolean;
+    /**
+     * True when both `agentId` and `appKey` were supplied and the loaded
+     * `deployment_config` actually contains a `DEVICE_MAP` at
+     * `applications[appKey].DEVICE_MAP`. False indicates the hook is either
+     * still warming up or the app isn't configured to expose a DEVICE_MAP —
+     * use this to distinguish "no devices granted yet" from "look at your config".
+     */
+    hasDeviceMap: boolean;
+}
+/**
+ * Read an agent's `DEVICE_MAP` — the platform-populated list of devices a
+ * given app instance has been granted permission to see — from the agent's
+ * `deployment_config` channel. Returns the entries flattened, keyed, and with
+ * `id` filled in from the dict key, plus a ready-to-use `deviceIds` array.
+ *
+ * Pass a narrower entry type as the generic when your app declares specific
+ * `x-extraDeviceFields`, e.g.:
+ *
+ * ```ts
+ * interface MyEntry extends DeviceMapEntry {
+ *   type?: { id?: string | null; name?: string | null; config?: { battery_voltage_tag?: string | null } | null } | null;
+ * }
+ * const { devices, deviceIds } = useDeviceMap<MyEntry>(agentId, "my_dashboard");
+ * ```
+ *
+ * If `appKey` is missing or `applications[appKey].DEVICE_MAP` isn't present,
+ * the hook returns an empty result with `hasDeviceMap: false` — it does not
+ * silently fall back to whichever other app block happens to carry a
+ * DEVICE_MAP, since that masks misconfiguration.
+ *
+ * @param agentId    The agent's id (typically from `customer_site/useRemoteParams`).
+ * @param appKey     The app's key, e.g. `"connectivity_dashboard"`. `DEVICE_MAP` lives at `deployment_config.applications[appKey].DEVICE_MAP`.
+ * @param options    See `UseDeviceMapOptions`.
+ */
+export declare function useDeviceMap<TEntry extends DeviceMapEntry = DeviceMapEntry>(agentId: string | undefined, appKey: string | undefined, options?: UseDeviceMapOptions): UseDeviceMapResult<TEntry>;

package/dist/esm/react/useDeviceMap.js

@@ -0,0 +1,59 @@
+import { useMemo } from "react";
+import { useAgentChannel } from "./useAgentChannel.js";
+/**
+ * Read an agent's `DEVICE_MAP` — the platform-populated list of devices a
+ * given app instance has been granted permission to see — from the agent's
+ * `deployment_config` channel. Returns the entries flattened, keyed, and with
+ * `id` filled in from the dict key, plus a ready-to-use `deviceIds` array.
+ *
+ * Pass a narrower entry type as the generic when your app declares specific
+ * `x-extraDeviceFields`, e.g.:
+ *
+ * ```ts
+ * interface MyEntry extends DeviceMapEntry {
+ *   type?: { id?: string | null; name?: string | null; config?: { battery_voltage_tag?: string | null } | null } | null;
+ * }
+ * const { devices, deviceIds } = useDeviceMap<MyEntry>(agentId, "my_dashboard");
+ * ```
+ *
+ * If `appKey` is missing or `applications[appKey].DEVICE_MAP` isn't present,
+ * the hook returns an empty result with `hasDeviceMap: false` — it does not
+ * silently fall back to whichever other app block happens to carry a
+ * DEVICE_MAP, since that masks misconfiguration.
+ *
+ * @param agentId    The agent's id (typically from `customer_site/useRemoteParams`).
+ * @param appKey     The app's key, e.g. `"connectivity_dashboard"`. `DEVICE_MAP` lives at `deployment_config.applications[appKey].DEVICE_MAP`.
+ * @param options    See `UseDeviceMapOptions`.
+ */
+export function useDeviceMap(agentId, appKey, options) {
+    const excludeSelf = options?.excludeSelf ?? true;
+    const { data: deploymentConfig, isLoading, isError } = useAgentChannel(agentId, "deployment_config");
+    return useMemo(() => {
+        const empty = {
+            devices: [],
+            deviceIds: [],
+            raw: {},
+            isLoading,
+            isError,
+            hasDeviceMap: false,
+        };
+        if (!appKey)
+            return empty;
+        const block = deploymentConfig?.applications?.[appKey];
+        const map = block?.DEVICE_MAP;
+        if (!map || typeof map !== "object")
+            return empty;
+        const raw = {};
+        const devices = [];
+        for (const [id, entry] of Object.entries(map)) {
+            if (excludeSelf && id === agentId)
+                continue;
+            // dict key is the source of truth for `id` — the platform only puts it
+            // on the entry value when the app explicitly requested "id" in extra_fields
+            const filled = { ...(entry ?? {}), id };
+            raw[id] = filled;
+            devices.push(filled);
+        }
+        return { devices, deviceIds: devices.map((d) => d.id), raw, isLoading, isError, hasDeviceMap: true };
+    }, [deploymentConfig, appKey, agentId, excludeSelf, isLoading, isError]);
+}

package/dist/esm/react/useInvocationLogs.d.ts

@@ -0,0 +1,23 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { ChannelIdentifier } from "../types/viewer.js";
+export declare function invocationLogsQueryKey(agentId: string | undefined, channelName: string | undefined, messageId: string | undefined): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "message", string | undefined, "logs"];
+export interface UseInvocationLogsOptions {
+    /** Defaults to true. Set false to skip the query (e.g. dialog closed). */
+    enabled?: boolean;
+    /**
+     * react-query retry behaviour. Defaults to false — the logs endpoint
+     * commonly 404s while logs are still materialising server-side, and a
+     * manual refetch button is friendlier than silent retry.
+     */
+    retry?: boolean | number;
+}
+/**
+ * Fetch the log entries for a single invocation message. The `/logs`
+ * endpoint is only meaningful for invocation messages (channel name like
+ * `dv-proc-inv-…`); other message types return 404.
+ *
+ * Generic on `TLog` — the shape of a single log entry. Defaults to `unknown`
+ * because log payloads are domain-specific (lambda telemetry, app-level
+ * structured logs, etc.) and doover-js does not own the canonical shape.
+ */
+export declare function useInvocationLogs<TLog = unknown>(identifier: ChannelIdentifier, messageId: string | undefined, options?: UseInvocationLogsOptions): UseQueryResult<TLog[]>;

package/dist/esm/react/useInvocationLogs.js

@@ -0,0 +1,37 @@
+import { useQuery } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+export function invocationLogsQueryKey(agentId, channelName, messageId) {
+    return [
+        "doover",
+        "agent",
+        agentId,
+        "channel",
+        channelName,
+        "message",
+        messageId,
+        "logs",
+    ];
+}
+/**
+ * Fetch the log entries for a single invocation message. The `/logs`
+ * endpoint is only meaningful for invocation messages (channel name like
+ * `dv-proc-inv-…`); other message types return 404.
+ *
+ * Generic on `TLog` — the shape of a single log entry. Defaults to `unknown`
+ * because log payloads are domain-specific (lambda telemetry, app-level
+ * structured logs, etc.) and doover-js does not own the canonical shape.
+ */
+export function useInvocationLogs(identifier, messageId, options) {
+    const client = useDooverClient();
+    const { agentId, channelName } = identifier;
+    return useQuery({
+        queryKey: invocationLogsQueryKey(agentId, channelName, messageId),
+        queryFn: () => client.messages.getInvocationLogs(agentId, channelName, messageId),
+        enabled: !!agentId &&
+            !!channelName &&
+            !!messageId &&
+            (options?.enabled ?? true),
+        retry: options?.retry ?? false,
+        staleTime: Infinity,
+    });
+}

package/dist/esm/react/useMultiAgentAggregates.d.ts

@@ -0,0 +1,38 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Aggregate, JSONValue, AgentAggregate } from "../types/common.js";
+export declare function multiAgentAggregatesQueryKey(channelName: string, agentIds: string[], fields?: readonly string[], sources?: string[]): readonly ["doover", "channel", string, "aggregates", string, "src", string] | readonly ["doover", "channel", string, "aggregates", string, "src", string, {
+    readonly fields: string[];
+}];
+export interface UseMultiAgentAggregatesOptions {
+    /** If false, skip per-agent live subscriptions. Defaults true. */
+    liveUpdates?: boolean;
+    /**
+     * Project the response to only the named top-level keys of each aggregate's
+     * `data`. Forwarded as `field_name`. Useful for large aggregates (e.g.
+     * `tag_values`) when you only need a handful of subtrees. Live updates that
+     * arrive via the per-agent subscription are *not* projected — the gateway
+     * pushes whatever it has, so consumers should still tolerate the full shape.
+     */
+    fields?: string[];
+    /**
+     * Restrict to these source ids on a `MultiplexClient`. Ignored for a plain
+     * `DooverClient` or `LocalAgentClient`. When set, the query key is
+     * source-dimensioned so data from different source subsets is cached
+     * independently.
+     */
+    sources?: string[];
+}
+export interface UseMultiAgentAggregatesResult<TData> {
+    /** Keyed by `agent_id` for O(1) lookup. */
+    aggregatesByAgent: Record<string, Aggregate<TData>>;
+    query: UseQueryResult<{
+        results: AgentAggregate<TData>[];
+        count: number;
+    }>;
+}
+/**
+ * Batch-fetch aggregates for a channel across many agents, then keep each
+ * agent's slot live via its own gateway subscription. Reconciles per-agent
+ * `channelSync`/`aggregateUpdate` events into the batched query cache.
+ */
+export declare function useMultiAgentAggregates<TData = Record<string, JSONValue>>(channelName: string, agentIds: string[], options?: UseMultiAgentAggregatesOptions): UseMultiAgentAggregatesResult<TData>;

package/dist/esm/react/useMultiAgentAggregates.js

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useMemo } from "react";
+import { useQuery, useQueryClient, } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+import { channelAggregateQueryKey } from "./useChannelAggregate.js";
+export function multiAgentAggregatesQueryKey(channelName, agentIds, fields, sources) {
+    const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
+    const base = [
+        "doover",
+        "channel",
+        channelName,
+        "aggregates",
+        [...agentIds].sort().join(","),
+        "src",
+        sourceDim,
+    ];
+    return fields && fields.length > 0
+        ? [...base, { fields: [...fields].sort() }]
+        : base;
+}
+/**
+ * Batch-fetch aggregates for a channel across many agents, then keep each
+ * agent's slot live via its own gateway subscription. Reconciles per-agent
+ * `channelSync`/`aggregateUpdate` events into the batched query cache.
+ */
+export function useMultiAgentAggregates(channelName, agentIds, options) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    const liveUpdates = options?.liveUpdates ?? true;
+    const sources = options?.sources;
+    const fields = options?.fields;
+    const key = multiAgentAggregatesQueryKey(channelName, agentIds, fields, sources);
+    const query = useQuery({
+        queryKey: key,
+        enabled: agentIds.length > 0,
+        staleTime: Infinity,
+        queryFn: async () => {
+            const params = {
+                agent_id: agentIds,
+                ...(fields && fields.length > 0 ? { field_name: fields } : {}),
+            };
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `never` since the TypeScript overloads don't declare it.
+            const sourcesArg = sources ? { sources } : undefined;
+            const response = await (sourcesArg
+                ? client.agents.getMultiAgentAggregates(channelName, params, sourcesArg)
+                : client.agents.getMultiAgentAggregates(channelName, params));
+            // Seed the per-agent `channelAggregateQueryKey` cache so that
+            // sibling `useChannelAggregate(id, channelName)` calls for any
+            // of these agents get an instant cache hit rather than issuing
+            // a second fetch for data we already have.
+            for (const result of response.results) {
+                const { agent_id, ...aggregate } = result;
+                queryClient.setQueryData(channelAggregateQueryKey(agent_id, channelName, sources), aggregate);
+            }
+            return response;
+        },
+    });
+    const patchAgentAggregate = useCallback((agentId, aggregate) => {
+        queryClient.setQueryData(key, (current) => {
+            if (!current)
+                return current;
+            const idx = current.results.findIndex((r) => r.agent_id === agentId);
+            const next = {
+                agent_id: agentId,
+                ...aggregate,
+            };
+            const results = idx === -1
+                ? [...current.results, next]
+                : current.results.map((r, i) => (i === idx ? next : r));
+            return { ...current, results };
+        });
+        // Mirror live updates into the per-agent cache so sibling
+        // `useChannelAggregate` consumers see them too.
+        queryClient.setQueryData(channelAggregateQueryKey(agentId, channelName, sources), aggregate);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryClient, channelName, agentIds.join(","), sources?.join(",")]);
+    useEffect(() => {
+        if (!liveUpdates || agentIds.length === 0)
+            return;
+        const offs = agentIds.map((agentId) => {
+            const channel = { agent_id: agentId, name: channelName };
+            return client.gateway.subscribeToChannel(channel, {
+                onAggregate: (agg) => patchAgentAggregate(agentId, agg),
+            });
+        });
+        void client.gateway.connect();
+        return () => {
+            for (const off of offs)
+                off();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, channelName, liveUpdates, agentIds.join(",")]);
+    const aggregatesByAgent = useMemo(() => {
+        const map = {};
+        for (const entry of query.data?.results ?? []) {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { agent_id, ...aggregate } = entry;
+            map[agent_id] = aggregate;
+        }
+        return map;
+    }, [query.data]);
+    return { aggregatesByAgent, query };
+}

package/dist/esm/react/useMultiAgentChannelMessages.d.ts

@@ -0,0 +1,79 @@
+import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-query";
+import type { MessageStructure } from "../types/common.js";
+export declare function multiAgentChannelMessagesQueryKey(channelName: string, agentIds: string[], sources?: string[], scope?: {
+    after?: string;
+    fields?: readonly string[];
+}): readonly ["doover", "channel", string, "messages", string, "src", string] | readonly ["doover", "channel", string, "messages", string, "src", string, Record<string, unknown>];
+export interface UseMultiAgentChannelMessagesOptions {
+    /**
+     * Global cap on the total number of messages returned across all agents
+     * for a single request. The server distributes this budget across agents
+     * in newest-first order, so a noisy agent can starve quieter ones.
+     * Prefer `agentMessageLimit` when you want a fair per-agent slice.
+     */
+    limit?: number;
+    /**
+     * Per-agent cap on messages returned. Forwarded as `agent_message_limit`.
+     * Use this when fanning out across many agents that have wildly different
+     * message rates and you want each agent's window represented.
+     */
+    agentMessageLimit?: number;
+    /** If false, skip live subscriptions per agent. Defaults true. */
+    liveUpdates?: boolean;
+    /**
+     * Restrict the returned messages to those whose payload contains any
+     * of these top-level field names. Forwarded as `field_name`.
+     */
+    fields?: string[];
+    /** Optional first-page `before` cursor (snowflake id). */
+    initialBefore?: string;
+    /**
+     * Keep paging older automatically until `hasNextPage` is false. Each page
+     * resumes only the agents that hit `agentMessageLimit`, using their own
+     * cursors, so a noisy agent doesn't drag the quiet ones back through
+     * messages they've already returned. Almost always combined with `after`
+     * — without a lower bound this walks every agent's channel back to its
+     * first message. `maxPages` caps the walk.
+     */
+    autoPaginate?: boolean;
+    /**
+     * Hard cap on pages fetched when `autoPaginate` is set. Defaults to 20.
+     * Guards against a window that's wider than `agentMessageLimit × maxPages`
+     * messages turning into an unbounded fetch loop.
+     */
+    maxPages?: number;
+    /**
+     * Optional lower-bound snowflake id. Forwarded server-side so each
+     * agent's pagination stops on its own once it walks past the bound —
+     * mirrors `useChannelMessages`'s `after`. Use this to fetch a bounded
+     * time window (e.g. last 24h) across many agents without filtering
+     * on the client.
+     */
+    after?: string;
+    /**
+     * Restrict to these source ids on a `MultiplexClient`. Ignored for a plain
+     * `DooverClient` or `LocalAgentClient`. When set, the query key is
+     * source-dimensioned so data from different source subsets is cached
+     * independently.
+     */
+    sources?: string[];
+}
+interface Page<TData> {
+    results: MessageStructure<TData>[];
+    /**
+     * Per-agent resume cursors, keyed by agent id. Present (and non-empty)
+     * only for agents that hit the per-agent limit before draining the
+     * window. This is the canonical "there is more" signal.
+     */
+    next_cursors?: Record<string, string>;
+    /** Legacy single-cursor signal, for servers predating `next_cursors`. */
+    next?: string | null;
+    /** Legacy: agent ids that may have more older messages. */
+    at_limit_agent_ids?: string[];
+}
+export interface UseMultiAgentChannelMessagesResult<TData> extends Omit<UseInfiniteQueryResult<InfiniteData<Page<TData>>>, "data"> {
+    messages: MessageStructure<TData>[];
+    data: InfiniteData<Page<TData>> | undefined;
+}
+export declare function useMultiAgentChannelMessages<TData = unknown>(channelName: string, agentIds: string[], options?: UseMultiAgentChannelMessagesOptions): UseMultiAgentChannelMessagesResult<TData>;
+export {};