@larc-iu/plaid-client 0.1.0-alpha.9 → 0.2.0-alpha.0

package/src/index.js

@@ -11,6 +11,7 @@ import { listAll, listPage, iterPages } from './pagination.js';
 import { createSSEConnection } from './sse.js';
 import {
   discoverServices,
+  discardService,
   serve,
   requestService,
 } from './services.js';
@@ -40,6 +41,14 @@ class PlaidClient {
     this.batchOperations = [];
     this.documentVersions = {};
     this.strictModeDocumentId = null;
+    // Ambient custom audit-log message applied to write requests; null = use
+    // the server's auto-generated description. See setAuditMessage / withAuditMessage.
+    this.auditMessage = null;
+    // Optional callback fired once (per client) when any request returns HTTP
+    // 401 — i.e. the token is missing/expired/invalid. Apps use it to discard
+    // the stored token and route back to login. See makeRequest in http.js.
+    this.onAuthError = options.onAuthError || null;
+    this._authErrorFired = false;
 
     // --- API Bundles ---
 
@@ -50,25 +59,40 @@ class PlaidClient {
        * @param {Array} tokens - The tokens to link
        * @param {any} [metadata] - Metadata for the link. Omit to leave unset; pass null to send JSON null.
        */
-      create: (vocabItem, tokens, metadata) =>
-        this._request('POST', '/api/v1/vocab-links', {
+      create: (vocabItem, tokens, metadata, auditMessage) =>
+        this._request('POST', '/api/v1/vocab-links', { auditMessage,
           body: bodyOf({ 'vocab-item': vocabItem, tokens, metadata }),
         }),
+      /**
+       * Create multiple vocab links in a single operation. Entries may
+       * reference different vocab items, but all tokens across the call must
+       * belong to one document.
+       * @param {Array<{vocabItem: string, tokens: string[], metadata?: any}>} body - The vocab links to create
+       * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
+       */
+      bulkCreate: (body, auditMessage) =>
+        this._request('POST', '/api/v1/vocab-links/bulk', { auditMessage, body }),
+      /**
+       * Delete multiple vocab links in a single operation. Provide an array of IDs.
+       * @param {string[]} body - The vocab link IDs to delete
+       */
+      bulkDelete: (body, auditMessage) =>
+        this._request('DELETE', '/api/v1/vocab-links/bulk', { auditMessage, body }),
       /**
        * Replace all metadata for a vocab link. The entire metadata map is replaced - existing metadata keys not included in the request will be removed.
        * @param {string} id - The resource ID
        * @param {any} body - The request body
        */
-      setMetadata: (id, body) =>
-        this._request('PUT', `/api/v1/vocab-links/${id}/metadata`, {
+      setMetadata: (id, body, auditMessage) =>
+        this._request('PUT', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a vocab link.
        * @param {string} id - The resource ID
        */
-      deleteMetadata: (id) =>
-        this._request('DELETE', `/api/v1/vocab-links/${id}/metadata`, {
+      deleteMetadata: (id, auditMessage) =>
+        this._request('DELETE', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -76,8 +100,8 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {any} body - The metadata patch
        */
-      patchMetadata: (id, body) =>
-        this._request('PATCH', `/api/v1/vocab-links/${id}/metadata`, {
+      patchMetadata: (id, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
@@ -93,8 +117,8 @@ class PlaidClient {
        * Delete a vocab link
        * @param {string} id - The resource ID
        */
-      delete: (id) =>
-        this._request('DELETE', `/api/v1/vocab-links/${id}`),
+      delete: (id, auditMessage) =>
+        this._request('DELETE', `/api/v1/vocab-links/${id}`, { auditMessage }),
     };
 
     this.vocabLayers = {
@@ -112,15 +136,15 @@ class PlaidClient {
        * Delete a vocab layer.
        * @param {string} id - The resource ID
        */
-      delete: (id) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${id}`),
+      delete: (id, auditMessage) =>
+        this._request('DELETE', `/api/v1/vocab-layers/${id}`, { auditMessage }),
       /**
        * Update a vocab layer's name.
        * @param {string} id - The resource ID
        * @param {string} name - The name
        */
-      update: (id, name) =>
-        this._request('PATCH', `/api/v1/vocab-layers/${id}`, {
+      update: (id, name, auditMessage) =>
+        this._request('PATCH', `/api/v1/vocab-layers/${id}`, { auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -130,8 +154,8 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (id, namespace, configKey, configValue) =>
-        this._request('PUT', `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`, {
+      setConfig: (id, namespace, configKey, configValue, auditMessage) =>
+        this._request('PUT', `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`, { auditMessage,
           rawBody: configValue, skipResponseTransform: true,
         }),
       /**
@@ -140,8 +164,8 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        */
-      deleteConfig: (id, namespace, configKey) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`, {
+      deleteConfig: (id, namespace, configKey, auditMessage) =>
+        this._request('DELETE', `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -176,8 +200,8 @@ class PlaidClient {
        * Create a new vocab layer. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
        */
-      create: (name) =>
-        this._request('POST', '/api/v1/vocab-layers', {
+      create: (name, auditMessage) =>
+        this._request('POST', '/api/v1/vocab-layers', { auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -185,15 +209,15 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
-      addMaintainer: (id, userId) =>
-        this._request('POST', `/api/v1/vocab-layers/${id}/maintainers/${userId}`),
+      addMaintainer: (id, userId, auditMessage) =>
+        this._request('POST', `/api/v1/vocab-layers/${id}/maintainers/${userId}`, { auditMessage }),
       /**
        * Remove a user's maintainer privileges for this vocab layer.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
-      removeMaintainer: (id, userId) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${id}/maintainers/${userId}`),
+      removeMaintainer: (id, userId, auditMessage) =>
+        this._request('DELETE', `/api/v1/vocab-layers/${id}/maintainers/${userId}`, { auditMessage }),
     };
 
     this.relations = {
@@ -202,16 +226,16 @@ class PlaidClient {
        * @param {string} relationId - The relation ID
        * @param {any} body - The request body
        */
-      setMetadata: (relationId, body) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/metadata`, {
+      setMetadata: (relationId, body, auditMessage) =>
+        this._request('PUT', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a relation.
        * @param {string} relationId - The relation ID
        */
-      deleteMetadata: (relationId) =>
-        this._request('DELETE', `/api/v1/relations/${relationId}/metadata`, {
+      deleteMetadata: (relationId, auditMessage) =>
+        this._request('DELETE', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -219,8 +243,8 @@ class PlaidClient {
        * @param {string} relationId - The relation ID
        * @param {any} body - The metadata patch
        */
-      patchMetadata: (relationId, body) =>
-        this._request('PATCH', `/api/v1/relations/${relationId}/metadata`, {
+      patchMetadata: (relationId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
@@ -228,8 +252,8 @@ class PlaidClient {
        * @param {string} relationId - The relation ID
        * @param {string} spanId - The span ID
        */
-      setTarget: (relationId, spanId) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/target`, {
+      setTarget: (relationId, spanId, auditMessage) =>
+        this._request('PUT', `/api/v1/relations/${relationId}/target`, { auditMessage,
           body: bodyOf({ 'span-id': spanId }),
         }),
       /**
@@ -245,15 +269,15 @@ class PlaidClient {
        * Delete a relation.
        * @param {string} relationId - The relation ID
        */
-      delete: (relationId) =>
-        this._request('DELETE', `/api/v1/relations/${relationId}`),
+      delete: (relationId, auditMessage) =>
+        this._request('DELETE', `/api/v1/relations/${relationId}`, { auditMessage }),
       /**
        * Update a relation's value.
        * @param {string} relationId - The relation ID
        * @param {any} value - The value
        */
-      update: (relationId, value) =>
-        this._request('PATCH', `/api/v1/relations/${relationId}`, {
+      update: (relationId, value, auditMessage) =>
+        this._request('PATCH', `/api/v1/relations/${relationId}`, { auditMessage,
           body: bodyOf({ value }),
         }),
       /**
@@ -261,8 +285,8 @@ class PlaidClient {
        * @param {string} relationId - The relation ID
        * @param {string} spanId - The span ID
        */
-      setSource: (relationId, spanId) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/source`, {
+      setSource: (relationId, spanId, auditMessage) =>
+        this._request('PUT', `/api/v1/relations/${relationId}/source`, { auditMessage,
           body: bodyOf({ 'span-id': spanId }),
         }),
       /**
@@ -275,22 +299,23 @@ class PlaidClient {
        * @param {any} value - The value
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (layerId, sourceId, targetId, value, metadata) =>
-        this._request('POST', '/api/v1/relations', {
+      create: (layerId, sourceId, targetId, value, metadata, auditMessage) =>
+        this._request('POST', '/api/v1/relations', { auditMessage,
           body: bodyOf({ 'layer-id': layerId, 'source-id': sourceId, 'target-id': targetId, value, metadata }),
         }),
       /**
        * Create multiple relations in a single operation.
        * @param {Array} body - The request body
+       * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
-      bulkCreate: (body) =>
-        this._request('POST', '/api/v1/relations/bulk', { body }),
+      bulkCreate: (body, auditMessage) =>
+        this._request('POST', '/api/v1/relations/bulk', { auditMessage, body }),
       /**
        * Delete multiple relations in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
        */
-      bulkDelete: (body) =>
-        this._request('DELETE', '/api/v1/relations/bulk', { body }),
+      bulkDelete: (body, auditMessage) =>
+        this._request('DELETE', '/api/v1/relations/bulk', { auditMessage, body }),
     };
 
     this.spanLayers = {
@@ -301,8 +326,8 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (spanLayerId, namespace, configKey, configValue) =>
-        this._request('PUT', `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`, {
+      setConfig: (spanLayerId, namespace, configKey, configValue, auditMessage) =>
+        this._request('PUT', `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`, { auditMessage,
           rawBody: configValue, skipResponseTransform: true,
         }),
       /**
@@ -311,8 +336,8 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        */
-      deleteConfig: (spanLayerId, namespace, configKey) =>
-        this._request('DELETE', `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`, {
+      deleteConfig: (spanLayerId, namespace, configKey, auditMessage) =>
+        this._request('DELETE', `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -328,15 +353,15 @@ class PlaidClient {
        * Delete a span layer.
        * @param {string} spanLayerId - The span layer ID
        */
-      delete: (spanLayerId) =>
-        this._request('DELETE', `/api/v1/span-layers/${spanLayerId}`),
+      delete: (spanLayerId, auditMessage) =>
+        this._request('DELETE', `/api/v1/span-layers/${spanLayerId}`, { auditMessage }),
       /**
        * Update a span layer's name.
        * @param {string} spanLayerId - The span layer ID
        * @param {string} name - The name
        */
-      update: (spanLayerId, name) =>
-        this._request('PATCH', `/api/v1/span-layers/${spanLayerId}`, {
+      update: (spanLayerId, name, auditMessage) =>
+        this._request('PATCH', `/api/v1/span-layers/${spanLayerId}`, { auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -344,8 +369,8 @@ class PlaidClient {
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} name - The name
        */
-      create: (tokenLayerId, name) =>
-        this._request('POST', '/api/v1/span-layers', {
+      create: (tokenLayerId, name, auditMessage) =>
+        this._request('POST', '/api/v1/span-layers', { auditMessage,
           body: bodyOf({ 'token-layer-id': tokenLayerId, name }),
         }),
       /**
@@ -353,8 +378,8 @@ class PlaidClient {
        * @param {string} spanLayerId - The span layer ID
        * @param {string} direction - The direction ("up" or "down")
        */
-      shift: (spanLayerId, direction) =>
-        this._request('POST', `/api/v1/span-layers/${spanLayerId}/shift`, {
+      shift: (spanLayerId, direction, auditMessage) =>
+        this._request('POST', `/api/v1/span-layers/${spanLayerId}/shift`, { auditMessage,
           body: bodyOf({ direction }),
         }),
     };
@@ -365,8 +390,8 @@ class PlaidClient {
        * @param {string} spanId - The span ID
        * @param {Array} tokens - The tokens
        */
-      setTokens: (spanId, tokens) =>
-        this._request('PUT', `/api/v1/spans/${spanId}/tokens`, {
+      setTokens: (spanId, tokens, auditMessage) =>
+        this._request('PUT', `/api/v1/spans/${spanId}/tokens`, { auditMessage,
           body: bodyOf({ tokens }),
         }),
       /**
@@ -377,8 +402,8 @@ class PlaidClient {
        * @param {any} value - The value
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (spanLayerId, tokens, value, metadata) =>
-        this._request('POST', '/api/v1/spans', {
+      create: (spanLayerId, tokens, value, metadata, auditMessage) =>
+        this._request('POST', '/api/v1/spans', { auditMessage,
           body: bodyOf({ 'span-layer-id': spanLayerId, tokens, value, metadata }),
         }),
       /**
@@ -394,44 +419,45 @@ class PlaidClient {
        * Delete a span.
        * @param {string} spanId - The span ID
        */
-      delete: (spanId) =>
-        this._request('DELETE', `/api/v1/spans/${spanId}`),
+      delete: (spanId, auditMessage) =>
+        this._request('DELETE', `/api/v1/spans/${spanId}`, { auditMessage }),
       /**
        * Update a span's value.
        * @param {string} spanId - The span ID
        * @param {any} value - The value
        */
-      update: (spanId, value) =>
-        this._request('PATCH', `/api/v1/spans/${spanId}`, {
+      update: (spanId, value, auditMessage) =>
+        this._request('PATCH', `/api/v1/spans/${spanId}`, { auditMessage,
           body: bodyOf({ value }),
         }),
       /**
        * Create multiple spans in a single operation.
        * @param {Array} body - The request body
+       * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
-      bulkCreate: (body) =>
-        this._request('POST', '/api/v1/spans/bulk', { body }),
+      bulkCreate: (body, auditMessage) =>
+        this._request('POST', '/api/v1/spans/bulk', { auditMessage, body }),
       /**
        * Delete multiple spans in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
        */
-      bulkDelete: (body) =>
-        this._request('DELETE', '/api/v1/spans/bulk', { body }),
+      bulkDelete: (body, auditMessage) =>
+        this._request('DELETE', '/api/v1/spans/bulk', { auditMessage, body }),
       /**
        * Replace all metadata for a span.
        * @param {string} spanId - The span ID
        * @param {any} body - The request body
        */
-      setMetadata: (spanId, body) =>
-        this._request('PUT', `/api/v1/spans/${spanId}/metadata`, {
+      setMetadata: (spanId, body, auditMessage) =>
+        this._request('PUT', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a span.
        * @param {string} spanId - The span ID
        */
-      deleteMetadata: (spanId) =>
-        this._request('DELETE', `/api/v1/spans/${spanId}/metadata`, {
+      deleteMetadata: (spanId, auditMessage) =>
+        this._request('DELETE', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -439,8 +465,8 @@ class PlaidClient {
        * @param {string} spanId - The span ID
        * @param {any} body - The metadata patch
        */
-      patchMetadata: (spanId, body) =>
-        this._request('PATCH', `/api/v1/spans/${spanId}/metadata`, {
+      patchMetadata: (spanId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
     };
@@ -451,8 +477,8 @@ class PlaidClient {
        * changes are rolled back.
        * @param {Array} body - The request body
        */
-      submit: (body) =>
-        this._request('POST', '/api/v1/batch', {
+      submit: (body, auditMessage) =>
+        this._request('POST', '/api/v1/batch', { auditMessage,
           body, noBatch: true,
         }),
     };
@@ -463,16 +489,16 @@ class PlaidClient {
        * @param {string} textId - The text ID
        * @param {any} body - The request body
        */
-      setMetadata: (textId, body) =>
-        this._request('PUT', `/api/v1/texts/${textId}/metadata`, {
+      setMetadata: (textId, body, auditMessage) =>
+        this._request('PUT', `/api/v1/texts/${textId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a text.
        * @param {string} textId - The text ID
        */
-      deleteMetadata: (textId) =>
-        this._request('DELETE', `/api/v1/texts/${textId}/metadata`, {
+      deleteMetadata: (textId, auditMessage) =>
+        this._request('DELETE', `/api/v1/texts/${textId}/metadata`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -480,8 +506,8 @@ class PlaidClient {
        * @param {string} textId - The text ID
        * @param {any} body - The metadata patch
        */
-      patchMetadata: (textId, body) =>
-        this._request('PATCH', `/api/v1/texts/${textId}/metadata`, {
+      patchMetadata: (textId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/texts/${textId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
@@ -492,8 +518,8 @@ class PlaidClient {
        * @param {string} body - The request body
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (textLayerId, documentId, body, metadata) =>
-        this._request('POST', '/api/v1/texts', {
+      create: (textLayerId, documentId, body, metadata, auditMessage) =>
+        this._request('POST', '/api/v1/texts', { auditMessage,
           body: bodyOf({ 'text-layer-id': textLayerId, 'document-id': documentId, body, metadata }),
         }),
       /**
@@ -509,8 +535,8 @@ class PlaidClient {
        * Delete a text and all dependent data.
        * @param {string} textId - The text ID
        */
-      delete: (textId) =>
-        this._request('DELETE', `/api/v1/texts/${textId}`),
+      delete: (textId, auditMessage) =>
+        this._request('DELETE', `/api/v1/texts/${textId}`, { auditMessage }),
       /**
        * Update a text's body. A diff is computed and token indices are updated
        * so that tokens remain intact. Alternatively, `body` can be a list of
@@ -518,8 +544,8 @@ class PlaidClient {
        * @param {string} textId - The text ID
        * @param {any} body - The request body
        */
-      update: (textId, body) =>
-        this._request('PATCH', `/api/v1/texts/${textId}`, {
+      update: (textId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/texts/${textId}`, { auditMessage,
           body: bodyOf({ body }),
         }),
     };
@@ -563,8 +589,8 @@ class PlaidClient {
        * @param {string} password - The password
        * @param {boolean} isAdmin - Whether the user is an admin
        */
-      create: (username, password, isAdmin) =>
-        this._request('POST', '/api/v1/users', {
+      create: (username, password, isAdmin, auditMessage) =>
+        this._request('POST', '/api/v1/users', { auditMessage,
           body: bodyOf({ username, password, 'is-admin': isAdmin }),
         }),
       /**
@@ -597,16 +623,16 @@ class PlaidClient {
        * Reversible via activate(), which restores login only.
        * @param {string} id - The resource ID
        */
-      delete: (id) =>
-        this._request('DELETE', `/api/v1/users/${id}`),
+      delete: (id, auditMessage) =>
+        this._request('DELETE', `/api/v1/users/${id}`, { auditMessage }),
       /**
        * Reactivate a deactivated user, restoring their ability to log in.
        * Project memberships, vocab maintainerships, and API tokens removed
        * at deactivation are NOT restored — re-grant them deliberately.
        * @param {string} id - The resource ID
        */
-      activate: (id) =>
-        this._request('POST', `/api/v1/users/${id}/activate`),
+      activate: (id, auditMessage) =>
+        this._request('POST', `/api/v1/users/${id}/activate`, { auditMessage }),
       /**
        * Modify a user. Admins may change the username, password, and admin
        * status of any user. All other users may only modify their own username
@@ -616,8 +642,8 @@ class PlaidClient {
        * @param {string} [username] - New username
        * @param {boolean} [isAdmin] - New admin status
        */
-      update: (id, password, username, isAdmin) =>
-        this._request('PATCH', `/api/v1/users/${id}`, {
+      update: (id, password, username, isAdmin, auditMessage) =>
+        this._request('PATCH', `/api/v1/users/${id}`, { auditMessage,
           body: bodyOf({ password, username, 'is-admin': isAdmin }),
         }),
     };
@@ -661,8 +687,8 @@ class PlaidClient {
        * @param {string} name - A human label, e.g. "Stanza Parser"
        * @returns {Promise<{id: string, name: string, token: string}>}
        */
-      create: (userId, name) =>
-        this._request('POST', `/api/v1/users/${userId}/tokens`, {
+      create: (userId, name, auditMessage) =>
+        this._request('POST', `/api/v1/users/${userId}/tokens`, { auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -670,8 +696,8 @@ class PlaidClient {
        * @param {string} userId - The user ID who owns the token
        * @param {string} tokenId - The token ID to revoke
        */
-      revoke: (userId, tokenId) =>
-        this._request('DELETE', `/api/v1/users/${userId}/tokens/${tokenId}`),
+      revoke: (userId, tokenId, auditMessage) =>
+        this._request('DELETE', `/api/v1/users/${userId}/tokens/${tokenId}`, { auditMessage }),
     };
 
     this.tokenLayers = {
@@ -680,8 +706,8 @@ class PlaidClient {
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} direction - The direction ("up" or "down")
        */
-      shift: (tokenLayerId, direction) =>
-        this._request('POST', `/api/v1/token-layers/${tokenLayerId}/shift`, {
+      shift: (tokenLayerId, direction, auditMessage) =>
+        this._request('POST', `/api/v1/token-layers/${tokenLayerId}/shift`, { auditMessage,
           body: bodyOf({ direction }),
         }),
       /**
@@ -691,8 +717,8 @@ class PlaidClient {
        * @param {string} [overlapMode] - Per-layer, immutable token invariant: "any" (default), "non-overlapping", or "partitioning". On partitioning layers, single token create/update/delete are rejected; use bulkCreate plus split/merge/shift.
        * @param {string} [parentTokenLayerId] - Optional immutable parent token layer. Tokens in this layer must nest within a parent-layer token; the parent layer must be in the same text layer and be "non-overlapping" or "partitioning" (an "any" parent is rejected). A nested layer may be "any" or "non-overlapping" but not "partitioning" (partitioning is only for root layers), e.g. words (non-overlapping, parent=sentences) within sentences (partitioning).
        */
-      create: (textLayerId, name, overlapMode, parentTokenLayerId) =>
-        this._request('POST', '/api/v1/token-layers', {
+      create: (textLayerId, name, overlapMode, parentTokenLayerId, auditMessage) =>
+        this._request('POST', '/api/v1/token-layers', { auditMessage,
           body: bodyOf({ 'text-layer-id': textLayerId, name, 'overlap-mode': overlapMode, 'parent-token-layer-id': parentTokenLayerId }),
         }),
       /**
@@ -702,8 +728,8 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (tokenLayerId, namespace, configKey, configValue) =>
-        this._request('PUT', `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`, {
+      setConfig: (tokenLayerId, namespace, configKey, configValue, auditMessage) =>
+        this._request('PUT', `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`, { auditMessage,
           rawBody: configValue, skipResponseTransform: true,
         }),
       /**
@@ -712,8 +738,8 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        */
-      deleteConfig: (tokenLayerId, namespace, configKey) =>
-        this._request('DELETE', `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`, {
+      deleteConfig: (tokenLayerId, namespace, configKey, auditMessage) =>
+        this._request('DELETE', `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -729,15 +755,15 @@ class PlaidClient {
        * Delete a token layer.
        * @param {string} tokenLayerId - The token layer ID
        */
-      delete: (tokenLayerId) =>
-        this._request('DELETE', `/api/v1/token-layers/${tokenLayerId}`),
+      delete: (tokenLayerId, auditMessage) =>
+        this._request('DELETE', `/api/v1/token-layers/${tokenLayerId}`, { auditMessage }),
       /**
        * Update a token layer's name.
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} name - The name
        */
-      update: (tokenLayerId, name) =>
-        this._request('PATCH', `/api/v1/token-layers/${tokenLayerId}`, {
+      update: (tokenLayerId, name, auditMessage) =>
+        this._request('PATCH', `/api/v1/token-layers/${tokenLayerId}`, { auditMessage,
           body: bodyOf({ name }),
         }),
     };
@@ -756,14 +782,14 @@ class PlaidClient {
        * Acquire or refresh a document lock
        * @param {string} documentId - The document ID
        */
-      acquireLock: (documentId) =>
-        this._request('POST', `/api/v1/documents/${documentId}/lock`),
+      acquireLock: (documentId, auditMessage) =>
+        this._request('POST', `/api/v1/documents/${documentId}/lock`, { auditMessage }),
       /**
        * Release a document lock
        * @param {string} documentId - The document ID
        */
-      releaseLock: (documentId) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/lock`),
+      releaseLock: (documentId, auditMessage) =>
+        this._request('DELETE', `/api/v1/documents/${documentId}/lock`, { auditMessage }),
       /**
        * Get media file for a document
        * @param {string} documentId - The document ID
@@ -780,10 +806,10 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        * @param {File} file - The file to upload
        */
-      uploadMedia: (documentId, file) => {
+      uploadMedia: (documentId, file, auditMessage) => {
         const fd = new FormData();
         fd.append('file', file);
-        return this._request('PUT', `/api/v1/documents/${documentId}/media`, {
+        return this._request('PUT', `/api/v1/documents/${documentId}/media`, { auditMessage,
           body: fd, formData: true, noBatch: true,
         });
       },
@@ -791,8 +817,8 @@ class PlaidClient {
        * Delete media file for a document
        * @param {string} documentId - The document ID
        */
-      deleteMedia: (documentId) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/media`, {
+      deleteMedia: (documentId, auditMessage) =>
+        this._request('DELETE', `/api/v1/documents/${documentId}/media`, { auditMessage,
           noBatch: true,
         }),
       /**
@@ -800,16 +826,16 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        * @param {any} body - The request body
        */
-      setMetadata: (documentId, body) =>
-        this._request('PUT', `/api/v1/documents/${documentId}/metadata`, {
+      setMetadata: (documentId, body, auditMessage) =>
+        this._request('PUT', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a document.
        * @param {string} documentId - The document ID
        */
-      deleteMetadata: (documentId) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/metadata`, {
+      deleteMetadata: (documentId, auditMessage) =>
+        this._request('DELETE', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -817,8 +843,8 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        * @param {any} body - The metadata patch
        */
-      patchMetadata: (documentId, body) =>
-        this._request('PATCH', `/api/v1/documents/${documentId}/metadata`, {
+      patchMetadata: (documentId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
@@ -848,15 +874,15 @@ class PlaidClient {
        * Delete a document and all data contained.
        * @param {string} documentId - The document ID
        */
-      delete: (documentId) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}`),
+      delete: (documentId, auditMessage) =>
+        this._request('DELETE', `/api/v1/documents/${documentId}`, { auditMessage }),
       /**
        * Update a document's name.
        * @param {string} documentId - The document ID
        * @param {string} name - The name
        */
-      update: (documentId, name) =>
-        this._request('PATCH', `/api/v1/documents/${documentId}`, {
+      update: (documentId, name, auditMessage) =>
+        this._request('PATCH', `/api/v1/documents/${documentId}`, { auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -865,8 +891,8 @@ class PlaidClient {
        * @param {string} name - The name
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (projectId, name, metadata) =>
-        this._request('POST', '/api/v1/documents', {
+      create: (projectId, name, metadata, auditMessage) =>
+        this._request('POST', '/api/v1/documents', { auditMessage,
           body: bodyOf({ 'project-id': projectId, name, metadata }),
         }),
     };
@@ -877,29 +903,29 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
-      addWriter: (id, userId) =>
-        this._request('POST', `/api/v1/projects/${id}/writers/${userId}`),
+      addWriter: (id, userId, auditMessage) =>
+        this._request('POST', `/api/v1/projects/${id}/writers/${userId}`, { auditMessage }),
       /**
        * Remove a user's writer privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
-      removeWriter: (id, userId) =>
-        this._request('DELETE', `/api/v1/projects/${id}/writers/${userId}`),
+      removeWriter: (id, userId, auditMessage) =>
+        this._request('DELETE', `/api/v1/projects/${id}/writers/${userId}`, { auditMessage }),
       /**
        * Set a user's access level to read-only for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
-      addReader: (id, userId) =>
-        this._request('POST', `/api/v1/projects/${id}/readers/${userId}`),
+      addReader: (id, userId, auditMessage) =>
+        this._request('POST', `/api/v1/projects/${id}/readers/${userId}`, { auditMessage }),
       /**
        * Remove a user's reader privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
-      removeReader: (id, userId) =>
-        this._request('DELETE', `/api/v1/projects/${id}/readers/${userId}`),
+      removeReader: (id, userId, auditMessage) =>
+        this._request('DELETE', `/api/v1/projects/${id}/readers/${userId}`, { auditMessage }),
       /**
        * Set a configuration value for a project in an editor namespace.
        * @param {string} id - The resource ID
@@ -907,8 +933,8 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (id, namespace, configKey, configValue) =>
-        this._request('PUT', `/api/v1/projects/${id}/config/${namespace}/${configKey}`, {
+      setConfig: (id, namespace, configKey, configValue, auditMessage) =>
+        this._request('PUT', `/api/v1/projects/${id}/config/${namespace}/${configKey}`, { auditMessage,
           rawBody: configValue, skipResponseTransform: true,
         }),
       /**
@@ -917,8 +943,8 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        */
-      deleteConfig: (id, namespace, configKey) =>
-        this._request('DELETE', `/api/v1/projects/${id}/config/${namespace}/${configKey}`, {
+      deleteConfig: (id, namespace, configKey, auditMessage) =>
+        this._request('DELETE', `/api/v1/projects/${id}/config/${namespace}/${configKey}`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -926,15 +952,15 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
-      addMaintainer: (id, userId) =>
-        this._request('POST', `/api/v1/projects/${id}/maintainers/${userId}`),
+      addMaintainer: (id, userId, auditMessage) =>
+        this._request('POST', `/api/v1/projects/${id}/maintainers/${userId}`, { auditMessage }),
       /**
        * Remove a user's maintainer privileges for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
-      removeMaintainer: (id, userId) =>
-        this._request('DELETE', `/api/v1/projects/${id}/maintainers/${userId}`),
+      removeMaintainer: (id, userId, auditMessage) =>
+        this._request('DELETE', `/api/v1/projects/${id}/maintainers/${userId}`, { auditMessage }),
       /**
        * Get audit log for a project. Transparently follows pagination cursors
        * and returns the full flat array.
@@ -953,15 +979,15 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {string} vocabId - The vocab layer ID
        */
-      linkVocab: (id, vocabId) =>
-        this._request('POST', `/api/v1/projects/${id}/vocabs/${vocabId}`),
+      linkVocab: (id, vocabId, auditMessage) =>
+        this._request('POST', `/api/v1/projects/${id}/vocabs/${vocabId}`, { auditMessage }),
       /**
        * Unlink a vocabulary from a project.
        * @param {string} id - The resource ID
        * @param {string} vocabId - The vocab layer ID
        */
-      unlinkVocab: (id, vocabId) =>
-        this._request('DELETE', `/api/v1/projects/${id}/vocabs/${vocabId}`),
+      unlinkVocab: (id, vocabId, auditMessage) =>
+        this._request('DELETE', `/api/v1/projects/${id}/vocabs/${vocabId}`, { auditMessage }),
       /**
        * Get a project by ID. To fetch the project's documents, use
        * listDocuments(id) — the include-documents flag has been removed.
@@ -1011,18 +1037,25 @@ class PlaidClient {
       iterDocuments: (id, { pageSize } = {}) =>
         iterPages(this, `/api/v1/projects/${id}/documents`, { pageSize }),
       /**
-       * Delete a project.
+       * Delete a project and everything in it. This is irrecoverable.
+       *
+       * For a large project this can take a long time, so the client's
+       * per-request timeout is DISABLED by default. Pass `{ timeout }` to
+       * impose a finite bound.
        * @param {string} id - The resource ID
+       * @param {string} [auditMessage] - Custom audit-log message
+       * @param {object} [options]
+       * @param {number} [options.timeout=0] - Per-request timeout in ms (0/null disables)
        */
-      delete: (id) =>
-        this._request('DELETE', `/api/v1/projects/${id}`),
+      delete: (id, auditMessage, { timeout = 0 } = {}) =>
+        this._request('DELETE', `/api/v1/projects/${id}`, { auditMessage, timeout }),
       /**
        * Update a project's name.
        * @param {string} id - The resource ID
        * @param {string} name - The name
        */
-      update: (id, name) =>
-        this._request('PATCH', `/api/v1/projects/${id}`, {
+      update: (id, name, auditMessage) =>
+        this._request('PATCH', `/api/v1/projects/${id}`, { auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -1057,8 +1090,8 @@ class PlaidClient {
        * Create a new project. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
        */
-      create: (name) =>
-        this._request('POST', '/api/v1/projects', {
+      create: (name, auditMessage) =>
+        this._request('POST', '/api/v1/projects', { auditMessage,
           body: bodyOf({ name }),
         }),
     };
@@ -1071,8 +1104,8 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (textLayerId, namespace, configKey, configValue) =>
-        this._request('PUT', `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`, {
+      setConfig: (textLayerId, namespace, configKey, configValue, auditMessage) =>
+        this._request('PUT', `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`, { auditMessage,
           rawBody: configValue, skipResponseTransform: true,
         }),
       /**
@@ -1081,8 +1114,8 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        */
-      deleteConfig: (textLayerId, namespace, configKey) =>
-        this._request('DELETE', `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`, {
+      deleteConfig: (textLayerId, namespace, configKey, auditMessage) =>
+        this._request('DELETE', `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -1098,15 +1131,15 @@ class PlaidClient {
        * Delete a text layer.
        * @param {string} textLayerId - The text layer ID
        */
-      delete: (textLayerId) =>
-        this._request('DELETE', `/api/v1/text-layers/${textLayerId}`),
+      delete: (textLayerId, auditMessage) =>
+        this._request('DELETE', `/api/v1/text-layers/${textLayerId}`, { auditMessage }),
       /**
        * Update a text layer's name.
        * @param {string} textLayerId - The text layer ID
        * @param {string} name - The name
        */
-      update: (textLayerId, name) =>
-        this._request('PATCH', `/api/v1/text-layers/${textLayerId}`, {
+      update: (textLayerId, name, auditMessage) =>
+        this._request('PATCH', `/api/v1/text-layers/${textLayerId}`, { auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -1114,8 +1147,8 @@ class PlaidClient {
        * @param {string} textLayerId - The text layer ID
        * @param {string} direction - The direction ("up" or "down")
        */
-      shift: (textLayerId, direction) =>
-        this._request('POST', `/api/v1/text-layers/${textLayerId}/shift`, {
+      shift: (textLayerId, direction, auditMessage) =>
+        this._request('POST', `/api/v1/text-layers/${textLayerId}/shift`, { auditMessage,
           body: bodyOf({ direction }),
         }),
       /**
@@ -1123,8 +1156,8 @@ class PlaidClient {
        * @param {string} projectId - The project ID
        * @param {string} name - The name
        */
-      create: (projectId, name) =>
-        this._request('POST', '/api/v1/text-layers', {
+      create: (projectId, name, auditMessage) =>
+        this._request('POST', '/api/v1/text-layers', { auditMessage,
           body: bodyOf({ 'project-id': projectId, name }),
         }),
     };
@@ -1135,16 +1168,16 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {any} body - The request body
        */
-      setMetadata: (id, body) =>
-        this._request('PUT', `/api/v1/vocab-items/${id}/metadata`, {
+      setMetadata: (id, body, auditMessage) =>
+        this._request('PUT', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a vocab item.
        * @param {string} id - The resource ID
        */
-      deleteMetadata: (id) =>
-        this._request('DELETE', `/api/v1/vocab-items/${id}/metadata`, {
+      deleteMetadata: (id, auditMessage) =>
+        this._request('DELETE', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -1152,8 +1185,8 @@ class PlaidClient {
        * @param {string} id - The resource ID
        * @param {any} body - The metadata patch
        */
-      patchMetadata: (id, body) =>
-        this._request('PATCH', `/api/v1/vocab-items/${id}/metadata`, {
+      patchMetadata: (id, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
@@ -1162,10 +1195,24 @@ class PlaidClient {
        * @param {string} form - The vocab item form
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (vocabLayerId, form, metadata) =>
-        this._request('POST', '/api/v1/vocab-items', {
+      create: (vocabLayerId, form, metadata, auditMessage) =>
+        this._request('POST', '/api/v1/vocab-items', { auditMessage,
           body: bodyOf({ 'vocab-layer-id': vocabLayerId, form, metadata }),
         }),
+      /**
+       * Create multiple vocab items in a single operation. Entries may target
+       * different vocab layers; the user must have write access to each.
+       * @param {Array<{vocabLayerId: string, form: string, metadata?: any}>} body - The vocab items to create
+       */
+      bulkCreate: (body, auditMessage) =>
+        this._request('POST', '/api/v1/vocab-items/bulk', { auditMessage, body }),
+      /**
+       * Delete multiple vocab items in a single operation. Each item's
+       * descendant vocab links are deleted too. Provide an array of IDs.
+       * @param {string[]} body - The vocab item IDs to delete
+       */
+      bulkDelete: (body, auditMessage) =>
+        this._request('DELETE', '/api/v1/vocab-items/bulk', { auditMessage, body }),
       /**
        * Get a vocab item by ID
        * @param {string} id - The resource ID
@@ -1179,15 +1226,15 @@ class PlaidClient {
        * Delete a vocab item
        * @param {string} id - The resource ID
        */
-      delete: (id) =>
-        this._request('DELETE', `/api/v1/vocab-items/${id}`),
+      delete: (id, auditMessage) =>
+        this._request('DELETE', `/api/v1/vocab-items/${id}`, { auditMessage }),
       /**
        * Update a vocab item's form
        * @param {string} id - The resource ID
        * @param {string} form - The vocab item form
        */
-      update: (id, form) =>
-        this._request('PATCH', `/api/v1/vocab-items/${id}`, {
+      update: (id, form, auditMessage) =>
+        this._request('PATCH', `/api/v1/vocab-items/${id}`, { auditMessage,
           body: bodyOf({ form }),
         }),
     };
@@ -1198,8 +1245,8 @@ class PlaidClient {
        * @param {string} relationLayerId - The relation layer ID
        * @param {string} direction - The direction ("up" or "down")
        */
-      shift: (relationLayerId, direction) =>
-        this._request('POST', `/api/v1/relation-layers/${relationLayerId}/shift`, {
+      shift: (relationLayerId, direction, auditMessage) =>
+        this._request('POST', `/api/v1/relation-layers/${relationLayerId}/shift`, { auditMessage,
           body: bodyOf({ direction }),
         }),
       /**
@@ -1207,8 +1254,8 @@ class PlaidClient {
        * @param {string} spanLayerId - The span layer ID
        * @param {string} name - The name
        */
-      create: (spanLayerId, name) =>
-        this._request('POST', '/api/v1/relation-layers', {
+      create: (spanLayerId, name, auditMessage) =>
+        this._request('POST', '/api/v1/relation-layers', { auditMessage,
           body: bodyOf({ 'span-layer-id': spanLayerId, name }),
         }),
       /**
@@ -1218,8 +1265,8 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (relationLayerId, namespace, configKey, configValue) =>
-        this._request('PUT', `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`, {
+      setConfig: (relationLayerId, namespace, configKey, configValue, auditMessage) =>
+        this._request('PUT', `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`, { auditMessage,
           rawBody: configValue, skipResponseTransform: true,
         }),
       /**
@@ -1228,8 +1275,8 @@ class PlaidClient {
        * @param {string} namespace - The config namespace
        * @param {string} configKey - The config key
        */
-      deleteConfig: (relationLayerId, namespace, configKey) =>
-        this._request('DELETE', `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`, {
+      deleteConfig: (relationLayerId, namespace, configKey, auditMessage) =>
+        this._request('DELETE', `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -1245,15 +1292,15 @@ class PlaidClient {
        * Delete a relation layer.
        * @param {string} relationLayerId - The relation layer ID
        */
-      delete: (relationLayerId) =>
-        this._request('DELETE', `/api/v1/relation-layers/${relationLayerId}`),
+      delete: (relationLayerId, auditMessage) =>
+        this._request('DELETE', `/api/v1/relation-layers/${relationLayerId}`, { auditMessage }),
       /**
        * Update a relation layer's name.
        * @param {string} relationLayerId - The relation layer ID
        * @param {string} name - The name
        */
-      update: (relationLayerId, name) =>
-        this._request('PATCH', `/api/v1/relation-layers/${relationLayerId}`, {
+      update: (relationLayerId, name, auditMessage) =>
+        this._request('PATCH', `/api/v1/relation-layers/${relationLayerId}`, { auditMessage,
           body: bodyOf({ name }),
         }),
     };
@@ -1277,8 +1324,8 @@ class PlaidClient {
        * @param {number} [precedence] - Ordering precedence
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
-      create: (tokenLayerId, text, begin, end, precedence, metadata) =>
-        this._request('POST', '/api/v1/tokens', {
+      create: (tokenLayerId, text, begin, end, precedence, metadata, auditMessage) =>
+        this._request('POST', '/api/v1/tokens', { auditMessage,
           body: bodyOf({ 'token-layer-id': tokenLayerId, text, begin, end, precedence, metadata }),
         }),
       /**
@@ -1295,8 +1342,8 @@ class PlaidClient {
        * have no remaining tokens, the span will also be deleted.
        * @param {string} tokenId - The token ID
        */
-      delete: (tokenId) =>
-        this._request('DELETE', `/api/v1/tokens/${tokenId}`),
+      delete: (tokenId, auditMessage) =>
+        this._request('DELETE', `/api/v1/tokens/${tokenId}`, { auditMessage }),
       /**
        * Update a token.
        * @param {string} tokenId - The token ID
@@ -1307,30 +1354,31 @@ class PlaidClient {
        *   CLEAR it (revert to no explicit ordering). bodyOf keeps null but
        *   drops undefined, so the three cases map correctly to the server.
        */
-      update: (tokenId, begin, end, precedence) =>
-        this._request('PATCH', `/api/v1/tokens/${tokenId}`, {
+      update: (tokenId, begin, end, precedence, auditMessage) =>
+        this._request('PATCH', `/api/v1/tokens/${tokenId}`, { auditMessage,
           body: bodyOf({ begin, end, precedence }),
         }),
       /**
        * Create multiple tokens in a single operation.
        * @param {Array} body - The request body
+       * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
-      bulkCreate: (body) =>
-        this._request('POST', '/api/v1/tokens/bulk', { body }),
+      bulkCreate: (body, auditMessage) =>
+        this._request('POST', '/api/v1/tokens/bulk', { auditMessage, body }),
       /**
        * Delete multiple tokens in a single operation. Provide an array of IDs.
        * @param {Array} body - The request body
        */
-      bulkDelete: (body) =>
-        this._request('DELETE', '/api/v1/tokens/bulk', { body }),
+      bulkDelete: (body, auditMessage) =>
+        this._request('DELETE', '/api/v1/tokens/bulk', { auditMessage, body }),
       /**
        * Split a token at a Unicode code-point offset. The original token becomes the
        * left half (keeps its ID, spans, vocab-links); the new right token's ID is returned.
        * @param {string} tokenId - The token ID
        * @param {number} position - Code-point offset to split at (strictly between begin and end)
        */
-      split: (tokenId, position) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/split`, {
+      split: (tokenId, position, auditMessage) =>
+        this._request('POST', `/api/v1/tokens/${tokenId}/split`, { auditMessage,
           body: bodyOf({ position }),
         }),
       /**
@@ -1341,8 +1389,8 @@ class PlaidClient {
        * @param {string} tokenId - The anchor token ID
        * @param {string} otherTokenId - The other token to merge in
        */
-      merge: (tokenId, otherTokenId) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/merge`, {
+      merge: (tokenId, otherTokenId, auditMessage) =>
+        this._request('POST', `/api/v1/tokens/${tokenId}/merge`, { auditMessage,
           body: bodyOf({ 'other-token-id': otherTokenId }),
         }),
       /**
@@ -1353,8 +1401,8 @@ class PlaidClient {
        * @param {number} [begin] - New start offset, inclusive (Unicode code points)
        * @param {number} [end] - New end offset, exclusive (Unicode code points)
        */
-      shift: (tokenId, begin, end) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/shift`, {
+      shift: (tokenId, begin, end, auditMessage) =>
+        this._request('POST', `/api/v1/tokens/${tokenId}/shift`, { auditMessage,
           body: bodyOf({ begin, end }),
         }),
       /**
@@ -1362,16 +1410,16 @@ class PlaidClient {
        * @param {string} tokenId - The token ID
        * @param {any} body - The request body
        */
-      setMetadata: (tokenId, body) =>
-        this._request('PUT', `/api/v1/tokens/${tokenId}/metadata`, {
+      setMetadata: (tokenId, body, auditMessage) =>
+        this._request('PUT', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
       /**
        * Remove all metadata from a token.
        * @param {string} tokenId - The token ID
        */
-      deleteMetadata: (tokenId) =>
-        this._request('DELETE', `/api/v1/tokens/${tokenId}/metadata`, {
+      deleteMetadata: (tokenId, auditMessage) =>
+        this._request('DELETE', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -1379,8 +1427,8 @@ class PlaidClient {
        * @param {string} tokenId - The token ID
        * @param {any} body - The metadata patch
        */
-      patchMetadata: (tokenId, body) =>
-        this._request('PATCH', `/api/v1/tokens/${tokenId}/metadata`, {
+      patchMetadata: (tokenId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
           rawBody: body, skipResponseTransform: true,
         }),
     };
@@ -1402,19 +1450,30 @@ class PlaidClient {
        * @param {any} data - The message data to send
        * @returns {Promise<any>} Response from the send operation
        */
-      sendMessage: (projectId, data) =>
-        this._request('POST', `/api/v1/projects/${projectId}/message`, {
+      sendMessage: (projectId, data, auditMessage) =>
+        this._request('POST', `/api/v1/projects/${projectId}/message`, { auditMessage,
           body: { body: data },
         }),
 
       /**
-       * Discover the services currently connected to a project (synchronous GET).
+       * Discover the services seen on a project (synchronous GET). Currently
+       * connected services carry `online: true`; previously-seen offline ones
+       * carry `online: false` plus a `lastSeenAt` stamp.
        * @param {string} projectId - The UUID of the project to query
-       * @param {number} [timeout] - Ignored; kept for back-compat
        * @returns {Promise<Array>} Array of discovered service information
        */
-      discoverServices: (projectId, timeout) =>
-        discoverServices(this, projectId, timeout),
+      discoverServices: (projectId) =>
+        discoverServices(this, projectId),
+
+      /**
+       * Forget a previously-seen (offline) service. Maintainer-only; 409 if
+       * the service is currently connected.
+       * @param {string} projectId - The UUID of the project
+       * @param {string} serviceId - The ID of the service to forget
+       * @returns {Promise<void>}
+       */
+      discardService: (projectId, serviceId) =>
+        discardService(this, projectId, serviceId),
 
       /**
        * Register as a service and handle incoming work requests.
@@ -1475,8 +1534,8 @@ class PlaidClient {
      *   For 'count': {return: 'count', count}. Entity cells are full entity objects
      *   (same shape as the GET endpoints).
      */
-    this.query = (body) =>
-      this._request('POST', '/api/v1/query', { body });
+    this.query = (body, auditMessage) =>
+      this._request('POST', '/api/v1/query', { auditMessage, body });
   }
 
   // --- Core methods ---
@@ -1499,10 +1558,62 @@ class PlaidClient {
     this.strictModeDocumentId = null;
   }
 
+  /**
+   * Set a custom audit-log message applied to every subsequent write request,
+   * OVERRIDING the server's auto-generated description (e.g. "Patch metadata
+   * on span X"). The message may template the endpoint's own path/query/body
+   * params with `{param}` placeholders, resolved server-side — e.g.
+   * `"Approve span {spanId}"`. Placeholder names are case/separator-insensitive
+   * (`{spanId}` == `{span-id}` == `{span_id}`), so use the camelCase names this
+   * client uses. Applies to GET-less requests
+   * only, including every operation queued in a batch.
+   * @param {string} message - The custom message (template).
+   */
+  setAuditMessage(message) {
+    this.auditMessage = message;
+    return this;
+  }
+
+  /** Clear the ambient custom audit-log message (revert to auto-generated). */
+  clearAuditMessage() {
+    this.auditMessage = null;
+    return this;
+  }
+
+  /**
+   * Run `fn` with a custom audit-log message in effect, restoring the previous
+   * message afterward (supports nesting). Use it to scope ONE call (per-call
+   * precision) or MANY (a logical unit):
+   *
+   *   await client.withAuditMessage('Approve span {spanId}', () =>
+   *     client.spans.update(spanId, ...));
+   *
+   *   await client.withAuditMessage('Import sentence', async () => {
+   *     await client.tokens.create(...);
+   *     await client.spans.create(...);
+   *   });
+   *
+   * @param {string} message - The custom message (template).
+   * @param {() => (Promise<any>|any)} fn - The work to run with the message set.
+   * @returns {Promise<any>} Whatever `fn` resolves to.
+   */
+  async withAuditMessage(message, fn) {
+    const prev = this.auditMessage;
+    this.auditMessage = message;
+    try {
+      return await fn();
+    } finally {
+      this.auditMessage = prev;
+    }
+  }
+
   /** Begin a batch of operations. Subsequent API calls will be queued. */
   beginBatch() {
     this.isBatching = true;
     this.batchOperations = [];
+    // Strict mode stamps the expected document-version on the FIRST write of
+    // the batch only (see _request) — reset the marker per batch.
+    this.batchVersionStamped = false;
   }
 
   /**
@@ -1587,6 +1698,38 @@ class PlaidClient {
     return this.isBatching;
   }
 
+  /**
+   * Run `fn` with a batch open, then submit all queued ops as ONE atomic
+   * request — or abort the batch if `fn` throws, so a half-open batch can never
+   * silently swallow later non-batch calls. `fn` makes the (queued) client
+   * calls; it must NOT call submitBatch itself. Resolves to the batch results
+   * array (`[]` if `fn` queued nothing).
+   *
+   *   const [sentRes, wordRes] = await client.batched(async () => {
+   *     client.tokens.bulkCreate(sentenceOps);
+   *     client.tokens.bulkCreate(wordOps);
+   *   });
+   *
+   * Server-side a batch runs sequentially in one transaction (a child op sees
+   * parents created earlier in the same `fn`; any op's failure rolls the whole
+   * batch back). Not nestable. Named `batched()` because `client.batch` is the
+   * low-level batch resource.
+   * @param {() => (void | Promise<void>)} fn
+   * @returns {Promise<Array>}
+   */
+  async batched(fn) {
+    this.beginBatch();
+    try {
+      await fn();
+    } catch (e) {
+      // fn failed: drop the queued ops so the client leaves batch mode and
+      // later plain calls don't queue into a never-submitted batch.
+      if (this.isBatchMode()) this.abortBatch();
+      throw e;
+    }
+    return this.submitBatch();
+  }
+
   /**
    * Authenticate and return a new client instance with token. This is the
    * single auth entry point — there is no `client.login` resource.
@@ -1642,3 +1785,17 @@ export {
   buildDefaultValues,
   coerceParamValues,
 } from './serviceSchema.js';
+// Provenance: the cross-app convention for machine-provided vs human-labeled
+// information (flat prov/provSource/provConfirmed metadata; absence = human),
+// plus the machine-writer contract. See ./provenance.js and the manual,
+// "Provenance".
+export {
+  PROV,
+  PROV_STATES,
+  stampInferred,
+  confirmedInferred,
+  provState,
+  isProtected,
+  verifyOnEdit,
+  serviceSource,
+} from './provenance.js';