doover-js 0.7.1 → 0.8.1

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

@@ -19,6 +19,65 @@ export interface MultiAgentMessagesParams {
     agent_message_limit?: number;
     field_name?: string[];
 }
+/**
+ * One token-posture knob across all three layers, so a UI can show
+ * "inherited from organisation" vs "overridden on this device" and offer a reset
+ * without duplicating the precedence rule client-side.
+ */
+export interface TokenPolicyField<T> {
+    /** What is actually enforced: `agent_override` if set, else `org_default`. */
+    effective: T | null;
+    /** This device's override. `null` means it inherits. */
+    agent_override: T | null;
+    /** The organisation-wide default inherited when not overridden. */
+    org_default: T | null;
+}
+export interface AgentTokenState {
+    /**
+     * Unix-ms revocation floor: every long-lived credential issued before this is
+     * rejected. `null` means nothing has ever been revoked for this agent.
+     */
+    tokens_valid_from: number | null;
+    /** Auth kill-switch — while true, every auth attempt is rejected. */
+    auth_locked: boolean;
+    self_rotation: TokenPolicyField<boolean>;
+    max_age_ms: TokenPolicyField<number>;
+    reuse_grace_ms: TokenPolicyField<number>;
+}
+/**
+ * A token-posture override. `null` on any field means "inherit the organisation
+ * default"; there is no way to express "explicitly off, ignoring the default",
+ * because every knob here is off when absent.
+ */
+export interface AgentTokenPolicy {
+    /** Allow the device to trade its own credential for a fresh one. */
+    self_rotation?: boolean | null;
+    /**
+     * Hard maximum credential age. Only valid alongside `self_rotation` — without
+     * it the device cannot rotate before the deadline and will be locked out.
+     */
+    max_age_ms?: number | null;
+    /**
+     * Grace window after a rotation before a stale credential counts as reuse.
+     * Setting this opts the device into *automatic* lockout on reuse detection.
+     */
+    reuse_grace_ms?: number | null;
+}
+export interface ResourcePermission {
+    permission_id: string;
+    permission: string;
+}
+export interface AdhocTokenResponse {
+    /** Shown once. Not retrievable afterwards. */
+    token: string;
+    token_id: string | null;
+}
+export interface DeviceTokenResponse {
+    /** Shown once. Not stored anywhere and not retrievable afterwards. */
+    token: string;
+    /** Unix-ms issuance time, which is what the revocation floor compares against. */
+    issued_at_ms: number | null;
+}
 export interface MultiAgentAggregatesParams {
     agent_id: string[];
     /**
@@ -56,4 +115,82 @@ export declare class AgentsApi {
         results: AgentAggregate[];
         count: number;
     }>;
+    /**
+     * Read an agent's credential state: the revocation floor, the auth
+     * kill-switch, and the token posture resolved across the per-agent override
+     * and the organisation default.
+     *
+     * Requires `AgentTokenRead`, which is read-only — a caller can display
+     * credential state (including an auth-lock banner, often the only explanation
+     * for why a device is offline) without being able to change any of it.
+     */
+    getTokenState(agentId: string): Promise<AgentTokenState>;
+    /**
+     * Replace an agent's token-posture override. Omitted or null fields mean
+     * "inherit the organisation default" — a full replacement rather than a
+     * merge, so clearing an override back to inherited is expressible.
+     *
+     * Rejected server-side if the resolved posture sets `max_age_ms` without
+     * `self_rotation`: a device that can't self-rotate has no way to trade its
+     * token in before the max age elapses, making that combination a scheduled
+     * outage.
+     */
+    setTokenPolicy(agentId: string, policy: AgentTokenPolicy): Promise<{
+        effective: AgentTokenPolicy;
+    }>;
+    /**
+     * Set or clear the auth kill-switch. While locked, every auth attempt for the
+     * agent is rejected regardless of token validity.
+     *
+     * doover-data sets this automatically on suspected token reuse, so clearing it
+     * is a routine incident-response action rather than an exotic one.
+     */
+    setAuthLock(agentId: string, locked: boolean): Promise<void>;
+    /**
+     * Revoke every outstanding long-lived credential for an agent by advancing the
+     * revocation floor. Mints nothing.
+     *
+     * This takes the device offline until it is re-provisioned. Break-glass:
+     * confirm before calling.
+     */
+    revokeAllTokens(agentId: string): Promise<{
+        tokens_valid_from: number;
+    }>;
+    /**
+     * Set the revocation floor to an explicit point, in either direction. `0` or
+     * `null` clears it.
+     *
+     * `revokeAllTokens` is the normal way to revoke. Lowering the floor reverses a
+     * revocation, so it is for undoing one made by mistake — not for recovering
+     * from a leak, where you should issue fresh credentials instead.
+     */
+    setRevocationFloor(agentId: string, tokensValidFrom: number | null): Promise<{
+        tokens_valid_from: number | null;
+    }>;
+    /**
+     * Mint a short-lived scoped JWT for ad-hoc access to an agent — debugging, a
+     * one-off script, an integration.
+     *
+     * This is the way to give a *person* access to a device. The device's own
+     * long-lived credential is deliberately not obtainable through the API: it is
+     * minted into an installer bundle and never shown. Expiry stands in for
+     * revocation here, so keep `timeout` as short as the task allows.
+     */
+    createAdhocToken(agentId: string, options?: {
+        permissions?: ResourcePermission[];
+        timeout?: number;
+    }): Promise<AdhocTokenResponse>;
+    /**
+     * Mint the device's long-lived credential and return it once, for manual
+     * provisioning — pasting into a device's config by hand. The installer download
+     * mints one into the bundle for you; this is the equivalent for a device you're
+     * configuring yourself.
+     *
+     * Always additive: the revocation floor is left alone, so minting can never
+     * knock a running device offline. `revoke_existing` is intentionally not
+     * exposed here — revoking is `revokeAllTokens`, a separate deliberate act.
+     *
+     * Returned once and stored nowhere. If it's lost, mint another.
+     */
+    createDeviceToken(agentId: string): Promise<DeviceTokenResponse>;
 }

