doover-js 0.7.1 → 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,6 +1,7 @@
 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;
     /**
@@ -93,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,6 +3,7 @@ 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;
@@ -137,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/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/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.1",
+  "version": "0.8.0",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",