@larc-iu/plaid-client 0.1.0-alpha.8 → 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,27 +59,51 @@ 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,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a vocab link. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} id - The resource ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (id, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Get a vocab link by ID
        * @param {string} id - The resource ID
@@ -84,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 = {
@@ -103,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 }),
         }),
       /**
@@ -121,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,
         }),
       /**
@@ -131,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,
         }),
       /**
@@ -167,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 }),
         }),
       /**
@@ -176,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 = {
@@ -193,25 +226,34 @@ 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,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a relation. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} relationId - The relation ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (relationId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Update the target span of a relation.
        * @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 }),
         }),
       /**
@@ -227,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 }),
         }),
       /**
@@ -243,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 }),
         }),
       /**
@@ -257,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 = {
@@ -283,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,
         }),
       /**
@@ -293,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,
         }),
       /**
@@ -310,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 }),
         }),
       /**
@@ -326,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 }),
         }),
       /**
@@ -335,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 }),
         }),
     };
@@ -347,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 }),
         }),
       /**
@@ -359,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 }),
         }),
       /**
@@ -376,46 +419,56 @@ 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,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a span. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} spanId - The span ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (spanId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
+          rawBody: body, skipResponseTransform: true,
+        }),
     };
 
     this.batch = {
@@ -424,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,
         }),
     };
@@ -436,18 +489,27 @@ 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,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a text. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} textId - The text ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (textId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/texts/${textId}/metadata`, { auditMessage,
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Create a new text in a document's text layer. A text is a container for
        * one long string in `body` for a given layer.
@@ -456,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 }),
         }),
       /**
@@ -473,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
@@ -482,49 +544,53 @@ 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 }),
         }),
     };
 
     this.users = {
       /**
-       * List all users. Transparently follows pagination cursors and returns
-       * the full flat array.
+       * List (or search) users. Transparently follows pagination cursors and
+       * returns the full flat array. Admin-or-maintainer only.
        * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
-       * @param {string} [asOf] - Temporal query timestamp
+       * @param {object} [opts]
+       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
+       * @param {string} [opts.asOf] - Temporal query timestamp
        */