package/dist/apis/agents-api.js

@@ -232,6 +232,96 @@ class AgentsApi {
             count: responses.reduce((acc, r) => acc + r.count, 0),
         };
     }
+    /**
+     * Read an agent's credential state: the revocation floor, the auth
+     * kill-switch, and the token posture resolved across the per-agent override
+     * and the organisation default.
+     *
+     * Requires `AgentTokenRead`, which is read-only — a caller can display
+     * credential state (including an auth-lock banner, often the only explanation
+     * for why a device is offline) without being able to change any of it.
+     */
+    getTokenState(agentId) {
+        return this.rest.get(`/agents/${agentId}/token_state`);
+    }
+    /**
+     * Replace an agent's token-posture override. Omitted or null fields mean
+     * "inherit the organisation default" — a full replacement rather than a
+     * merge, so clearing an override back to inherited is expressible.
+     *
+     * Rejected server-side if the resolved posture sets `max_age_ms` without
+     * `self_rotation`: a device that can't self-rotate has no way to trade its
+     * token in before the max age elapses, making that combination a scheduled
+     * outage.
+     */
+    setTokenPolicy(agentId, policy) {
+        return this.rest.put(`/agents/${agentId}/token_policy`, policy);
+    }
+    /**
+     * Set or clear the auth kill-switch. While locked, every auth attempt for the
+     * agent is rejected regardless of token validity.
+     *
+     * doover-data sets this automatically on suspected token reuse, so clearing it
+     * is a routine incident-response action rather than an exotic one.
+     */
+    setAuthLock(agentId, locked) {
+        return this.rest.post(`/agents/${agentId}/auth_lock`, { locked });
+    }
+    /**
+     * Revoke every outstanding long-lived credential for an agent by advancing the
+     * revocation floor. Mints nothing.
+     *
+     * This takes the device offline until it is re-provisioned. Break-glass:
+     * confirm before calling.
+     */
+    revokeAllTokens(agentId) {
+        return this.rest.post(`/agents/${agentId}/token/revoke_all`, {});
+    }
+    /**
+     * Set the revocation floor to an explicit point, in either direction. `0` or
+     * `null` clears it.
+     *
+     * `revokeAllTokens` is the normal way to revoke. Lowering the floor reverses a
+     * revocation, so it is for undoing one made by mistake — not for recovering
+     * from a leak, where you should issue fresh credentials instead.
+     */
+    setRevocationFloor(agentId, tokensValidFrom) {
+        return this.rest.post(`/agents/${agentId}/token/floor`, { tokens_valid_from: tokensValidFrom });
+    }
+    /**
+     * Mint a short-lived scoped JWT for ad-hoc access to an agent — debugging, a
+     * one-off script, an integration.
+     *
+     * This is the way to give a *person* access to a device. The device's own
+     * long-lived credential is deliberately not obtainable through the API: it is
+     * minted into an installer bundle and never shown. Expiry stands in for
+     * revocation here, so keep `timeout` as short as the task allows.
+     */
+    createAdhocToken(agentId, options = {}) {
+        return this.rest.post(`/agents/${agentId}/token`, {
+            format: "jwt",
+            permissions: options.permissions ?? [],
+            timeout: options.timeout,
+        });
+    }
+    /**
+     * Mint the device's long-lived credential and return it once, for manual
+     * provisioning — pasting into a device's config by hand. The installer download
+     * mints one into the bundle for you; this is the equivalent for a device you're
+     * configuring yourself.
+     *
+     * Always additive: the revocation floor is left alone, so minting can never
+     * knock a running device offline. `revoke_existing` is intentionally not
+     * exposed here — revoking is `revokeAllTokens`, a separate deliberate act.
+     *
+     * Returned once and stored nowhere. If it's lost, mint another.
+     */
+    createDeviceToken(agentId) {
+        return this.rest.post(`/agents/${agentId}/token`, {
+            format: "mini_v1",
+            revoke_existing: false,
+        });
+    }
 }
 exports.AgentsApi = AgentsApi;
 // CloudFront fronts the channels-rest API with a hard 8,192-byte URL quota.

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/capabilities.d.ts

