doover-js 0.6.0 → 0.6.2

package/dist/apis/agents-api.d.ts

@@ -32,6 +32,14 @@ export declare class AgentsApi {
     private readonly controlApiUrl?;
     constructor(rest: RestClient, controlApiUrl?: string | undefined);
     listAgents(options?: GetAgentsOptions): Promise<AgentsResponse>;
+    /**
+     * Batch-fetch recent messages for many agents. Auto-chunks `agent_id`
+     * (and the parallel `agent_before` cursors, if given) at MULTI_AGENT_CHUNK_SIZE
+     * so each request's URL stays under CloudFront's 8,192-byte quota. Chunks
+     * are fetched in parallel and merged: `results`/`count` concat-and-sum,
+     * `next_cursors`/`at_limit_agent_ids` union, legacy `next` becomes the
+     * lexically-highest cursor across at-limit agents.
+     */
     getMultiAgentMessages(channelName: string, params: MultiAgentMessagesParams): Promise<BatchMessagesResponse>;
     /**
      * Batch-fetch aggregates for many agents. Auto-chunks `agent_id` so each

package/dist/apis/agents-api.js

@@ -144,12 +144,65 @@ class AgentsApi {
         }
         return { ...raw, agents: merged, results: merged, count: merged.length };
     }
+    /**
+     * Batch-fetch recent messages for many agents. Auto-chunks `agent_id`
+     * (and the parallel `agent_before` cursors, if given) at MULTI_AGENT_CHUNK_SIZE
+     * so each request's URL stays under CloudFront's 8,192-byte quota. Chunks
+     * are fetched in parallel and merged: `results`/`count` concat-and-sum,
+     * `next_cursors`/`at_limit_agent_ids` union, legacy `next` becomes the
+     * lexically-highest cursor across at-limit agents.
+     */
     async getMultiAgentMessages(channelName, params) {
-        const response = await this.rest.get(`/agents/channels/${channelName}/messages`, params);
-        return {
+        const path = `/agents/channels/${channelName}/messages`;
+        const { agent_id, agent_before, ...rest } = params;
+        const stampTimestamps = (response) => ({
             ...response,
             results: response.results.map((message) => "timestamp" in message ? message : (0, snowflake_1.addTimestampToMessage)(message)),
+        });
+        if (agent_id.length <= MULTI_AGENT_CHUNK_SIZE) {
+            const response = await this.rest.get(path, params);
+            return stampTimestamps(response);
+        }
+        if (agent_before && agent_before.length !== agent_id.length) {
+            throw new Error("agent_before must be the same length as agent_id when set");
+        }
+        const chunks = [];
+        for (let i = 0; i < agent_id.length; i += MULTI_AGENT_CHUNK_SIZE) {
+            chunks.push({
+                agent_id: agent_id.slice(i, i + MULTI_AGENT_CHUNK_SIZE),
+                ...(agent_before
+                    ? { agent_before: agent_before.slice(i, i + MULTI_AGENT_CHUNK_SIZE) }
+                    : {}),
+            });
+        }
+        const responses = await Promise.all(chunks.map((chunk) => this.rest
+            .get(path, { ...rest, ...chunk })
+            .then(stampTimestamps)));
+        // Merge: results/count concat-and-sum; next_cursors merge; at_limit_agent_ids
+        // concat (both keyed by agent id, unique across chunks). Legacy `next` is the
+        // lexically-highest oldest-cursor across at-limit agents — snowflakes sort
+        // lexically since they're equal-width digit strings.
+        const merged = {
+            results: responses.flatMap((r) => r.results),
+            count: responses.reduce((acc, r) => acc + r.count, 0),
         };
+        const nexts = responses
+            .map((r) => r.next)
+            .filter((n) => typeof n === "string" && n.length > 0);
+        if (nexts.length > 0) {
+            merged.next = nexts.reduce((a, b) => (a > b ? a : b));
+        }
+        const cursors = {};
+        for (const r of responses) {
+            if (r.next_cursors)
+                Object.assign(cursors, r.next_cursors);
+        }
+        if (Object.keys(cursors).length > 0)
+            merged.next_cursors = cursors;
+        const atLimit = responses.flatMap((r) => r.at_limit_agent_ids ?? []);
+        if (atLimit.length > 0)
+            merged.at_limit_agent_ids = atLimit;
+        return merged;
     }
     /**
      * Batch-fetch aggregates for many agents. Auto-chunks `agent_id` so each

package/dist/index.d.ts

@@ -47,4 +47,6 @@ export type * from "./types/common";
 export type * from "./types/connection";
 export type * from "./types/openapi";
 export type * from "./types/viewer";
+export type * from "./types/audit";
+export { DV_AUDIT_CHANNEL } from "./types/audit";
 export { addTimestampToMessage, extractSnowflakeId, generateSnowflakeIdAtTime, } from "./utils/snowflake";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = exports.ALL_CAPABILITIES = exports.DooverRpcError = exports.RpcDispatcher = exports.UsersApi = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.MultiplexClient = exports.LocalAgentClient = exports.DooverClient = void 0;
+exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.DV_AUDIT_CHANNEL = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = exports.ALL_CAPABILITIES = exports.DooverRpcError = exports.RpcDispatcher = exports.UsersApi = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.MultiplexClient = exports.LocalAgentClient = exports.DooverClient = void 0;
 var doover_client_1 = require("./client/doover-client");
 Object.defineProperty(exports, "DooverClient", { enumerable: true, get: function () { return doover_client_1.DooverClient; } });
 var local_agent_client_1 = require("./client/local-agent-client");
@@ -68,6 +68,8 @@ var doover_data_provider_1 = require("./viewer/doover-data-provider");
 Object.defineProperty(exports, "DooverDataProvider", { enumerable: true, get: function () { return doover_data_provider_1.DooverDataProvider; } });
 var path_parsing_1 = require("./viewer/path-parsing");
 Object.defineProperty(exports, "getIdentifierFromPath", { enumerable: true, get: function () { return path_parsing_1.getIdentifierFromPath; } });
+var audit_1 = require("./types/audit");
+Object.defineProperty(exports, "DV_AUDIT_CHANNEL", { enumerable: true, get: function () { return audit_1.DV_AUDIT_CHANNEL; } });
 var snowflake_1 = require("./utils/snowflake");
 Object.defineProperty(exports, "addTimestampToMessage", { enumerable: true, get: function () { return snowflake_1.addTimestampToMessage; } });
 Object.defineProperty(exports, "extractSnowflakeId", { enumerable: true, get: function () { return snowflake_1.extractSnowflakeId; } });

package/dist/react/useMultiAgentChannelMessages.d.ts

@@ -1,8 +1,23 @@
 import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-query";
 import type { MessageStructure } from "../types/common";
-export declare function multiAgentChannelMessagesQueryKey(channelName: string, agentIds: string[], sources?: string[]): readonly ["doover", "channel", string, "messages", string, "src", string];
+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;
     /**
@@ -12,6 +27,14 @@ export interface UseMultiAgentChannelMessagesOptions {
     fields?: string[];
     /** Optional first-page `before` cursor (snowflake id). */
     initialBefore?: string;
+    /**
+     * 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

package/dist/react/useMultiAgentChannelMessages.js

@@ -5,9 +5,9 @@ exports.useMultiAgentChannelMessages = useMultiAgentChannelMessages;
 const react_1 = require("react");
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("./context");
-function multiAgentChannelMessagesQueryKey(channelName, agentIds, sources) {
+function multiAgentChannelMessagesQueryKey(channelName, agentIds, sources, scope) {
     const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
-    return [
+    const base = [
         "doover",
         "channel",
         channelName,
@@ -16,16 +16,34 @@ function multiAgentChannelMessagesQueryKey(channelName, agentIds, sources) {
         "src",
         sourceDim,
     ];
+    // Pagination cursors come from the first page's response and are scoped
+    // to *that* response's `after`/`fields`. Mixing them under one cache
+    // entry would cause `getNextPageParam` to anchor on an unrelated page,
+    // so a differently-bounded request must live under its own key.
+    const scopeKey = {};
+    if (scope?.after)
+        scopeKey.after = scope.after;
+    if (scope?.fields && scope.fields.length > 0) {
+        scopeKey.fields = [...scope.fields].sort();
+    }
+    return Object.keys(scopeKey).length > 0
+        ? [...base, scopeKey]
+        : base;
 }
 function useMultiAgentChannelMessages(channelName, agentIds, options) {
     const client = (0, context_1.useDooverClient)();
     const queryClient = (0, react_query_1.useQueryClient)();
     const limit = options?.limit;
+    const agentMessageLimit = options?.agentMessageLimit;
     const liveUpdates = options?.liveUpdates ?? true;
     const fields = options?.fields;
     const initialBefore = options?.initialBefore;
     const sources = options?.sources;
-    const key = multiAgentChannelMessagesQueryKey(channelName, agentIds, sources);
+    const after = options?.after;
+    const key = multiAgentChannelMessagesQueryKey(channelName, agentIds, sources, {
+        after,
+        fields,
+    });
     const prependMessage = (0, react_1.useCallback)((message) => {
         queryClient.setQueryData(key, (current) => {
             if (!current)
@@ -42,8 +60,12 @@ function useMultiAgentChannelMessages(channelName, agentIds, options) {
             };
         });
     }, 
+    // `key` captures every scope dim (agentIds + sources + after + fields);
+    // serialise the whole thing so the closure refreshes when any dim
+    // changes — listing dims by hand drops live updates whenever the list
+    // grows (we used to omit `after`/`fields`).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [queryClient, channelName, agentIds.join(","), sources?.join(",")]);
+    [queryClient, JSON.stringify(key)]);
     (0, react_1.useEffect)(() => {
         if (!liveUpdates || agentIds.length === 0)
             return;
@@ -71,7 +93,11 @@ function useMultiAgentChannelMessages(channelName, agentIds, options) {
                 agent_id: agentIds,
                 ...(typeof pageParam === "string" ? { before: pageParam } : {}),
                 ...(limit !== undefined ? { limit } : {}),
+                ...(agentMessageLimit !== undefined
+                    ? { agent_message_limit: agentMessageLimit }
+                    : {}),
                 ...(fields && fields.length > 0 ? { field_name: fields } : {}),
+                ...(after !== undefined ? { after } : {}),
             };
             // Pass `{ sources }` as a trailing bag only when set — cast through
             // `never` since the TypeScript overloads don't declare it.

package/dist/test/apis.test.js

@@ -82,6 +82,82 @@ function setupRest(responseFactory) {
         const returnedIds = aggregates.results.map((r) => r.agent_id).sort();
         (0, chai_1.expect)(returnedIds).to.deep.equal([...agentIds].sort());
     });
+    (0, mocha_1.it)("chunks getMultiAgentMessages over the per-request agent cap", async () => {
+        const baseTs = new Date("2026-01-01T00:00:00Z");
+        const { rest, fetchMock } = setupRest((url) => {
+            const ids = [...new URL(url).searchParams.getAll("agent_id")];
+            return (0, helpers_1.createJsonResponse)({
+                results: ids.map((id, i) => ({
+                    id: (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(baseTs.getTime() + i)),
+                    author_id: "u",
+                    channel: { agent_id: id, name: "c1" },
+                    data: {},
+                    attachments: [],
+                })),
+                count: ids.length,
+            });
+        });
+        const api = new agents_api_1.AgentsApi(rest);
+        // 600 agents → 3 chunks of 250/250/100.
+        const agentIds = Array.from({ length: 600 }, (_, i) => `a${i}`);
+        const messages = await api.getMultiAgentMessages("c1", {
+            agent_id: agentIds,
+            agent_message_limit: 50,
+        });
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(3);
+        (0, chai_1.expect)(messages.results).to.have.length(600);
+        (0, chai_1.expect)(messages.count).to.equal(600);
+        const returnedIds = messages.results
+            .map((m) => m.channel.agent_id)
+            .sort();
+        (0, chai_1.expect)(returnedIds).to.deep.equal([...agentIds].sort());
+        // Per-request param survives chunking.
+        for (let i = 0; i < 3; i++) {
+            const url = fetchMock.getCall(i).args[0];
+            (0, chai_1.expect)(url).to.include("agent_message_limit=50");
+        }
+    });
+    (0, mocha_1.it)("merges next_cursors and at_limit_agent_ids across chunks", async () => {
+        let call = 0;
+        const cursors = [
+            { "a0": "100", "a1": "200" },
+            { "a250": "150" },
+        ];
+        const atLimit = [["a0", "a1"], ["a250"]];
+        const { rest } = setupRest((url) => {
+            const idx = call++;
+            const ids = [...new URL(url).searchParams.getAll("agent_id")];
+            return (0, helpers_1.createJsonResponse)({
+                results: ids.map((id) => ({
+                    id: (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00Z")),
+                    author_id: "u",
+                    channel: { agent_id: id, name: "c1" },
+                    data: {},
+                    attachments: [],
+                })),
+                count: ids.length,
+                next: idx === 0 ? "200" : "150",
+                next_cursors: cursors[idx],
+                at_limit_agent_ids: atLimit[idx],
+            });
+        });
+        const api = new agents_api_1.AgentsApi(rest);
+        const agentIds = Array.from({ length: 300 }, (_, i) => `a${i}`);
+        const messages = await api.getMultiAgentMessages("c1", {
+            agent_id: agentIds,
+        });
+        (0, chai_1.expect)(messages.next).to.equal("200"); // max across chunks
+        (0, chai_1.expect)(messages.next_cursors).to.deep.equal({
+            a0: "100",
+            a1: "200",
+            a250: "150",
+        });
+        (0, chai_1.expect)(messages.at_limit_agent_ids?.sort()).to.deep.equal([
+            "a0",
+            "a1",
+            "a250",
+        ]);
+    });
     (0, mocha_1.it)("covers channels methods", async () => {
         const { rest, fetchMock } = setupRest(() => (0, helpers_1.createJsonResponse)([]));
         const api = new channels_api_1.ChannelsApi(rest);

package/dist/types/audit.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Audit event types — mirror of the records doover-control writes to the
+ * `dv-audit` channel (see ``doover-control/doover_control/events/audit.py``
+ * for the source of truth).
+ *
+ * Each record is read back via the standard channel-messages APIs: it lands
+ * inside a ``MessageStructure<AuditEvent>`` envelope (with ``id``, ``timestamp``,
+ * ``channel``, etc.), and the record itself is on ``message.data``.
+ */
+/** Channel name on which audit records live in doover-data. */
+export declare const DV_AUDIT_CHANNEL = "dv-audit";
+/** The role this party plays in the record. */
+export type AuditEntityType = "device" | "user" | "organisation" | "Tunnel" | "ApplicationInstallation" | "SolutionInstallation" | "ApplicationDeployment" | "ObjectGroup" | "PendingUser" | "User" | "fusionauth" | "system";
+export interface AuditEntity {
+    type: AuditEntityType;
+    /** Stringified id (User pk, Device pk, FA UUID, etc.). May be absent for `system`. */
+    id?: string;
+    /** Display name. May be an email for users / pending invites. */
+    name?: string;
+}
+export interface AuditOrganisation {
+    id: string;
+    name: string;
+}
+export interface AuditRequestContext {
+    ip_address?: string;
+    user_agent?: string;
+}
+/** Origin system for the event. */
+export type AuditSource = "control" | "auth" | "data" | "tunnels";
+/**
+ * String-literal union of every wired audit action — kept in lock-step with
+ * ``doover_control/events/types.py``'s ``EventType`` enum. Future event types
+ * declared in Python but not yet emitted are intentionally included so the
+ * frontend mapping (icons, labels) can be filled in ahead of the wire-up.
+ */
+export type AuditAction = "user.logged_in" | "user.login.failed" | "user.signed_up" | "user.created" | "user.updated" | "user.deleted" | "user.deactivated" | "user.reactivated" | "user.password_changed" | "user.password_reset" | "user.password_breached" | "user.mfa_changed" | "user.email_verified" | "user.email_changed" | "user.idp_linked" | "user.idp_unlinked" | "user.token_revoked" | "user.invited" | "user.removed" | "user.role_changed" | "app.installed" | "app.deployed" | "app.config_changed" | "app.uninstalled" | "solution.config_changed" | "group.created" | "group.edited" | "group.deleted" | "device.created" | "device.updated" | "device.config_changed" | "device.archived" | "device.unarchived" | "device.deleted" | "device.opened" | "tunnel.created" | "tunnel.deleted" | "tunnel.opened" | "tunnel.closed" | "tunnel.accessed" | "notification.sent" | "report.created" | "command.received";
+/**
+ * The audit record payload as written by ``publish_audit`` — i.e. what you
+ * find on ``MessageStructure<AuditEvent>.data`` after reading the channel.
+ *
+ * The doover-data ``MessageStructure`` envelope provides ``id`` (snowflake)
+ * and ``timestamp`` (epoch ms) for ordering; this struct is the body only.
+ */
+export interface AuditEvent {
+    action: AuditAction;
+    actor: AuditEntity | null;
+    subject: AuditEntity | null;
+    organisation: AuditOrganisation | null;
+    source: AuditSource;
+    metadata: Record<string, unknown>;
+    request_context: AuditRequestContext | null;
+}

package/dist/types/audit.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Audit event types — mirror of the records doover-control writes to the
+ * `dv-audit` channel (see ``doover-control/doover_control/events/audit.py``
+ * for the source of truth).
+ *
+ * Each record is read back via the standard channel-messages APIs: it lands
+ * inside a ``MessageStructure<AuditEvent>`` envelope (with ``id``, ``timestamp``,
+ * ``channel``, etc.), and the record itself is on ``message.data``.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DV_AUDIT_CHANNEL = void 0;
+/** Channel name on which audit records live in doover-data. */
+exports.DV_AUDIT_CHANNEL = "dv-audit";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",