-      list: (asOf) =>
-        listAll(this, '/api/v1/users', { query: { 'as-of': asOf } }),
+      list: ({ q, asOf } = {}) =>
+        listAll(this, '/api/v1/users', { query: { q, 'as-of': asOf } }),
       /**
-       * Fetch a single page of users.
+       * Fetch a single page of users (optionally filtered by `q`).
        * @param {object} [opts]
+       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
        * @param {string} [opts.asOf] - Temporal query timestamp
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ limit, cursor, asOf } = {}) =>
-        listPage(this, '/api/v1/users', { limit, cursor, query: { 'as-of': asOf } }),
+      listPage: ({ q, limit, cursor, asOf } = {}) =>
+        listPage(this, '/api/v1/users', { limit, cursor, query: { q, 'as-of': asOf } }),
       /**
        * Async-iterate users page by page; yields each page's entries array.
        * @param {object} [opts]
+       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
        * @param {number} [opts.pageSize] - Per-request page size
        * @param {string} [opts.asOf] - Temporal query timestamp
        * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ pageSize, asOf } = {}) =>
-        iterPages(this, '/api/v1/users', { pageSize, query: { 'as-of': asOf } }),
+      iterPages: ({ q, pageSize, asOf } = {}) =>
+        iterPages(this, '/api/v1/users', { pageSize, query: { q, 'as-of': asOf } }),
       /**
        * Create a new user
        * @param {string} username - The username
        * @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 }),
         }),
       /**
@@ -550,11 +616,23 @@ class PlaidClient {
           queryParams: { 'as-of': asOf },
         }),
       /**
-       * Delete a user
+       * Deactivate a user. Users are never hard-deleted: deactivation
+       * rejects their logins and tokens, strips their project memberships
+       * and vocab maintainerships, and revokes their API tokens. The user
+       * stays visible in listings with a deactivated-at timestamp.
+       * 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, 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
@@ -564,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 }),
         }),
     };
@@ -609,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 }),
         }),
       /**
@@ -618,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 = {
@@ -628,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 }),
         }),
       /**
@@ -639,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 }),
         }),
       /**
@@ -650,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,
         }),
       /**
@@ -660,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,
         }),
       /**
@@ -677,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 }),
         }),
     };
@@ -704,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
@@ -728,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,
         });
       },
@@ -739,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,
         }),
       /**
@@ -748,18 +826,27 @@ 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,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a document. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} documentId - The document ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (documentId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Get audit log for a document. Transparently follows pagination cursors
        * and returns the full flat array.
@@ -787,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 }),
         }),
       /**
@@ -804,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 }),
         }),
     };
@@ -816,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
@@ -846,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,
         }),
       /**
@@ -856,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,
         }),
       /**
@@ -865,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.
@@ -892,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.
@@ -950,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 }),
         }),
       /**
@@ -996,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 }),
         }),
     };
@@ -1010,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,
         }),
       /**
@@ -1020,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,
         }),
       /**
@@ -1037,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 }),
         }),
       /**
@@ -1053,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 }),
         }),
       /**
@@ -1062,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 }),
         }),
     };
@@ -1074,28 +1168,51 @@ 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,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a vocab item. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} id - The resource ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (id, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
+          rawBody: body, skipResponseTransform: true,
+        }),
       /**
        * Create a new vocab item
        * @param {string} vocabLayerId - The vocab layer ID
        * @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
@@ -1109,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 }),
         }),
     };
@@ -1128,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 }),
         }),
       /**
@@ -1137,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 }),
         }),
       /**
@@ -1148,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,
         }),
       /**
@@ -1158,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,
         }),
       /**
@@ -1175,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 }),
         }),
     };
@@ -1194,15 +1311,21 @@ class PlaidClient {
        * using begin and end offsets. Tokens may be zero-width and may overlap.
        * For tokens sharing the same begin, precedence controls the linear
        * ordering.
+       *
+       * Offsets are 0-based indices in Unicode CODE POINTS (not UTF-16 code
+       * units): a supplementary-plane character (emoji, SMP script) is one
+       * position. JS strings are UTF-16, so do NOT use `str.length` /
+       * `str.substring` to compute offsets — count code points instead
+       * (e.g. `[...str].length`, or iterate with `codePointAt`).
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} text - The text ID
-       * @param {number} begin - Start offset (inclusive)
-       * @param {number} end - End offset (exclusive)
+       * @param {number} begin - Start offset, inclusive (Unicode code points)
+       * @param {number} end - End offset, exclusive (Unicode code points)
        * @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 }),
         }),
       /**
@@ -1219,42 +1342,43 @@ 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
-       * @param {number} [begin] - New start offset
-       * @param {number} [end] - New end offset
+       * @param {number} [begin] - New start offset, inclusive (Unicode code points)
+       * @param {number} [end] - New end offset, exclusive (Unicode code points)
        * @param {?number} [precedence] - Ordering precedence. Omit (undefined)
        *   to leave unchanged; pass a number to set; pass null explicitly to
        *   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 character offset. The original token becomes the left half
-       * (keeps its ID, spans, vocab-links); the new right token's ID is returned.
+       * 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 - Offset to split at (strictly between begin and end)
+       * @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 }),
         }),
       /**
@@ -1265,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 }),
         }),
       /**
@@ -1274,11 +1398,11 @@ class PlaidClient {
        * auto-adjusted to preserve the partition; on non-overlapping layers a shift that
        * would create an overlap is rejected.
        * @param {string} tokenId - The token ID
-       * @param {number} [begin] - New start offset
-       * @param {number} [end] - New end offset
+       * @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 }),
         }),
       /**
@@ -1286,18 +1410,27 @@ 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,
         }),
+      /**
+       * Patch (shallow-merge) metadata for a token. Keys present in the body are set or overwritten; keys not present are left untouched; a key whose value is null is deleted. Merging is top-level only (nested objects are replaced wholesale, not deep-merged), so a literal null cannot be stored as a value. An empty body changes no metadata.
+       * @param {string} tokenId - The token ID
+       * @param {any} body - The metadata patch
+       */
+      patchMetadata: (tokenId, body, auditMessage) =>
+        this._request('PATCH', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
+          rawBody: body, skipResponseTransform: true,
+        }),
     };
 
     this.messages = {
@@ -1317,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.
@@ -1366,8 +1510,8 @@ class PlaidClient {
      *   await client.query({
      *     find: ['?s1', '?s2'],
      *     where: [
-     *       ['span', '?s1', { layer: 'pos', value: 'NOUN' }],
-     *       ['span', '?s2', { layer: 'pos', value: 'VERB' }],
+     *       ['span', '?s1', { layer: posLayerId, value: 'NOUN' }],
+     *       ['span', '?s2', { layer: posLayerId, value: 'VERB' }],
      *       ['covers', '?s1', '?t1'], ['covers', '?s2', '?t2'],
      *       ['precedes', '?t1', '?t2'],
      *     ],
@@ -1375,13 +1519,23 @@ class PlaidClient {
      *     limit: 100,
      *   });
      *
-     * @param {Object} body - The query AST ({find, where, scope?, limit?, return?}).
+     * A `layer` is referenced by its id (its UUID) only — not by name or
+     * path. To match a layer by name, bind it with a `*-layer` clause (e.g.
+     * `['span-layer', '?sl', { name: 'pos' }]`) and use the variable.
+     *
+     * Optional keys: `scope` (restrict to projects by id, `{projectIds}`), `orderBy`
+     * (sort rows), and `bindings` (substitute `?name` placeholders with literals).
+     * `return` may also be an aggregate spec `{group, aggregates}`. See the query
+     * language reference.
+     *
+     * @param {Object} body - The query AST ({find, where, scope?, limit?, orderBy?,
+     *   return?, bindings?}).
      * @returns {Promise<Object>} For 'ids'/'entities': {columns, results, count, truncated}.
      *   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 ---
@@ -1404,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;
   }
 
   /**
@@ -1492,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.
@@ -1530,3 +1768,34 @@ class PlaidClient {
 
 export default PlaidClient;
 export { PlaidClient };
+
+// Unicode code-point helpers for text offsets (token begin/end are code-point
+// indices). See ./codepoint.js.
+export { cpLength, cpSlice, cpSlicer, utf16ToCp, cpToUtf16, cpIndexOf } from './codepoint.js';
+export { PLAID_NAMESPACE, ROLE_KEY, ROLES, readRole, findByRole } from './roles.js';
+// Service self-description helpers: filter discovered services by task, read a
+// service's parameter schema/summary, and build/coerce form values. See
+// ./serviceSchema.js.
+export {
+  TASKS,
+  servesTask,
+  filterServicesByTask,
+  getParamSchema,
+  getServiceSummary,
+  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';