@@ -6,5 +6,5 @@
  * String-literal union (not a TS enum) so values serialise cleanly and can
  * appear in error messages / debug UIs verbatim.
  */
-export type Capability = "agents.list" | "agents.multiAgentMessages" | "agents.multiAgentAggregates" | "channels.list" | "channels.get" | "channels.create" | "channels.archive" | "channels.dataSeries" | "aggregates.get" | "aggregates.put" | "aggregates.patch" | "aggregates.attachment" | "messages.list" | "messages.listHistorical" | "messages.get" | "messages.post" | "messages.put" | "messages.delete" | "messages.attachment" | "messages.timeseries" | "messages.invocationLogs" | "gateway.subscribe" | "gateway.realtime" | "gateway.oneShot" | "rpc.send" | "alarms.read" | "alarms.write" | "connections.read" | "connections.write" | "notifications.read" | "notifications.write" | "permissions.read" | "permissions.write" | "processors.read" | "processors.write" | "turn.credentials" | "users.me";
+export type Capability = "agents.list" | "agents.multiAgentMessages" | "agents.multiAgentAggregates" | "agents.tokenRead" | "agents.tokenManage" | "channels.list" | "channels.get" | "channels.create" | "channels.archive" | "channels.dataSeries" | "aggregates.get" | "aggregates.put" | "aggregates.patch" | "aggregates.attachment" | "messages.list" | "messages.listHistorical" | "messages.get" | "messages.post" | "messages.put" | "messages.delete" | "messages.attachment" | "messages.timeseries" | "messages.invocationLogs" | "gateway.subscribe" | "gateway.realtime" | "gateway.oneShot" | "rpc.send" | "alarms.read" | "alarms.write" | "connections.read" | "connections.write" | "notifications.read" | "notifications.write" | "permissions.read" | "permissions.write" | "processors.read" | "processors.write" | "turn.credentials" | "users.me";
 export declare const ALL_CAPABILITIES: readonly Capability[];

package/dist/client/capabilities.js

