doover-js 0.5.1 → 0.5.3

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

@@ -2,6 +2,15 @@ import type { AgentAggregate, BatchMessagesResponse } from "../types/openapi";
 import type { RestClient } from "../http/rest-client";
 export interface MultiAgentMessagesParams {
     agent_id: string[];
+    /**
+     * Per-agent `before` cursors, parallel to `agent_id`. When set, must
+     * be the same length as `agent_id`; each agent then uses its own
+     * cursor as the upper bound instead of the global `before`. This is
+     * how paginating clients should resume from a previous response's
+     * `next_cursors` map — each agent paginates independently with no
+     * inter-agent "watermark retain".
+     */
+    agent_before?: string[];
     before?: string;
     after?: string;
     limit?: number;
@@ -21,6 +30,14 @@ export declare class AgentsApi {
     private readonly rest;
     constructor(rest: RestClient);
     getMultiAgentMessages(channelName: string, params: MultiAgentMessagesParams): Promise<BatchMessagesResponse>;
+    /**
+     * Batch-fetch aggregates for many agents. Auto-chunks `agent_id` so each
+     * request's URL stays under CloudFront's hard 8,192-byte URL quota — each
+     * agent contributes ~30 chars (`agent_id=<snowflake>&`), so the chunk size
+     * below caps the query string at ~7.5KB even before the base URL. Chunks
+     * are fetched in parallel and merged into one `{ results, count }` so
+     * callers never have to think about the limit.
+     */
     getMultiAgentAggregates(channelName: string, params: MultiAgentAggregatesParams): Promise<{
         results: AgentAggregate[];
         count: number;

package/dist/apis/agents-api.js

@@ -13,8 +13,37 @@ class AgentsApi {
             results: response.results.map((message) => "timestamp" in message ? message : (0, snowflake_1.addTimestampToMessage)(message)),
         };
     }
-    getMultiAgentAggregates(channelName, params) {
-        return this.rest.get(`/agents/channels/${channelName}/aggregates`, params);
+    /**
+     * Batch-fetch aggregates for many agents. Auto-chunks `agent_id` so each
+     * request's URL stays under CloudFront's hard 8,192-byte URL quota — each
+     * agent contributes ~30 chars (`agent_id=<snowflake>&`), so the chunk size
+     * below caps the query string at ~7.5KB even before the base URL. Chunks
+     * are fetched in parallel and merged into one `{ results, count }` so
+     * callers never have to think about the limit.
+     */
+    async getMultiAgentAggregates(channelName, params) {
+        const path = `/agents/channels/${channelName}/aggregates`;
+        const { agent_id, ...rest } = params;
+        if (agent_id.length <= MULTI_AGENT_CHUNK_SIZE) {
+            return this.rest.get(path, params);
+        }
+        const chunks = [];
+        for (let i = 0; i < agent_id.length; i += MULTI_AGENT_CHUNK_SIZE) {
+            chunks.push(agent_id.slice(i, i + MULTI_AGENT_CHUNK_SIZE));
+        }
+        const responses = await Promise.all(chunks.map((chunk) => this.rest.get(path, {
+            ...rest,
+            agent_id: chunk,
+        })));
+        return {
+            results: responses.flatMap((r) => r.results),
+            count: responses.reduce((acc, r) => acc + r.count, 0),
+        };
     }
 }
 exports.AgentsApi = AgentsApi;
+// CloudFront fronts the channels-rest API with a hard 8,192-byte URL quota.
+// Each agent adds ~30 chars (`agent_id=<19-digit snowflake>&`), so 250 IDs
+// is ~7.5KB of query string — comfortably under the cap with room for the
+// base URL and any `field_name` params.
+const MULTI_AGENT_CHUNK_SIZE = 250;

package/dist/react/useChannelAggregate.d.ts

@@ -16,7 +16,12 @@ export interface UseChannelAggregateResult<TData> extends Omit<UseQueryResult<Ag
     data: TData | undefined;
     /** Attachments (files/blobs) on the aggregate. */
     attachments: Aggregate["attachments"] | undefined;
-    /** Server timestamp (epoch seconds) of the last aggregate update. */
+    /**
+     * Server timestamp (epoch **milliseconds**) of the last aggregate update —
+     * matches the `Date` / `dayjs()` constructor. Use `dayjs(last_updated)`, not
+     * `dayjs.unix(last_updated)` (the latter assumes seconds and lands ~58000
+     * years in the future).
+     */
     last_updated: number | null | undefined;
 }
 export interface UseChannelAggregateOptions {

package/dist/test/apis.test.js

@@ -61,6 +61,27 @@ function setupRest(responseFactory) {
         (0, chai_1.expect)(fetchMock.getCall(0).args[0]).to.equal("https://api.example.com/agents/channels/c1/messages?agent_id=a1&agent_id=a2&limit=5");
         (0, chai_1.expect)(fetchMock.getCall(1).args[0]).to.equal("https://api.example.com/agents/channels/c1/aggregates?agent_id=a1");
     });
+    (0, mocha_1.it)("chunks getMultiAgentAggregates over the per-request agent cap", async () => {
+        const { rest, fetchMock } = setupRest((url) => {
+            const ids = [...new URL(url).searchParams.getAll("agent_id")];
+            return (0, helpers_1.createJsonResponse)({
+                results: ids.map((id) => ({ agent_id: id, 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 aggregates = await api.getMultiAgentAggregates("c1", {
+            agent_id: agentIds,
+        });
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(3);
+        (0, chai_1.expect)(aggregates.results).to.have.length(600);
+        (0, chai_1.expect)(aggregates.count).to.equal(600);
+        // Every agent is represented exactly once across the merged chunks.
+        const returnedIds = aggregates.results.map((r) => r.agent_id).sort();
+        (0, chai_1.expect)(returnedIds).to.deep.equal([...agentIds].sort());
+    });
     (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/openapi.d.ts

@@ -4,16 +4,28 @@ export interface BatchMessagesResponse {
     results: MessageStructure[];
     count: number;
     /**
-     * Snowflake cursor for the next sub-page — non-null means at least one
-     * agent returned a full `agent_message_limit` worth and may have more
-     * older messages within the window. Re-request with `before=<next>`.
+     * Per-agent resume cursors. Any agent whose fetch hit the per-agent
+     * limit before draining the window maps to the oldest snowflake we
+     * did return for it. Pass these back as `agent_before` (parallel to
+     * `agent_id`) on the next call to continue paginating each agent
+     * independently. Empty (or missing, on older servers) when the
+     * window is fully drained.
+     *
+     * This is the canonical pagination signal — `next` and
+     * `at_limit_agent_ids` are kept populated for back-compat with
+     * pre-`next_cursors` clients.
+     */
+    next_cursors?: Record<string, string>;
+    /**
+     * Legacy single-cursor pagination signal — the most-recent (highest
+     * snowflake id) oldest-cursor across at-limit agents. Clients
+     * paginating with a single global `before` should pass this back;
+     * prefer `next_cursors` + `agent_before` for new code.
      */
     next?: string | null;
     /**
-     * Agent ids that returned a full `agent_message_limit` worth in this
-     * response — those that may have more older messages within the window.
-     * Pass these (and only these) as `agent_id` on the next sub-page so the
-     * server doesn't repeat DDB lookups for already-exhausted agents.
+     * Legacy: agent ids with possibly-more older messages — equivalent to
+     * `Object.keys(next_cursors)`. Prefer `next_cursors` for new code.
      */
     at_limit_agent_ids?: string[];
 }

package/package.json

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