doover-js 0.7.0 → 0.8.0

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

@@ -1,6 +1,7 @@
 import type { RestClient } from "../http/rest-client";
 import type { Aggregate } from "../types/openapi";
 import type { DooverRequestOptions } from "../client/request-options";
+import { type BatchAggregateResponse, type BatchAggregateUpdateItem } from "../types/batch";
 export interface AggregateMutationParams {
     suppress_response?: boolean;
     clear_attachments?: boolean;
@@ -9,6 +10,26 @@ export interface AggregateMutationParams {
 export declare class AggregatesApi {
     private readonly rest;
     constructor(rest: RestClient);
+    /**
+     * Merge-patch aggregates across many agents and channels in one request.
+     *
+     * Replaces N single-agent PATCHes with one round trip, which is the point:
+     * it removes the per-request HTTP, auth, routing and tracing overhead, and
+     * shrinks synchronised write bursts. It does *not* reduce DynamoDB writes —
+     * the server still issues one `UpdateItem` per aggregate, capped at four
+     * concurrently — so callers should still coalesce on the client rather than
+     * relying on this to absorb a storm.
+     *
+     * Batches over {@link MAX_BATCH_ITEMS} are split automatically and the
+     * responses merged, so a caller can pass an arbitrarily long list. An empty
+     * list resolves to an empty response without issuing a request.
+     *
+     * Partial success is normal: inspect `items` and retry only the entries
+     * whose `success` is false. Successful entries are never rolled back.
+     */
+    batchPatchAggregates(items: BatchAggregateUpdateItem[]): Promise<BatchAggregateResponse>;
+    batchPatchAggregates(items: BatchAggregateUpdateItem[], requestOptions: DooverRequestOptions): Promise<BatchAggregateResponse>;
+    private _batchPatchAggregates;
     getAggregate(agentId: string, channelName: string): Promise<Aggregate>;
     getAggregate(agentId: string, channelName: string, requestOptions: DooverRequestOptions): Promise<Aggregate>;
     getAggregate(identifier: {

package/dist/apis/aggregates-api.js

@@ -2,10 +2,28 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AggregatesApi = void 0;
 const _args_1 = require("./_args");
+const batch_1 = require("../types/batch");
 class AggregatesApi {
     constructor(rest) {
         this.rest = rest;
     }
+    batchPatchAggregates(...args) {
+        return this._batchPatchAggregates(args[0]);
+    }
+    async _batchPatchAggregates(items) {
+        if (items.length === 0) {
+            return { items: [], count: 0, succeeded: 0, failed: 0 };
+        }
+        const responses = [];
+        // Sequential: the point of batching is to stop hammering the write path,
+        // so firing every chunk at once would defeat it.
+        for (const chunk of (0, batch_1.chunkBatchItems)(items)) {
+            responses.push(await this.rest.patch("/agents/aggregates", {
+                items: chunk,
+            }));
+        }
+        return (0, batch_1.mergeBatchResponses)(responses);
+    }
     getAggregate(...args) {
         const { agentId, channelName } = (0, _args_1.resolveChannelArgs)(args);
         return this._getAggregate(agentId, channelName);

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

@@ -1,8 +1,16 @@
 import type { RestClient } from "../http/rest-client";
 import type { CreateMessageRequest, DataSeries, MessageStructure, UpdateMessageRequest } from "../types/openapi";
 import type { DooverRequestOptions } from "../client/request-options";
+import { type BatchCreateMessageItem, type BatchDeleteMessageItem, type BatchMessageResponse, type BatchUpdateMessageItem } from "../types/batch";
 export interface ListMessagesParams {
     before?: string;
+    /**
+     * Lower-bound cursor (exclusive). With `before` set (or defaulted) it merely
+     * floors the window. On its own — `after` set, `before` omitted — it pages
+     * *forward*: the server returns the `limit` **oldest** messages strictly
+     * newer than the cursor, oldest-first. This is the only way to walk history
+     * upward toward "now".
+     */
     after?: string;
     limit?: number;
     field_name?: string[];
@@ -86,5 +94,35 @@ export declare class MessagesApi {
         channelName: string;
     }, messageId: string): Promise<TLog[]>;
     private _getInvocationLogs;
+    /**
+     * Create messages across many agents and channels in one request.
+     *
+     * Supply `message_id` per item where you can: the server's create path is
+     * not yet idempotent, so a retry after a lost response can otherwise
+     * duplicate the message and double-count the daily summary.
+     */
+    batchPostMessages(items: BatchCreateMessageItem[]): Promise<BatchMessageResponse>;
+    batchPostMessages(items: BatchCreateMessageItem[], requestOptions: DooverRequestOptions): Promise<BatchMessageResponse>;
+    /** Merge-patch messages across many agents and channels in one request. */
+    batchPatchMessages(items: BatchUpdateMessageItem[]): Promise<BatchMessageResponse>;
+    batchPatchMessages(items: BatchUpdateMessageItem[], requestOptions: DooverRequestOptions): Promise<BatchMessageResponse>;
+    /** Replace messages across many agents and channels in one request. */
+    batchPutMessages(items: BatchUpdateMessageItem[]): Promise<BatchMessageResponse>;
+    batchPutMessages(items: BatchUpdateMessageItem[], requestOptions: DooverRequestOptions): Promise<BatchMessageResponse>;
+    /**
+     * Delete messages across many agents and channels in one request.
+     *
+     * Deletion is not idempotent server-side yet — a retried delete can
+     * decrement the daily summary twice — so retry only items the response
+     * reported as failed.
+     */
+    batchDeleteMessages(items: BatchDeleteMessageItem[]): Promise<BatchMessageResponse>;
+    batchDeleteMessages(items: BatchDeleteMessageItem[], requestOptions: DooverRequestOptions): Promise<BatchMessageResponse>;
+    /**
+     * Shared driver for the four `/agents/messages` verbs. Chunks to the
+     * server's item ceiling and sends sequentially, so a long list doesn't
+     * reintroduce the burst that batching exists to remove.
+     */
+    private _batchMessages;
     createMultipartPayload(jsonPayload: Record<string, unknown>, attachments: Array<Blob | File>): FormData;
 }

package/dist/apis/messages-api.js

@@ -3,17 +3,34 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessagesApi = void 0;
 const snowflake_1 = require("../utils/snowflake");
 const _args_1 = require("./_args");
+const batch_1 = require("../types/batch");
 function resolveListMessagesParams(params) {
     const order = params?.order ?? "desc";
+    const hasAfter = params?.after !== undefined;
+    const hasBefore = params?.before !== undefined;
+    // The server keys pagination on whichever bound is sent: `before` walks
+    // newest-first downward, `after` alone walks oldest-first upward (the N
+    // oldest messages strictly newer than the cursor). Sending `after` without
+    // `before` is the only way to page forward; sending both, or neither, keeps
+    // the newest-first behaviour (defaulting `before` to "now" when unbounded).
+    if (hasAfter && !hasBefore) {
+        const query = {
+            after: params.after,
+            limit: params?.limit ?? 10,
+        };
+        if (params?.field_name !== undefined)
+            query.field_name = params.field_name;
+        return { query, order, serverAscending: true };
+    }
     const query = {
         before: params?.before ?? (0, snowflake_1.generateSnowflakeIdAtTime)(new Date()),
         limit: params?.limit ?? 10,
     };
-    if (params?.after !== undefined)
+    if (hasAfter)
         query.after = params.after;
     if (params?.field_name !== undefined)
         query.field_name = params.field_name;
-    return { query, order };
+    return { query, order, serverAscending: false };
 }
 class MessagesApi {
     constructor(rest) {
@@ -24,10 +41,13 @@ class MessagesApi {
         return this._listMessages(agentId, channelName, options);
     }
     async _listMessages(agentId, channelName, params) {
-        const { query, order } = resolveListMessagesParams(params);
+        const { query, order, serverAscending } = resolveListMessagesParams(params);
         const response = await this.rest.get(`/agents/${agentId}/channels/${channelName}/messages`, query);
         const stamped = response.map(snowflake_1.addTimestampToMessage);
-        return order === "asc" ? [...stamped].reverse() : stamped;
+        // The server returns newest-first for `before` and oldest-first for a bare
+        // `after`; reverse only when that native order differs from what was asked.
+        const wantAscending = order === "asc";
+        return serverAscending === wantAscending ? stamped : [...stamped].reverse();
     }
     async postMessage(...args) {
         if (typeof args[0] === "string") {
@@ -118,6 +138,39 @@ class MessagesApi {
     _getInvocationLogs(agentId, channelName, messageId) {
         return this.rest.get(`/agents/${agentId}/channels/${channelName}/messages/${messageId}/logs`);
     }
+    batchPostMessages(...args) {
+        return this._batchMessages("POST", args[0]);
+    }
+    batchPatchMessages(...args) {
+        return this._batchMessages("PATCH", args[0]);
+    }
+    batchPutMessages(...args) {
+        return this._batchMessages("PUT", args[0]);
+    }
+    batchDeleteMessages(...args) {
+        return this._batchMessages("DELETE", args[0]);
+    }
+    /**
+     * Shared driver for the four `/agents/messages` verbs. Chunks to the
+     * server's item ceiling and sends sequentially, so a long list doesn't
+     * reintroduce the burst that batching exists to remove.
+     */
+    async _batchMessages(method, items) {
+        if (items.length === 0) {
+            return { items: [], count: 0, succeeded: 0, failed: 0 };
+        }
+        const responses = [];
+        for (const chunk of (0, batch_1.chunkBatchItems)(items)) {
+            // Goes through `request` rather than the verb helpers because DELETE
+            // needs a body, which `rest.delete` does not accept.
+            responses.push(await this.rest.request({
+                path: "/agents/messages",
+                method,
+                body: { items: chunk },
+            }));
+        }
+        return (0, batch_1.mergeBatchResponses)(responses);
+    }
     createMultipartPayload(jsonPayload, attachments) {
         const formData = new FormData();
         formData.set("json_payload", JSON.stringify(jsonPayload));

package/dist/client/multiplex-client.d.ts

@@ -97,6 +97,20 @@ export declare class MultiplexClient implements DataClient {
     private isNotFound;
     private requiredMessagesCapability;
     private unsupportedMethod;
+    /**
+     * Route a cross-agent batch mutation.
+     *
+     * A batch can name agents served by different members, so unlike
+     * `routedWrite` there is no single target. Each item is resolved to its own
+     * member using the same rules (unsupported and ambiguous both throw), the
+     * batch is split into one sub-batch per member, and results are stitched
+     * back into the caller's original item order.
+     *
+     * Resolution happens for every item up front so an unroutable item fails
+     * the whole call before any member is written to, rather than leaving a
+     * half-applied batch behind.
+     */
+    private routedBatchWrite;
     private guessNonCoreCap;
     protected recordConflict(method: string, agentId: string, channelName: string, values: Array<{
         value: unknown;

package/dist/client/multiplex-client.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MultiplexClient = void 0;
 const multiplex_merge_1 = require("./multiplex-merge");
+const batch_1 = require("../types/batch");
 const errors_1 = require("./errors");
 const snowflake_1 = require("../utils/snowflake");
 const multiplex_gateway_1 = require("./multiplex-gateway");
@@ -293,6 +294,76 @@ class MultiplexClient {
     unsupportedMethod(_method, cap) {
         return () => Promise.reject(new errors_1.UnsupportedCapabilityError(cap, this.clientId));
     }
+    /**
+     * Route a cross-agent batch mutation.
+     *
+     * A batch can name agents served by different members, so unlike
+     * `routedWrite` there is no single target. Each item is resolved to its own
+     * member using the same rules (unsupported and ambiguous both throw), the
+     * batch is split into one sub-batch per member, and results are stitched
+     * back into the caller's original item order.
+     *
+     * Resolution happens for every item up front so an unroutable item fails
+     * the whole call before any member is written to, rather than leaving a
+     * half-applied batch behind.
+     */
+    routedBatchWrite(method, cap) {
+        const self = this;
+        return async function (...rawArgs) {
+            const { args, sources } = self.splitSourcesOption(rawArgs);
+            const items = (args[0] ?? []);
+            if (!Array.isArray(items) || items.length === 0) {
+                return { items: [], count: 0, succeeded: 0, failed: 0 };
+            }
+            const groups = new Map();
+            items.forEach((item, index) => {
+                let members = self.candidates(item.agent_id, cap, sources);
+                if (sources && sources.length === 1) {
+                    const only = members.find((m) => m.id === sources[0]);
+                    if (!only)
+                        throw new errors_1.UnsupportedCapabilityError(cap, sources[0]);
+                    members = [only];
+                }
+                if (members.length === 0)
+                    throw new errors_1.UnsupportedCapabilityError(cap, self.clientId);
+                if (members.length > 1) {
+                    throw new errors_1.AmbiguousWriteError(cap, members.map((m) => m.id));
+                }
+                const target = members[0];
+                const group = groups.get(target.id) ?? {
+                    client: target.client,
+                    items: [],
+                    indices: [],
+                };
+                group.items.push(item);
+                group.indices.push(index);
+                groups.set(target.id, group);
+            });
+            const subclient = method.split(".")[0];
+            const fnName = method.split(".")[1];
+            const results = new Array(items.length);
+            for (const group of groups.values()) {
+                const fn = group.client[subclient][fnName];
+                const response = (await fn.apply(group.client[subclient], [
+                    group.items,
+                ]));
+                group.indices.forEach((originalIndex, i) => {
+                    const item = response.items[i];
+                    // A member that returns a short list would otherwise leave holes;
+                    // record an explicit failure so `count` stays consistent.
+                    results[originalIndex] = item ?? {
+                        agent_id: group.items[i].agent_id,
+                        channel_name: group.items[i].channel_name ?? "",
+                        success: false,
+                        error: "no result returned for batch item",
+                    };
+                });
+            }
+            return (0, batch_1.mergeBatchResponses)([
+                { items: results, count: results.length, succeeded: 0, failed: 0 },
+            ]);
+        };
+    }
     guessNonCoreCap(subclient) {
         switch (subclient) {
             case "alarms": return "alarms.read";
@@ -459,6 +530,7 @@ class MultiplexClient {
             },
             putAggregate: self.routedWrite("aggregates.putAggregate", "aggregates.put"),
             patchAggregate: self.routedWrite("aggregates.patchAggregate", "aggregates.patch"),
+            batchPatchAggregates: self.routedBatchWrite("aggregates.batchPatchAggregates", "aggregates.patch"),
             async getAggregateAttachment(agentIdOrId, ...rest) {
                 const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
                 const agentId = self.extractAgentId(args);
@@ -515,6 +587,10 @@ class MultiplexClient {
             putMessage: self.routedWrite("messages.putMessage", "messages.put"),
             patchMessage: self.routedWrite("messages.patchMessage", "messages.put"),
             deleteMessage: self.routedWrite("messages.deleteMessage", "messages.delete"),
+            batchPostMessages: self.routedBatchWrite("messages.batchPostMessages", "messages.post"),
+            batchPatchMessages: self.routedBatchWrite("messages.batchPatchMessages", "messages.put"),
+            batchPutMessages: self.routedBatchWrite("messages.batchPutMessages", "messages.put"),
+            batchDeleteMessages: self.routedBatchWrite("messages.batchDeleteMessages", "messages.delete"),
             getTimeseries: self.makeFanoutFirst("messages.getTimeseries", "messages.timeseries"),
             getMessageAttachment: self.makeBlobFanout("messages.getMessageAttachment", "messages.attachment"),
             getInvocationLogs: self.makeFanoutFirst("messages.getInvocationLogs", "messages.invocationLogs"),

package/dist/client/offline-cache.js

@@ -215,6 +215,7 @@ class OfflineDataClient {
             }),
             putAggregate: this.offlineGuard("aggregates.putAggregate", target.putAggregate.bind(target)),
             patchAggregate: this.offlineGuard("aggregates.patchAggregate", target.patchAggregate.bind(target)),
+            batchPatchAggregates: this.offlineGuard("aggregates.batchPatchAggregates", target.batchPatchAggregates.bind(target)),
             getAggregateAttachment: ((...rawArgs) => {
                 const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
                 const { agentId, channelName } = extractChannelId(args);
@@ -267,6 +268,10 @@ class OfflineDataClient {
             putMessage: this.offlineGuard("messages.putMessage", target.putMessage.bind(target)),
             patchMessage: this.offlineGuard("messages.patchMessage", target.patchMessage.bind(target)),
             deleteMessage: this.offlineGuard("messages.deleteMessage", target.deleteMessage.bind(target)),
+            batchPostMessages: this.offlineGuard("messages.batchPostMessages", target.batchPostMessages.bind(target)),
+            batchPatchMessages: this.offlineGuard("messages.batchPatchMessages", target.batchPatchMessages.bind(target)),
+            batchPutMessages: this.offlineGuard("messages.batchPutMessages", target.batchPutMessages.bind(target)),
+            batchDeleteMessages: this.offlineGuard("messages.batchDeleteMessages", target.batchDeleteMessages.bind(target)),
             getTimeseries: ((...args) => target.getTimeseries(...args)),
             getMessageAttachment: ((...rawArgs) => {
                 const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);

package/dist/index.d.ts

@@ -31,6 +31,8 @@ export { OfflineDataClient, MemoryOfflineStorageAdapter, DEFAULT_OFFLINE_RETENTI
 export type { OfflineCacheMode, OfflineReadCacheOptions, OfflineChannelPolicy, OfflineCacheScope, OfflineCacheRecord, OfflineStorageAdapter, OfflineDataClientOptions, } from "./client/offline-cache";
 export { requestOptions, isDooverRequestOptions, splitRequestOptions, } from "./client/request-options";
 export type { DooverRequestOptions } from "./client/request-options";
+export { MAX_BATCH_ITEMS, chunkBatchItems, mergeBatchResponses } from "./types/batch";
+export type { BatchAggregateUpdateItem, BatchAggregateResponse, BatchCreateMessageItem, BatchUpdateMessageItem, BatchDeleteMessageItem, BatchMessageResponse, BatchMessageResultItem, BatchResultItem, BatchResponse, } from "./types/batch";
 export type { DataClient, AgentScope, DataClientStatus, DataClientConnectionState, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, TurnApiLike, UsersApiLike, GatewayClientLike, RpcDispatcherLike, } from "./client/data-client";
 export type { SourceProvenance, SourceProvenanceViaRest, SourceProvenanceViaGateway, } from "./types/provenance";
 export { DooverAuth } from "./auth/doover-auth";

package/dist/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.splitRequestOptions = exports.isDooverRequestOptions = exports.requestOptions = exports.DEFAULT_OFFLINE_RETENTION_MS = exports.MemoryOfflineStorageAdapter = exports.OfflineDataClient = exports.DooverOfflineError = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = exports.ALL_CAPABILITIES = exports.DooverRpcError = exports.RpcDispatcher = exports.UsersApi = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.OrganisationsApi = 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.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.mergeBatchResponses = exports.chunkBatchItems = exports.MAX_BATCH_ITEMS = exports.splitRequestOptions = exports.isDooverRequestOptions = exports.requestOptions = exports.DEFAULT_OFFLINE_RETENTION_MS = exports.MemoryOfflineStorageAdapter = exports.OfflineDataClient = exports.DooverOfflineError = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = exports.ALL_CAPABILITIES = exports.DooverRpcError = exports.RpcDispatcher = exports.UsersApi = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.OrganisationsApi = 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 = 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");
@@ -55,6 +56,10 @@ var request_options_1 = require("./client/request-options");
 Object.defineProperty(exports, "requestOptions", { enumerable: true, get: function () { return request_options_1.requestOptions; } });
 Object.defineProperty(exports, "isDooverRequestOptions", { enumerable: true, get: function () { return request_options_1.isDooverRequestOptions; } });
 Object.defineProperty(exports, "splitRequestOptions", { enumerable: true, get: function () { return request_options_1.splitRequestOptions; } });
+var batch_1 = require("./types/batch");
+Object.defineProperty(exports, "MAX_BATCH_ITEMS", { enumerable: true, get: function () { return batch_1.MAX_BATCH_ITEMS; } });
+Object.defineProperty(exports, "chunkBatchItems", { enumerable: true, get: function () { return batch_1.chunkBatchItems; } });
+Object.defineProperty(exports, "mergeBatchResponses", { enumerable: true, get: function () { return batch_1.mergeBatchResponses; } });
 var doover_auth_1 = require("./auth/doover-auth");
 Object.defineProperty(exports, "DooverAuth", { enumerable: true, get: function () { return doover_auth_1.DooverAuth; } });
 var cookie_auth_1 = require("./auth/cookie-auth");

package/dist/react/useChannelMessages.js

@@ -99,38 +99,68 @@ function useChannelMessages(identifier, options) {
         queryKey: key,
         enabled: !!agentId && !!channelName,
         staleTime: Infinity,
-        initialPageParam: (anchor ?? initialBefore),
-        getNextPageParam: (lastPage) => lastPage && lastPage.length > 0 ? lastPage[0]?.id : undefined,
+        initialPageParam: { before: anchor ?? initialBefore },
+        // Older (down): the next cursor is the oldest id currently held.
+        getNextPageParam: (lastPage) => lastPage && lastPage.length > 0
+            ? { before: lastPage[0]?.id }
+            : undefined,
+        // Newer (up): only for an anchored window — the live window already begins
+        // at "now", so it has nothing above to page into. `after` = newest id held;
+        // the server returns the oldest messages above it, walking up toward now.
+        // An empty page whose own cursor was already a forward `after` means the
+        // top is reached; an empty *initial* page (nothing below the anchor) still
+        // seeds the walk from the anchor, since messages may sit above it.
+        getPreviousPageParam: (firstPage, _all, firstPageParam) => {
+            if (!anchor)
+                return undefined;
+            if (firstPage && firstPage.length > 0) {
+                return { after: firstPage[firstPage.length - 1]?.id };
+            }
+            if (firstPageParam?.after !== undefined)
+                return undefined;
+            return { after: anchor };
+        },
         queryFn: async ({ pageParam }) => {
             if (!agentId || !channelName)
                 return [];
             const id = { agentId, channelName };
-            // Resolve `before` here rather than letting the API default it, so the
-            // range store records the exact bound the request proved.
-            const before = typeof pageParam === "string"
-                ? pageParam
-                : (0, snowflake_1.generateSnowflakeIdAtTime)(new Date());
+            const param = (pageParam ?? {});
             // Mirrors the API's own default; the store needs the limit actually applied
             const effectiveLimit = limit ?? DEFAULT_PAGE_LIMIT;
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `unknown` since the TypeScript overloads don't declare it.
+            const runList = (params) => sources
+                ? client.messages.listMessages(id, params, { sources })
+                : client.messages.listMessages(id, params);
+            // Forward (newer) page: `after` alone pages oldest-first upward. Bypasses
+            // the range store, which models before-anchored windows only.
+            if (param.after !== undefined && param.before === undefined) {
+                const page = await runList({
+                    after: param.after,
+                    ...(limit !== undefined ? { limit } : {}),
+                    ...(fields && fields.length > 0 ? { field_name: fields } : {}),
+                    order: "asc",
+                });
+                return page;
+            }
+            // Older page. Resolve `before` here rather than letting the API default
+            // it, so the range store records the exact bound the request proved.
+            const before = typeof param.before === "string"
+                ? param.before
+                : (0, snowflake_1.generateSnowflakeIdAtTime)(new Date());
             if (rangeCacheable) {
                 const cached = store.read(BigInt(before), effectiveLimit);
                 if (cached)
                     return cached;
             }
             const requestedAt = Date.now();
-            const params = {
+            const page = await runList({
                 before,
                 ...(limit !== undefined ? { limit } : {}),
                 ...(fields && fields.length > 0 ? { field_name: fields } : {}),
                 ...(after !== undefined ? { after } : {}),
                 order: "asc",
-            };
-            // 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 page = sourcesArg
-                ? await client.messages.listMessages(id, params, sourcesArg)
-                : await client.messages.listMessages(id, params);
+            });
             if (rangeCacheable) {
                 store.record({
                     before: BigInt(before),

package/dist/test/apis.test.js

@@ -229,6 +229,36 @@ function setupRest(responseFactory) {
         (0, chai_1.expect)(formData.get("json_payload")).to.equal(JSON.stringify({ data: { x: 1 } }));
         (0, chai_1.expect)(formData.get("attachment-0")).to.be.instanceOf(Blob);
     });
+    (0, mocha_1.it)("pages forward with a bare `after`: sends no `before`, keeps oldest-first", async () => {
+        const older = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00Z"));
+        const newer = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-02T00:00:00Z"));
+        // The `after`-only route returns oldest-first natively (scan_index_forward).
+        const nativeAsc = [
+            { id: older, author_id: "u", channel: { agent_id: "a1", name: "c1" }, data: {}, attachments: [] },
+            { id: newer, author_id: "u", channel: { agent_id: "a1", name: "c1" }, data: {}, attachments: [] },
+        ];
+        let lastQuery;
+        const { rest } = setupRest((url) => {
+            if (url.endsWith("/messages") || url.includes("/messages?")) {
+                lastQuery = new URL(url).searchParams;
+                return (0, helpers_1.createJsonResponse)(nativeAsc);
+            }
+            return (0, helpers_1.createJsonResponse)([]);
+        });
+        const api = new messages_api_1.MessagesApi(rest);
+        // asc: server order already matches → no reversal, no `before` sent.
+        const asc = await api.listMessages("a1", "c1", { after: older, limit: 5, order: "asc" });
+        (0, chai_1.expect)(lastQuery?.get("after")).to.equal(older);
+        (0, chai_1.expect)(lastQuery?.has("before"), "bare `after` must not send `before`").to.equal(false);
+        (0, chai_1.expect)(asc.map((m) => m.id)).to.deep.equal([older, newer]);
+        // desc over the same forward route reverses the native ascending page.
+        const desc = await api.listMessages("a1", "c1", { after: older, limit: 5, order: "desc" });
+        (0, chai_1.expect)(desc.map((m) => m.id)).to.deep.equal([newer, older]);
+        // With `before` present, `after` is only a floor and both bounds are sent.
+        await api.listMessages("a1", "c1", { before: newer, after: older, limit: 5, order: "asc" });
+        (0, chai_1.expect)(lastQuery?.get("before")).to.equal(newer);
+        (0, chai_1.expect)(lastQuery?.get("after")).to.equal(older);
+    });
     (0, mocha_1.it)("covers aggregates and alarms methods", async () => {
         const { rest, fetchMock } = setupRest((url) => {
             if (url.includes("/attachments/")) {

package/dist/test/batch-apis.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/batch-apis.test.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const aggregates_api_1 = require("../apis/aggregates-api");
+const messages_api_1 = require("../apis/messages-api");
+const rest_client_1 = require("../http/rest-client");
+const batch_1 = require("../types/batch");
+const helpers_1 = require("./helpers");
+/**
+ * Rest client whose fetch mock records every request and replies with a
+ * well-formed batch response echoing the submitted items as successes.
+ */
+function setupBatchRest(overrides) {
+    const requests = [];
+    const fetchMock = (0, helpers_1.createFetchMock)((url, init) => {
+        const body = JSON.parse(String(init?.body ?? "{}"));
+        const captured = { url, method: init?.method, body };
+        requests.push(captured);
+        const override = overrides?.(captured);
+        if (override)
+            return (0, helpers_1.createJsonResponse)(override);
+        const items = body.items.map((item) => ({
+            agent_id: item.agent_id,
+            channel_name: item.channel_name,
+            success: true,
+        }));
+        return (0, helpers_1.createJsonResponse)({
+            items,
+            count: items.length,
+            succeeded: items.length,
+            failed: 0,
+        });
+    });
+    const rest = new rest_client_1.RestClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+    });
+    return { rest, requests };
+}
+function aggregateItems(count) {
+    return Array.from({ length: count }, (_, i) => ({
+        agent_id: `agent-${i}`,
+        channel_name: "dv-ui-sub",
+        data: { group_open: { "u1:s1": 1 } },
+    }));
+}
+(0, mocha_1.describe)("batch helpers", () => {
+    (0, mocha_1.it)("chunks to the server ceiling and preserves order", () => {
+        const chunks = (0, batch_1.chunkBatchItems)([1, 2, 3, 4, 5], 2);
+        (0, chai_1.expect)(chunks).to.deep.equal([[1, 2], [3, 4], [5]]);
+    });
+    (0, mocha_1.it)("returns no chunks for an empty list", () => {
+        (0, chai_1.expect)((0, batch_1.chunkBatchItems)([])).to.deep.equal([]);
+    });
+    (0, mocha_1.it)("rejects a nonsensical chunk size rather than looping forever", () => {
+        (0, chai_1.expect)(() => (0, batch_1.chunkBatchItems)([1], 0)).to.throw(RangeError);
+    });
+    (0, mocha_1.it)("recomputes counts when merging responses", () => {
+        const merged = (0, batch_1.mergeBatchResponses)([
+            {
+                items: [{ agent_id: "a", channel_name: "c", success: true }],
+                count: 1,
+                succeeded: 1,
+                failed: 0,
+            },
+            {
+                items: [
+                    { agent_id: "b", channel_name: "c", success: false, error: "boom" },
+                ],
+                count: 1,
+                succeeded: 1, // deliberately wrong: merge must not trust these
+                failed: 0,
+            },
+        ]);
+        (0, chai_1.expect)(merged.count).to.equal(2);
+        (0, chai_1.expect)(merged.succeeded).to.equal(1);
+        (0, chai_1.expect)(merged.failed).to.equal(1);
+        (0, chai_1.expect)(merged.items.map((i) => i.agent_id)).to.deep.equal(["a", "b"]);
+    });
+});
+(0, mocha_1.describe)("AggregatesApi.batchPatchAggregates", () => {
+    (0, mocha_1.it)("PATCHes /agents/aggregates with an items envelope", async () => {
+        const { rest, requests } = setupBatchRest();
+        const api = new aggregates_api_1.AggregatesApi(rest);
+        const response = await api.batchPatchAggregates(aggregateItems(2));
+        (0, chai_1.expect)(requests).to.have.length(1);
+        (0, chai_1.expect)(requests[0].url).to.equal("https://api.example.com/agents/aggregates");
+        (0, chai_1.expect)(requests[0].method).to.equal("PATCH");
+        (0, chai_1.expect)(requests[0].body.items).to.have.length(2);
+        (0, chai_1.expect)(requests[0].body.items[0]).to.deep.equal({
+            agent_id: "agent-0",
+            channel_name: "dv-ui-sub",
+            data: { group_open: { "u1:s1": 1 } },
+        });
+        (0, chai_1.expect)(response.count).to.equal(2);
+        (0, chai_1.expect)(response.succeeded).to.equal(2);
+    });
+    (0, mocha_1.it)("issues no request at all for an empty batch", async () => {
+        const { rest, requests } = setupBatchRest();
+        const api = new aggregates_api_1.AggregatesApi(rest);
+        const response = await api.batchPatchAggregates([]);
+        (0, chai_1.expect)(requests).to.have.length(0);
+        (0, chai_1.expect)(response).to.deep.equal({ items: [], count: 0, succeeded: 0, failed: 0 });
+    });
+    (0, mocha_1.it)("splits oversized batches and merges the responses in order", async () => {
+        const { rest, requests } = setupBatchRest();
+        const api = new aggregates_api_1.AggregatesApi(rest);
+        const total = batch_1.MAX_BATCH_ITEMS + 5;
+        const response = await api.batchPatchAggregates(aggregateItems(total));
+        (0, chai_1.expect)(requests).to.have.length(2);
+        (0, chai_1.expect)(requests[0].body.items).to.have.length(batch_1.MAX_BATCH_ITEMS);
+        (0, chai_1.expect)(requests[1].body.items).to.have.length(5);
+        (0, chai_1.expect)(response.count).to.equal(total);
+        (0, chai_1.expect)(response.items[0].agent_id).to.equal("agent-0");
+        (0, chai_1.expect)(response.items[total - 1].agent_id).to.equal(`agent-${total - 1}`);
+    });
+    (0, mocha_1.it)("surfaces partial failure without throwing", async () => {
+        const { rest } = setupBatchRest(() => ({
+            items: [
+                { agent_id: "agent-0", channel_name: "dv-ui-sub", success: true },
+                {
+                    agent_id: "agent-1",
+                    channel_name: "dv-ui-sub",
+                    success: false,
+                    error: "permission denied",
+                },
+            ],
+            count: 2,
+            succeeded: 1,
+            failed: 1,
+        }));
+        const api = new aggregates_api_1.AggregatesApi(rest);
+        const response = await api.batchPatchAggregates(aggregateItems(2));
+        (0, chai_1.expect)(response.failed).to.equal(1);
+        (0, chai_1.expect)(response.items[1].error).to.equal("permission denied");
+    });
+});
+(0, mocha_1.describe)("MessagesApi batch mutations", () => {
+    (0, mocha_1.it)("POSTs creates to /agents/messages", async () => {
+        const { rest, requests } = setupBatchRest();
+        const api = new messages_api_1.MessagesApi(rest);
+        await api.batchPostMessages([
+            { agent_id: "a1", channel_name: "activity", message_id: "m1", data: { event: "opened" } },
+        ]);
+        (0, chai_1.expect)(requests[0].url).to.equal("https://api.example.com/agents/messages");
+        (0, chai_1.expect)(requests[0].method).to.equal("POST");
+        (0, chai_1.expect)(requests[0].body.items[0].message_id).to.equal("m1");
+    });
+    (0, mocha_1.it)("uses the matching verb for patch, put and delete", async () => {
+        const { rest, requests } = setupBatchRest();
+        const api = new messages_api_1.MessagesApi(rest);
+        const items = [{ agent_id: "a1", channel_name: "c1", message_id: "m1", data: {} }];
+        await api.batchPatchMessages(items);
+        await api.batchPutMessages(items);
+        await api.batchDeleteMessages([{ agent_id: "a1", channel_name: "c1", message_id: "m1" }]);
+        (0, chai_1.expect)(requests.map((r) => r.method)).to.deep.equal(["PATCH", "PUT", "DELETE"]);
+        // DELETE must carry a body — the reason these bypass `rest.delete`.
+        (0, chai_1.expect)(requests[2].body.items).to.have.length(1);
+    });
+    (0, mocha_1.it)("chunks message batches too", async () => {
+        const { rest, requests } = setupBatchRest();
+        const api = new messages_api_1.MessagesApi(rest);
+        const items = Array.from({ length: batch_1.MAX_BATCH_ITEMS + 1 }, (_, i) => ({
+            agent_id: `a${i}`,
+            channel_name: "c1",
+            message_id: `m${i}`,
+            data: {},
+        }));
+        const response = await api.batchPatchMessages(items);
+        (0, chai_1.expect)(requests).to.have.length(2);
+        (0, chai_1.expect)(response.count).to.equal(batch_1.MAX_BATCH_ITEMS + 1);
+    });
+    (0, mocha_1.it)("issues no request for an empty message batch", async () => {
+        const { rest, requests } = setupBatchRest();
+        const api = new messages_api_1.MessagesApi(rest);
+        const response = await api.batchDeleteMessages([]);
+        (0, chai_1.expect)(requests).to.have.length(0);
+        (0, chai_1.expect)(response.count).to.equal(0);
+    });
+});

package/dist/test/react-channel-messages-forward.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/react-channel-messages-forward.test.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const sinon_1 = __importDefault(require("sinon"));
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const messageRangeStore_1 = require("../react/messageRangeStore");
+const snowflake_1 = require("../utils/snowflake");
+const helpers_1 = require("./helpers");
+const AGENT = "agent-1";
+const CHANNEL = "camera_1";
+const NOW = Date.now();
+/** `COUNT` messages, one per minute, ascending by id (index 0 = oldest). */
+const COUNT = 60;
+const ALL = Array.from({ length: COUNT }, (_, i) => {
+    const at = new Date(NOW - (COUNT - 1 - i) * 60000);
+    return {
+        id: (0, snowflake_1.generateSnowflakeIdAtTime)(at),
+        data: { i },
+        attachments: [],
+        author_id: "author",
+        channel: { agent_id: AGENT, name: CHANNEL },
+    };
+}).sort((a, b) => (BigInt(a.id) < BigInt(b.id) ? -1 : 1));
+/**
+ * Emulates the REST route's *native* ordering, which the SDK client then
+ * reverses per `order`: `before` returns the newest N below the cursor,
+ * newest-first; a bare `after` returns the oldest N above it, oldest-first.
+ */
+function serveNative(query) {
+    const before = query.get("before");
+    const after = query.get("after");
+    const limit = Number(query.get("limit") ?? "10");
+    if (before && !after) {
+        const below = ALL.filter((m) => BigInt(m.id) < BigInt(before));
+        return below.slice(Math.max(0, below.length - limit)).reverse(); // newest-first
+    }
+    if (after && !before) {
+        const above = ALL.filter((m) => BigInt(m.id) > BigInt(after));
+        return above.slice(0, limit); // oldest-first
+    }
+    // both bounds: newest-first within (after, before]
+    const within = ALL.filter((m) => BigInt(m.id) < BigInt(before) && BigInt(m.id) > BigInt(after));
+    return within.slice(Math.max(0, within.length - limit)).reverse();
+}
+function makeClient() {
+    const calls = [];
+    const fetchMock = sinon_1.default.stub().callsFake(async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (url.includes("/messages")) {
+            const q = new URL(url).searchParams;
+            calls.push(q);
+            return (0, helpers_1.createJsonResponse)(serveNative(q));
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, calls };
+}
+function wrapper(client, queryClient) {
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+const newQueryClient = () => new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+const idAtIndex = (i) => ALL[i].id;
+const timeOfIndex = (i) => NOW - (COUNT - 1 - i) * 60000;
+/** A snowflake landing strictly between messages i and i+1 (30s after i). */
+const anchorAfter = (i) => (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(timeOfIndex(i) + 30000));
+(0, mocha_1.describe)("useChannelMessages forward pagination", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        (0, messageRangeStore_1.resetChannelRangeStores)();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("pages forward from an anchor into newer messages", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        // Anchor between index 29 and 30 — half the history is newer than it.
+        const anchor = anchorAfter(29);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(10));
+        // The anchored page is the 10 newest *below* the anchor: indices 20..29.
+        (0, chai_1.expect)(result.current.messages.every((m) => BigInt(m.id) < BigInt(anchor))).to.equal(true);
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(true);
+        await (0, react_1.act)(async () => {
+            await result.current.fetchPreviousPage();
+        });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages.some((m) => BigInt(m.id) > BigInt(anchor))).to.equal(true));
+        // Forward page brought in the messages immediately above the anchor (index 30+).
+        (0, chai_1.expect)(result.current.messages.map((m) => m.data).some((d) => d.i >= 30)).to.equal(true);
+    });
+    (0, mocha_1.it)("exposes no previous page for an unanchored (live) window", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(10));
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(false);
+    });
+    (0, mocha_1.it)("recovers messages above an anchor that has nothing below it, and terminates", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        // Anchor older than every message: the initial before=anchor page is empty.
+        const anchor = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - COUNT * 10 * 60000));
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.isLoading).to.equal(false));
+        (0, chai_1.expect)(result.current.messages).to.have.length(0);
+        // Empty below, but the walk still seeds from the anchor itself.
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(true);
+        // Drain forward until exhausted — must terminate, never loop.
+        for (let guard = 0; guard < 20 && result.current.hasPreviousPage; guard++) {
+            await (0, react_1.act)(async () => {
+                await result.current.fetchPreviousPage();
+            });
+        }
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(false);
+        // Every message above the anchor is recovered (order is the consumer's job).
+        const ids = result.current.messages.map((m) => m.id);
+        (0, chai_1.expect)(ids).to.have.length(COUNT);
+        (0, chai_1.expect)(ids).to.include(idAtIndex(0));
+        (0, chai_1.expect)(ids).to.include(idAtIndex(COUNT - 1));
+    });
+});

package/dist/test/react-multiagent-messages.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/react-multiagent-messages.test.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const helpers_1 = require("./helpers");
+const sinon_1 = __importDefault(require("sinon"));
+/**
+ * Fetch mock for the multi-agent messages endpoint. `pagesByRound` supplies
+ * one canned response per call, in order, so a test can hand back
+ * `next_cursors` on early rounds and drain on the last one.
+ */
+function makeClient(pagesByRound) {
+    let round = 0;
+    const calls = [];
+    const fetchMock = sinon_1.default.stub().callsFake(async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (url.includes("/messages")) {
+            const parsed = new URL(url);
+            calls.push({
+                agent_id: parsed.searchParams.getAll("agent_id"),
+                agent_before: parsed.searchParams.getAll("agent_before"),
+            });
+            const page = pagesByRound[Math.min(round, pagesByRound.length - 1)];
+            round += 1;
+            return (0, helpers_1.createJsonResponse)(page);
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, calls };
+}
+function wrapper(client) {
+    const queryClient = new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+function msg(id, agentId) {
+    return { id, channel: { agent_id: agentId, name: "tag_values" }, data: {} };
+}
+(0, mocha_1.describe)("useMultiAgentChannelMessages autoPaginate", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        helpers_1.MockWebSocket.reset();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("walks back per-agent via next_cursors until the window drains", async () => {
+        const { client, calls } = makeClient([
+            // round 1: a1 hit its limit (cursor returned), a2 drained already
+            { results: [msg("100", "a1"), msg("99", "a2")], next_cursors: { a1: "90" } },
+            // round 2: a1 drains
+            { results: [msg("89", "a1")], next_cursors: {} },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1", "a2"], {
+            after: "1",
+            agentMessageLimit: 2,
+            autoPaginate: true,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(3));
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(false);
+        // Second request must resume ONLY a1, using its own cursor as agent_before.
+        (0, chai_1.expect)(calls).to.have.length(2);
+        (0, chai_1.expect)(calls[1].agent_id).to.deep.equal(["a1"]);
+        (0, chai_1.expect)(calls[1].agent_before).to.deep.equal(["90"]);
+    });
+    (0, mocha_1.it)("does not paginate when autoPaginate is off", async () => {
+        const { client, calls } = makeClient([
+            { results: [msg("100", "a1")], next_cursors: { a1: "90" } },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1"], {
+            agentMessageLimit: 1,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(1));
+        // hasNextPage is exposed, but nothing auto-fetches the second page.
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(true);
+        (0, chai_1.expect)(calls).to.have.length(1);
+    });
+    (0, mocha_1.it)("dedupes messages that repeat across pages", async () => {
+        const { client } = makeClient([
+            { results: [msg("100", "a1")], next_cursors: { a1: "100" } },
+            // overlaps the previous page's id 100 (legacy-style re-return)
+            { results: [msg("100", "a1"), msg("90", "a1")], next_cursors: {} },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1"], {
+            after: "1",
+            agentMessageLimit: 1,
+            autoPaginate: true,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(2));
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(false);
+        (0, chai_1.expect)(result.current.messages.map((m) => m.id)).to.deep.equal(["100", "90"]);
+    });
+});

package/dist/types/batch.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared types for the bounded batch mutation endpoints.
+ *
+ * The data API exposes cross-agent batch mutations at `/agents/aggregates`
+ * and `/agents/messages`. Every item carries its own `agent_id` and
+ * `channel_name`, each is authorised independently, and the batch can
+ * partially succeed — results come back in request order and callers should
+ * retry only the failed entries.
+ *
+ * See `docs/batch-aggregate-updates.md` in channels-rest for the contract.
+ */
+/**
+ * Server-enforced ceiling on items per batch request. Exceeding it is a 400,
+ * so callers must chunk. `chunkBatchItems` does this for you.
+ */
+export declare const MAX_BATCH_ITEMS = 50;
+/** A single merge-patch against one agent's channel aggregate. */
+export interface BatchAggregateUpdateItem {
+    agent_id: string;
+    channel_name: string;
+    /** Merge patch. `null` at a leaf clears that key. */
+    data: Record<string, unknown>;
+    /**
+     * Dot-paths to replace outright rather than merge into. Mirrors the
+     * `replace` query parameter on the single-aggregate PATCH.
+     */
+    replace?: string[];
+    /** Skip aggregate hooks (alarms, SNS fan-out, websocket publish). */
+    suppress_hooks?: boolean;
+}
+export interface BatchCreateMessageItem {
+    agent_id: string;
+    channel_name: string;
+    /**
+     * Supplying a stable ID makes create retries idempotent. Without one the
+     * server generates an ID and a lost response can duplicate the message.
+     */
+    message_id?: string;
+    data: unknown;
+    /** Message timestamp, ms since epoch. Defaults to server receipt time. */
+    ts?: number;
+    /** Time-to-live in seconds. */
+    ttl?: number;
+}
+export interface BatchUpdateMessageItem {
+    agent_id: string;
+    channel_name: string;
+    message_id: string;
+    data: unknown;
+}
+export interface BatchDeleteMessageItem {
+    agent_id: string;
+    channel_name: string;
+    message_id: string;
+}
+/** Per-item outcome. `error` is present only when `success` is false. */
+export interface BatchResultItem {
+    agent_id: string;
+    channel_name: string;
+    success: boolean;
+    error?: string;
+}
+export interface BatchMessageResultItem extends BatchResultItem {
+    /** Present for creates — the server-generated ID when none was supplied. */
+    message_id?: string;
+}
+export interface BatchResponse<TItem extends BatchResultItem = BatchResultItem> {
+    /** Results in request order, one per submitted item. */
+    items: TItem[];
+    count: number;
+    succeeded: number;
+    failed: number;
+}
+export type BatchAggregateResponse = BatchResponse<BatchResultItem>;
+export type BatchMessageResponse = BatchResponse<BatchMessageResultItem>;
+/**
+ * Split `items` into server-acceptable chunks. Returns `[]` for an empty
+ * input, since an empty batch is a 400 rather than a no-op.
+ */
+export declare function chunkBatchItems<T>(items: T[], size?: number): T[][];
+/**
+ * Merge several batch responses into one, as if the whole set had been sent
+ * in a single request. Useful after chunking.
+ */
+export declare function mergeBatchResponses<TItem extends BatchResultItem>(responses: BatchResponse<TItem>[]): BatchResponse<TItem>;

package/dist/types/batch.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Shared types for the bounded batch mutation endpoints.
+ *
+ * The data API exposes cross-agent batch mutations at `/agents/aggregates`
+ * and `/agents/messages`. Every item carries its own `agent_id` and
+ * `channel_name`, each is authorised independently, and the batch can
+ * partially succeed — results come back in request order and callers should
+ * retry only the failed entries.
+ *
+ * See `docs/batch-aggregate-updates.md` in channels-rest for the contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BATCH_ITEMS = void 0;
+exports.chunkBatchItems = chunkBatchItems;
+exports.mergeBatchResponses = mergeBatchResponses;
+/**
+ * Server-enforced ceiling on items per batch request. Exceeding it is a 400,
+ * so callers must chunk. `chunkBatchItems` does this for you.
+ */
+exports.MAX_BATCH_ITEMS = 50;
+/**
+ * Split `items` into server-acceptable chunks. Returns `[]` for an empty
+ * input, since an empty batch is a 400 rather than a no-op.
+ */
+function chunkBatchItems(items, size = exports.MAX_BATCH_ITEMS) {
+    if (size < 1)
+        throw new RangeError("chunk size must be at least 1");
+    const out = [];
+    for (let i = 0; i < items.length; i += size) {
+        out.push(items.slice(i, i + size));
+    }
+    return out;
+}
+/**
+ * Merge several batch responses into one, as if the whole set had been sent
+ * in a single request. Useful after chunking.
+ */
+function mergeBatchResponses(responses) {
+    const items = responses.flatMap((r) => r.items);
+    return {
+        items,
+        count: items.length,
+        succeeded: items.filter((i) => i.success).length,
+        failed: items.filter((i) => !i.success).length,
+    };
+}

package/package.json

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