@@ -5,6 +5,8 @@ exports.ALL_CAPABILITIES = [
     "agents.list",
     "agents.multiAgentMessages",
     "agents.multiAgentAggregates",
+    "agents.tokenRead",
+    "agents.tokenManage",
     "channels.list",
     "channels.get",
     "channels.create",

package/dist/client/local-agent-client.js

@@ -183,6 +183,13 @@ const METHOD_TO_CAPABILITY = {
     "agents.listAgents": "agents.list",
     "agents.getMultiAgentMessages": "agents.multiAgentMessages",
     "agents.getMultiAgentAggregates": "agents.multiAgentAggregates",
+    "agents.getTokenState": "agents.tokenRead",
+    "agents.setTokenPolicy": "agents.tokenManage",
+    "agents.setAuthLock": "agents.tokenManage",
+    "agents.revokeAllTokens": "agents.tokenManage",
+    "agents.setRevocationFloor": "agents.tokenManage",
+    "agents.createAdhocToken": "agents.tokenManage",
+    "agents.createDeviceToken": "agents.tokenManage",
     "channels.listChannels": "channels.list",
     "channels.getChannel": "channels.get",
     "channels.createChannel": "channels.create",

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"),
@@ -584,6 +660,13 @@ class MultiplexClient {
                 const merged = (0, multiplex_merge_1.dedupeBy)([].concat(...responses.map((r) => r.results)), (a) => a.agent_id);
                 return { results: merged, count: merged.length };
             },
+            getTokenState: self.makeFanoutFirst("agents.getTokenState", "agents.tokenRead"),
+            setTokenPolicy: self.routedWrite("agents.setTokenPolicy", "agents.tokenManage"),
+            setAuthLock: self.routedWrite("agents.setAuthLock", "agents.tokenManage"),
+            revokeAllTokens: self.routedWrite("agents.revokeAllTokens", "agents.tokenManage"),
+            setRevocationFloor: self.routedWrite("agents.setRevocationFloor", "agents.tokenManage"),
+            createAdhocToken: self.routedWrite("agents.createAdhocToken", "agents.tokenManage"),
+            createDeviceToken: self.routedWrite("agents.createDeviceToken", "agents.tokenManage"),
         };
     }
     // ===== non-core generic facade =====

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

@@ -7,6 +7,7 @@ export { getDooverClient, peekDooverClient, resetDooverClient, } from "./client/
 export { DooverStatsCollector } from "./client/stats";
 export type { DooverStatsSnapshot, RestStatsSnapshot, GatewayStatsSnapshot, } from "./client/stats";
 export { AgentsApi } from "./apis/agents-api";
+export type { AgentTokenState, AgentTokenPolicy, TokenPolicyField, AdhocTokenResponse, DeviceTokenResponse, ResourcePermission, } from "./apis/agents-api";
 export { AggregatesApi } from "./apis/aggregates-api";
 export { AlarmsApi } from "./apis/alarms-api";
 export { ChannelsApi } from "./apis/channels-api";
@@ -31,6 +32,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/index.d.ts

@@ -33,4 +33,6 @@ export type { UseMultiAgentChannelMessagesOptions, UseMultiAgentChannelMessagesR
 export { useDeviceMap } from "./useDeviceMap";
 export type { DeviceMapEntry, UseDeviceMapOptions, UseDeviceMapResult, } from "./useDeviceMap";
 export { useTurnCredentials } from "./useTurnCredentials";
+export { useAgentTokenState, useSetAgentTokenPolicy, useSetAgentAuthLock, useRevokeAgentTokens, useSetRevocationFloor, useCreateAdhocToken, useCreateDeviceToken, agentTokenStateQueryKey, } from "./useAgentTokenState";
+export type { UseAgentTokenStateOptions } from "./useAgentTokenState";
 export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient";

package/dist/react/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
+exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.agentTokenStateQueryKey = exports.useCreateDeviceToken = exports.useCreateAdhocToken = exports.useSetRevocationFloor = exports.useRevokeAgentTokens = exports.useSetAgentAuthLock = exports.useSetAgentTokenPolicy = exports.useAgentTokenState = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "DooverProvider", { enumerable: true, get: function () { return context_1.DooverProvider; } });
 Object.defineProperty(exports, "useDooverClient", { enumerable: true, get: function () { return context_1.useDooverClient; } });
@@ -48,6 +48,15 @@ var useDeviceMap_1 = require("./useDeviceMap");
 Object.defineProperty(exports, "useDeviceMap", { enumerable: true, get: function () { return useDeviceMap_1.useDeviceMap; } });
 var useTurnCredentials_1 = require("./useTurnCredentials");
 Object.defineProperty(exports, "useTurnCredentials", { enumerable: true, get: function () { return useTurnCredentials_1.useTurnCredentials; } });
+var useAgentTokenState_1 = require("./useAgentTokenState");
+Object.defineProperty(exports, "useAgentTokenState", { enumerable: true, get: function () { return useAgentTokenState_1.useAgentTokenState; } });
+Object.defineProperty(exports, "useSetAgentTokenPolicy", { enumerable: true, get: function () { return useAgentTokenState_1.useSetAgentTokenPolicy; } });
+Object.defineProperty(exports, "useSetAgentAuthLock", { enumerable: true, get: function () { return useAgentTokenState_1.useSetAgentAuthLock; } });
+Object.defineProperty(exports, "useRevokeAgentTokens", { enumerable: true, get: function () { return useAgentTokenState_1.useRevokeAgentTokens; } });
+Object.defineProperty(exports, "useSetRevocationFloor", { enumerable: true, get: function () { return useAgentTokenState_1.useSetRevocationFloor; } });
+Object.defineProperty(exports, "useCreateAdhocToken", { enumerable: true, get: function () { return useAgentTokenState_1.useCreateAdhocToken; } });
+Object.defineProperty(exports, "useCreateDeviceToken", { enumerable: true, get: function () { return useAgentTokenState_1.useCreateDeviceToken; } });
+Object.defineProperty(exports, "agentTokenStateQueryKey", { enumerable: true, get: function () { return useAgentTokenState_1.agentTokenStateQueryKey; } });
 var sharedQueryClient_1 = require("./sharedQueryClient");
 Object.defineProperty(exports, "getSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_1.getSharedQueryClient; } });
 Object.defineProperty(exports, "resetSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_1.resetSharedQueryClient; } });

package/dist/react/useAgentTokenState.d.ts

@@ -0,0 +1,70 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { AgentTokenPolicy, AgentTokenState, ResourcePermission } from "../apis/agents-api";
+export declare function agentTokenStateQueryKey(agentId: string | undefined): readonly ["doover", "agent", string | null, "tokenState"];
+export interface UseAgentTokenStateOptions {
+    enabled?: boolean;
+    staleTime?: number;
+}
+/**
+ * Read an agent's credential state — revocation floor, auth kill-switch, and the
+ * token posture resolved across the per-agent override and organisation default.
+ *
+ * Deliberately short `staleTime`: `auth_locked` can be flipped by doover-data
+ * itself (automatic lockout on suspected token reuse), so this value changes
+ * without any action from this client. Showing a stale "not locked" on the one
+ * screen someone opens *because* their device went offline would be worse than
+ * an extra fetch.
+ */
+export declare function useAgentTokenState(agentId: string | undefined, options?: UseAgentTokenStateOptions): UseQueryResult<AgentTokenState>;
+/**
+ * Write an agent's token-posture override. Full replacement — a null field means
+ * "inherit the organisation default".
+ *
+ * Invalidates the token-state query on success so the inherited-vs-overridden
+ * display reflects the write without the caller wiring that up.
+ */
+export declare function useSetAgentTokenPolicy(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    effective: AgentTokenPolicy;
+}, Error, AgentTokenPolicy, unknown>;
+/** Set or clear the auth kill-switch. */
+export declare function useSetAgentAuthLock(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<void, Error, boolean, unknown>;
+/**
+ * Mint a short-lived scoped token for ad-hoc access to an agent.
+ *
+ * Does not invalidate the token-state query: an ad-hoc token is a JWT with its
+ * own expiry and doesn't touch the revocation floor or the agent's posture, so
+ * there is nothing in that query for it to change.
+ *
+ * The resulting token is returned once and is not retrievable afterwards — hand
+ * it straight to the user and don't cache it.
+ */
+export declare function useCreateAdhocToken(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<import("../apis/agents-api").AdhocTokenResponse, Error, {
+    permissions?: ResourcePermission[];
+    timeout?: number;
+}, unknown>;
+/**
+ * Set the revocation floor to an explicit point; pass `0` or `null` to clear it.
+ *
+ * Lowering it reverses a revocation, so this is for undoing one made by mistake
+ * rather than for recovering a device whose credentials leaked.
+ */
+export declare function useSetRevocationFloor(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    tokens_valid_from: number | null;
+}, Error, number | null, unknown>;
+/**
+ * Mint the device's long-lived credential for manual provisioning, returned once.
+ *
+ * Invalidates the token-state query so the revocation floor display stays honest
+ * — the mint itself is additive and doesn't move the floor, but refetching keeps
+ * this in step with anything else that has changed since the panel loaded.
+ */
+export declare function useCreateDeviceToken(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<import("../apis/agents-api").DeviceTokenResponse, Error, void, unknown>;
+/**
+ * Revoke every outstanding long-lived credential for an agent.
+ *
+ * Break-glass: the device stays offline until it is re-provisioned. Confirm with
+ * the user before calling.
+ */
+export declare function useRevokeAgentTokens(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    tokens_valid_from: number;
+}, Error, void, unknown>;

package/dist/react/useAgentTokenState.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentTokenStateQueryKey = agentTokenStateQueryKey;
+exports.useAgentTokenState = useAgentTokenState;
+exports.useSetAgentTokenPolicy = useSetAgentTokenPolicy;
+exports.useSetAgentAuthLock = useSetAgentAuthLock;
+exports.useCreateAdhocToken = useCreateAdhocToken;
+exports.useSetRevocationFloor = useSetRevocationFloor;
+exports.useCreateDeviceToken = useCreateDeviceToken;
+exports.useRevokeAgentTokens = useRevokeAgentTokens;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+function agentTokenStateQueryKey(agentId) {
+    return ["doover", "agent", agentId ?? null, "tokenState"];
+}
+/**
+ * Read an agent's credential state — revocation floor, auth kill-switch, and the
+ * token posture resolved across the per-agent override and organisation default.
+ *
+ * Deliberately short `staleTime`: `auth_locked` can be flipped by doover-data
+ * itself (automatic lockout on suspected token reuse), so this value changes
+ * without any action from this client. Showing a stale "not locked" on the one
+ * screen someone opens *because* their device went offline would be worse than
+ * an extra fetch.
+ */
+function useAgentTokenState(agentId, options) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useQuery)({
+        queryKey: agentTokenStateQueryKey(agentId),
+        enabled: (options?.enabled ?? true) && Boolean(agentId),
+        staleTime: options?.staleTime ?? 15 * 1000,
+        queryFn: () => client.agents.getTokenState(agentId),
+    });
+}
+/**
+ * Write an agent's token-posture override. Full replacement — a null field means
+ * "inherit the organisation default".
+ *
+ * Invalidates the token-state query on success so the inherited-vs-overridden
+ * display reflects the write without the caller wiring that up.
+ */
+function useSetAgentTokenPolicy(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (policy) => client.agents.setTokenPolicy(agentId, policy),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/** Set or clear the auth kill-switch. */
+function useSetAgentAuthLock(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (locked) => client.agents.setAuthLock(agentId, locked),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Mint a short-lived scoped token for ad-hoc access to an agent.
+ *
+ * Does not invalidate the token-state query: an ad-hoc token is a JWT with its
+ * own expiry and doesn't touch the revocation floor or the agent's posture, so
+ * there is nothing in that query for it to change.
+ *
+ * The resulting token is returned once and is not retrievable afterwards — hand
+ * it straight to the user and don't cache it.
+ */
+function useCreateAdhocToken(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (options) => client.agents.createAdhocToken(agentId, options),
+    });
+}
+/**
+ * Set the revocation floor to an explicit point; pass `0` or `null` to clear it.
+ *
+ * Lowering it reverses a revocation, so this is for undoing one made by mistake
+ * rather than for recovering a device whose credentials leaked.
+ */
+function useSetRevocationFloor(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (tokensValidFrom) => client.agents.setRevocationFloor(agentId, tokensValidFrom),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Mint the device's long-lived credential for manual provisioning, returned once.
+ *
+ * Invalidates the token-state query so the revocation floor display stays honest
+ * — the mint itself is additive and doesn't move the floor, but refetching keeps
+ * this in step with anything else that has changed since the panel loaded.
+ */
+function useCreateDeviceToken(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: () => client.agents.createDeviceToken(agentId),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Revoke every outstanding long-lived credential for an agent.
+ *
+ * Break-glass: the device stays offline until it is re-provisioned. Confirm with
+ * the user before calling.
+ */
+function useRevokeAgentTokens(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: () => client.agents.revokeAllTokens(agentId),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}

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.1",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",