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

package/src/index.js

@@ -2,19 +2,46 @@
  * plaid-client - JavaScript client for the Plaid annotation API
  */
 
-import { transformRequest, transformResponse } from './transforms.js';
+import { transformRequest, transformResponse } from "./transforms.js";
 import {
-  makeRequest, extractDocumentVersions, parseErrorBody, makeHttpError,
-  makeNetworkError, timeoutSignal, DEFAULT_TIMEOUT_MS,
-} from './http.js';
-import { listAll, listPage, iterPages } from './pagination.js';
-import { createSSEConnection } from './sse.js';
+  makeRequest,
+  extractDocumentVersions,
+  parseErrorBody,
+  makeHttpError,
+  makeNetworkError,
+  timeoutSignal,
+  retryWhileBusy,
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_BATCH_TIMEOUT_MS,
+} from "./http.js";
+import { listAll, listPage, iterPages } from "./pagination.js";
+import { createSSEConnection } from "./sse.js";
 import {
   discoverServices,
   discardService,
   serve,
   requestService,
-} from './services.js';
+  attachServiceRequest,
+  cancelServiceRequest,
+} from "./services.js";
+
+// Helper: normalize a document-read `layers` filter to the wire's
+// comma-separated form. Accepts an array of layer ids or a ready-made string;
+// anything empty becomes undefined so no `?layers=` is sent at all.
+function layersParam(layers) {
+  if (layers === undefined || layers === null) return undefined;
+  const joined = Array.isArray(layers) ? layers.join(",") : String(layers);
+  return joined.length > 0 ? joined : undefined;
+}
+
+// Helper: normalize an audit `opTypes` filter to the wire's comma-separated
+// form. Accepts an array of op types or a ready-made string; anything empty
+// becomes undefined so no `?op-types=` is sent at all.
+function opTypesParam(opTypes) {
+  if (opTypes === undefined || opTypes === null) return undefined;
+  const joined = Array.isArray(opTypes) ? opTypes.join(",") : String(opTypes);
+  return joined.length > 0 ? joined : undefined;
+}
 
 // Helper: build body object, filtering out undefined values
 function bodyOf(obj) {
@@ -25,6 +52,45 @@ function bodyOf(obj) {
   return result;
 }
 
+// POST to an endpoint that takes no Authorization header (login, invite lookup
+// and redemption). Deliberately does not go through PlaidClient._request: these
+// are called before any client exists, which is the whole point.
+async function anonymousPost(baseUrl, path, body, options = {}) {
+  const base = baseUrl.replace(/\/$/, "");
+  const url = `${base}${path}`;
+  try {
+    const fetchOptions = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    };
+    const signal = timeoutSignal(
+      options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
+    );
+    if (signal) fetchOptions.signal = signal;
+
+    const response = await fetch(url, fetchOptions);
+    if (!response.ok) {
+      throw makeHttpError(
+        response,
+        await parseErrorBody(response),
+        url,
+        "POST",
+      );
+    }
+    return transformResponse(await response.json());
+  } catch (error) {
+    if (error.status) throw error;
+    throw makeNetworkError(error, url, "POST");
+  }
+}
+
+/**
+ * The server's cap on operations per batch request (plaid.rest-api.v1.batch).
+ * A batch queued past it is submitted as consecutive requests.
+ */
+const MAX_BATCH_OPS = 1000;
+
 class PlaidClient {
   /**
    * Create a new PlaidClient instance
@@ -32,18 +98,33 @@ class PlaidClient {
    * @param {string} token - The authentication token
    * @param {object} [options] - Client options
    * @param {number} [options.timeout=30000] - Per-request timeout in ms (0 or null disables it)
+   * @param {number} [options.batchTimeout=180000] - Timeout for batch submissions in ms (0 or null disables it)
    */
   constructor(baseUrl, token, options = {}) {
-    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.baseUrl = baseUrl.replace(/\/$/, "");
     this.token = token;
-    this.timeout = options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS;
+    this.timeout =
+      options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS;
+    // Batch submissions get a longer budget than a single request. Aborting a
+    // batch does NOT stop the server: it keeps running the transaction and
+    // holding the single SQLite write lock, so a client that gives up early
+    // just adds a retry on top of a write that is still in progress. Falls
+    // back to an explicit `timeout` when one was given.
+    this.batchTimeout =
+      options.batchTimeout !== undefined
+        ? options.batchTimeout
+        : options.timeout !== undefined
+          ? options.timeout
+          : DEFAULT_BATCH_TIMEOUT_MS;
     this.isBatching = false;
     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;
+    // The open logical operation (audit-log group), or null. While set, every
+    // write is stamped with `?group-id=` (+ `group-message`) so the audit log
+    // folds them into ONE expandable entry. See beginOperation / withOperation.
+    // Shape: { id, message, depth, written, refined }.
+    this.operationGroup = 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.
@@ -60,8 +141,9 @@ class PlaidClient {
        * @param {any} [metadata] - Metadata for the link. Omit to leave unset; pass null to send JSON null.
        */
       create: (vocabItem, tokens, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/vocab-links', { auditMessage,
-          body: bodyOf({ 'vocab-item': vocabItem, tokens, metadata }),
+        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
@@ -71,28 +153,37 @@ class PlaidClient {
        * @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 }),
+        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 }),
+        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, auditMessage) =>
-        this._request('PUT', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        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, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
+        this._request("DELETE", `/api/v1/vocab-links/${id}/metadata`, {
+          auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -101,8 +192,10 @@ class PlaidClient {
        * @param {any} body - The metadata patch
        */
       patchMetadata: (id, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/vocab-links/${id}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PATCH", `/api/v1/vocab-links/${id}/metadata`, {
+          auditMessage,
+          rawBody: body,
+          skipResponseTransform: true,
         }),
       /**
        * Get a vocab link by ID
@@ -110,15 +203,15 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (id, asOf) =>
-        this._request('GET', `/api/v1/vocab-links/${id}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/vocab-links/${id}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a vocab link
        * @param {string} id - The resource ID
        */
       delete: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-links/${id}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/vocab-links/${id}`, { auditMessage }),
     };
 
     this.vocabLayers = {
@@ -129,22 +222,23 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (id, includeItems, asOf) =>
-        this._request('GET', `/api/v1/vocab-layers/${id}`, {
-          queryParams: { 'include-items': includeItems, 'as-of': asOf },
+        this._request("GET", `/api/v1/vocab-layers/${id}`, {
+          queryParams: { "include-items": includeItems, "as-of": asOf },
         }),
       /**
        * Delete a vocab layer.
        * @param {string} id - The resource ID
        */
       delete: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/vocab-layers/${id}`, { auditMessage,
+        this._request("PATCH", `/api/v1/vocab-layers/${id}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -155,9 +249,11 @@ class PlaidClient {
        * @param {any} configValue - Configuration value to set
        */
       setConfig: (id, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+        this._request(
+          "PUT",
+          `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`,
+          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} id - The resource ID
@@ -165,9 +261,11 @@ class PlaidClient {
        * @param {string} configKey - The config key
        */
       deleteConfig: (id, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+        this._request(
+          "DELETE",
+          `/api/v1/vocab-layers/${id}/config/${namespace}/${configKey}`,
+          { auditMessage, skipResponseTransform: true },
+        ),
       /**
        * List all vocab layers accessible to user. Transparently follows
        * pagination cursors and returns the full flat array.
@@ -175,7 +273,7 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       list: (asOf) =>
-        listAll(this, '/api/v1/vocab-layers', { query: { 'as-of': asOf } }),
+        listAll(this, "/api/v1/vocab-layers", { query: { "as-of": asOf } }),
       /**
        * Fetch a single page of vocab layers.
        * @param {object} [opts]
@@ -185,7 +283,11 @@ class PlaidClient {
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
       listPage: ({ limit, cursor, asOf } = {}) =>
-        listPage(this, '/api/v1/vocab-layers', { limit, cursor, query: { 'as-of': asOf } }),
+        listPage(this, "/api/v1/vocab-layers", {
+          limit,
+          cursor,
+          query: { "as-of": asOf },
+        }),
       /**
        * Async-iterate vocab layers page by page; yields each page's entries array.
        * @param {object} [opts]
@@ -195,13 +297,17 @@ class PlaidClient {
        * @returns {AsyncGenerator<Array>}
        */
       iterPages: ({ pageSize, asOf } = {}) =>
-        iterPages(this, '/api/v1/vocab-layers', { pageSize, query: { 'as-of': asOf } }),
+        iterPages(this, "/api/v1/vocab-layers", {
+          pageSize,
+          query: { "as-of": asOf },
+        }),
       /**
        * Create a new vocab layer. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
        */
       create: (name, auditMessage) =>
-        this._request('POST', '/api/v1/vocab-layers', { auditMessage,
+        this._request("POST", "/api/v1/vocab-layers", {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -210,14 +316,22 @@ class PlaidClient {
        * @param {string} userId - The user ID
        */
       addMaintainer: (id, userId, auditMessage) =>
-        this._request('POST', `/api/v1/vocab-layers/${id}/maintainers/${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, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-layers/${id}/maintainers/${userId}`, { auditMessage }),
+        this._request(
+          "DELETE",
+          `/api/v1/vocab-layers/${id}/maintainers/${userId}`,
+          { auditMessage },
+        ),
     };
 
     this.relations = {
@@ -227,15 +341,18 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (relationId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        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, auditMessage) =>
-        this._request('DELETE', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
+        this._request("DELETE", `/api/v1/relations/${relationId}/metadata`, {
+          auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -244,8 +361,10 @@ class PlaidClient {
        * @param {any} body - The metadata patch
        */
       patchMetadata: (relationId, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/relations/${relationId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PATCH", `/api/v1/relations/${relationId}/metadata`, {
+          auditMessage,
+          rawBody: body,
+          skipResponseTransform: true,
         }),
       /**
        * Update the target span of a relation.
@@ -253,8 +372,9 @@ class PlaidClient {
        * @param {string} spanId - The span ID
        */
       setTarget: (relationId, spanId, auditMessage) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/target`, { auditMessage,
-          body: bodyOf({ 'span-id': spanId }),
+        this._request("PUT", `/api/v1/relations/${relationId}/target`, {
+          auditMessage,
+          body: bodyOf({ "span-id": spanId }),
         }),
       /**
        * Get a relation by ID.
@@ -262,22 +382,25 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (relationId, asOf) =>
-        this._request('GET', `/api/v1/relations/${relationId}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/relations/${relationId}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a relation.
        * @param {string} relationId - The relation ID
        */
       delete: (relationId, auditMessage) =>
-        this._request('DELETE', `/api/v1/relations/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/relations/${relationId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/relations/${relationId}`, {
+          auditMessage,
           body: bodyOf({ value }),
         }),
       /**
@@ -286,8 +409,9 @@ class PlaidClient {
        * @param {string} spanId - The span ID
        */
       setSource: (relationId, spanId, auditMessage) =>
-        this._request('PUT', `/api/v1/relations/${relationId}/source`, { auditMessage,
-          body: bodyOf({ 'span-id': spanId }),
+        this._request("PUT", `/api/v1/relations/${relationId}/source`, {
+          auditMessage,
+          body: bodyOf({ "span-id": spanId }),
         }),
       /**
        * Create a new relation. A relation is a directed edge between two spans
@@ -300,8 +424,15 @@ class PlaidClient {
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
       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 }),
+        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.
@@ -309,13 +440,16 @@ class PlaidClient {
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
-        this._request('POST', '/api/v1/relations/bulk', { auditMessage, body }),
+        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, auditMessage) =>
-        this._request('DELETE', '/api/v1/relations/bulk', { auditMessage, body }),
+        this._request("DELETE", "/api/v1/relations/bulk", {
+          auditMessage,
+          body,
+        }),
     };
 
     this.spanLayers = {
@@ -326,10 +460,18 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (spanLayerId, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (
+        spanLayerId,
+        namespace,
+        configKey,
+        configValue,
+        auditMessage,
+      ) =>
+        this._request(
+          "PUT",
+          `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`,
+          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} spanLayerId - The span layer ID
@@ -337,31 +479,36 @@ class PlaidClient {
        * @param {string} configKey - The config key
        */
       deleteConfig: (spanLayerId, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+        this._request(
+          "DELETE",
+          `/api/v1/span-layers/${spanLayerId}/config/${namespace}/${configKey}`,
+          { auditMessage, skipResponseTransform: true },
+        ),
       /**
        * Get a span layer by ID.
        * @param {string} spanLayerId - The span layer ID
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (spanLayerId, asOf) =>
-        this._request('GET', `/api/v1/span-layers/${spanLayerId}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/span-layers/${spanLayerId}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a span layer.
        * @param {string} spanLayerId - The span layer ID
        */
       delete: (spanLayerId, auditMessage) =>
-        this._request('DELETE', `/api/v1/span-layers/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/span-layers/${spanLayerId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/span-layers/${spanLayerId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -370,8 +517,9 @@ class PlaidClient {
        * @param {string} name - The name
        */
       create: (tokenLayerId, name, auditMessage) =>
-        this._request('POST', '/api/v1/span-layers', { auditMessage,
-          body: bodyOf({ 'token-layer-id': tokenLayerId, name }),
+        this._request("POST", "/api/v1/span-layers", {
+          auditMessage,
+          body: bodyOf({ "token-layer-id": tokenLayerId, name }),
         }),
       /**
        * Shift a span layer's display order.
@@ -379,7 +527,8 @@ class PlaidClient {
        * @param {string} direction - The direction ("up" or "down")
        */
       shift: (spanLayerId, direction, auditMessage) =>
-        this._request('POST', `/api/v1/span-layers/${spanLayerId}/shift`, { auditMessage,
+        this._request("POST", `/api/v1/span-layers/${spanLayerId}/shift`, {
+          auditMessage,
           body: bodyOf({ direction }),
         }),
     };
@@ -391,7 +540,8 @@ class PlaidClient {
        * @param {Array} tokens - The tokens
        */
       setTokens: (spanId, tokens, auditMessage) =>
-        this._request('PUT', `/api/v1/spans/${spanId}/tokens`, { auditMessage,
+        this._request("PUT", `/api/v1/spans/${spanId}/tokens`, {
+          auditMessage,
           body: bodyOf({ tokens }),
         }),
       /**
@@ -403,8 +553,14 @@ class PlaidClient {
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
       create: (spanLayerId, tokens, value, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/spans', { auditMessage,
-          body: bodyOf({ 'span-layer-id': spanLayerId, tokens, value, metadata }),
+        this._request("POST", "/api/v1/spans", {
+          auditMessage,
+          body: bodyOf({
+            "span-layer-id": spanLayerId,
+            tokens,
+            value,
+            metadata,
+          }),
         }),
       /**
        * Get a span by ID.
@@ -412,22 +568,23 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (spanId, asOf) =>
-        this._request('GET', `/api/v1/spans/${spanId}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/spans/${spanId}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a span.
        * @param {string} spanId - The span ID
        */
       delete: (spanId, auditMessage) =>
-        this._request('DELETE', `/api/v1/spans/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/spans/${spanId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/spans/${spanId}`, {
+          auditMessage,
           body: bodyOf({ value }),
         }),
       /**
@@ -436,28 +593,31 @@ class PlaidClient {
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
-        this._request('POST', '/api/v1/spans/bulk', { auditMessage, body }),
+        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, auditMessage) =>
-        this._request('DELETE', '/api/v1/spans/bulk', { auditMessage, body }),
+        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, auditMessage) =>
-        this._request('PUT', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        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, auditMessage) =>
-        this._request('DELETE', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
+        this._request("DELETE", `/api/v1/spans/${spanId}/metadata`, {
+          auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -466,8 +626,10 @@ class PlaidClient {
        * @param {any} body - The metadata patch
        */
       patchMetadata: (spanId, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/spans/${spanId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PATCH", `/api/v1/spans/${spanId}/metadata`, {
+          auditMessage,
+          rawBody: body,
+          skipResponseTransform: true,
         }),
     };
 
@@ -478,8 +640,10 @@ class PlaidClient {
        * @param {Array} body - The request body
        */
       submit: (body, auditMessage) =>
-        this._request('POST', '/api/v1/batch', { auditMessage,
-          body, noBatch: true,
+        this._request("POST", "/api/v1/batch", {
+          auditMessage,
+          body,
+          noBatch: true,
         }),
     };
 
@@ -490,15 +654,18 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (textId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/texts/${textId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        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, auditMessage) =>
-        this._request('DELETE', `/api/v1/texts/${textId}/metadata`, { auditMessage,
+        this._request("DELETE", `/api/v1/texts/${textId}/metadata`, {
+          auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -507,8 +674,10 @@ class PlaidClient {
        * @param {any} body - The metadata patch
        */
       patchMetadata: (textId, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/texts/${textId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        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
@@ -519,8 +688,14 @@ class PlaidClient {
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
       create: (textLayerId, documentId, body, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/texts', { auditMessage,
-          body: bodyOf({ 'text-layer-id': textLayerId, 'document-id': documentId, body, metadata }),
+        this._request("POST", "/api/v1/texts", {
+          auditMessage,
+          body: bodyOf({
+            "text-layer-id": textLayerId,
+            "document-id": documentId,
+            body,
+            metadata,
+          }),
         }),
       /**
        * Get a text.
@@ -528,24 +703,30 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (textId, asOf) =>
-        this._request('GET', `/api/v1/texts/${textId}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/texts/${textId}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a text and all dependent data.
        * @param {string} textId - The text ID
        */
       delete: (textId, auditMessage) =>
-        this._request('DELETE', `/api/v1/texts/${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
-       * edit directives.
+       * edit directives (code-point indices, applied in order):
+       *   {type: 'delete', index, value: count}
+       *   {type: 'insert', index, value: string}
+       *   {type: 'replace', index, length, value: string} — unlike
+       *     delete+insert, a token covering the whole range is resized to keep
+       *     it (respell a word in place without losing its annotations).
        * @param {string} textId - The text ID
        * @param {any} body - The request body
        */
       update: (textId, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/texts/${textId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/texts/${textId}`, {
+          auditMessage,
           body: bodyOf({ body }),
         }),
     };
@@ -556,42 +737,58 @@ class PlaidClient {
        * 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 {object} [opts]
-       * @param {string} [opts.q] - Filter to usernames containing this text (case-insensitive)
+       * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
        * @param {string} [opts.asOf] - Temporal query timestamp
        */
       list: ({ q, asOf } = {}) =>
-        listAll(this, '/api/v1/users', { query: { q, 'as-of': asOf } }),
+        listAll(this, "/api/v1/users", { query: { q, "as-of": asOf } }),
       /**
        * 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 {string} [opts.q] - Filter to users whose display name or email contains 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: ({ q, limit, cursor, asOf } = {}) =>
-        listPage(this, '/api/v1/users', { limit, cursor, query: { q, 'as-of': 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 {string} [opts.q] - Filter to users whose display name or email contains 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: ({ q, pageSize, asOf } = {}) =>
-        iterPages(this, '/api/v1/users', { pageSize, query: { q, 'as-of': asOf } }),
+        iterPages(this, "/api/v1/users", {
+          pageSize,
+          query: { q, "as-of": asOf },
+        }),
       /**
-       * Create a new user
-       * @param {string} username - The username
+       * Create a new user.
+       * @param {string} email - The account's email address. It becomes the
+       *   user's id and is what they log in with; it can never be changed.
        * @param {string} password - The password
        * @param {boolean} isAdmin - Whether the user is an admin
+       * @param {string} [displayName] - How the user is shown in the UI.
+       *   Defaults to the local part of the email.
        */
-      create: (username, password, isAdmin, auditMessage) =>
-        this._request('POST', '/api/v1/users', { auditMessage,
-          body: bodyOf({ username, password, 'is-admin': isAdmin }),
+      create: (email, password, isAdmin, displayName, auditMessage) =>
+        this._request("POST", "/api/v1/users", {
+          auditMessage,
+          body: bodyOf({
+            email,
+            password,
+            "is-admin": isAdmin,
+            "display-name": displayName,
+          }),
         }),
       /**
        * Get audit log for a user's actions. Transparently follows pagination
@@ -601,10 +798,19 @@ class PlaidClient {
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
        * @param {string} [asOf] - Temporal query timestamp
+       * @param {string[]|string} [opTypes] - Only return operations of these
+       *   types, spelled as in an entry's `op/type` (e.g.
+       *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
+       *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (userId, startTime, endTime, asOf) =>
+      audit: (userId, startTime, endTime, asOf, opTypes) =>
         listAll(this, `/api/v1/users/${userId}/audit`, {
-          query: { 'start-time': startTime, 'end-time': endTime, 'as-of': asOf },
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+          },
         }),
       /**
        * Get a user by ID
@@ -612,8 +818,8 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (id, asOf) =>
-        this._request('GET', `/api/v1/users/${id}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/users/${id}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Deactivate a user. Users are never hard-deleted: deactivation
@@ -624,7 +830,7 @@ class PlaidClient {
        * @param {string} id - The resource ID
        */
       delete: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/users/${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
@@ -632,22 +838,148 @@ class PlaidClient {
        * @param {string} id - The resource ID
        */
       activate: (id, auditMessage) =>
-        this._request('POST', `/api/v1/users/${id}/activate`, { 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
-       * or password.
-       * @param {string} id - The resource ID
+       * Modify a user. Admins may change the display name, password, and admin
+       * status of any user. All other users may only modify their own display
+       * name or password.
+       *
+       * A user's id is their email address and is fixed for the life of the
+       * account — it is what they log in with, so nothing can change it.
+       * @param {string} id - The resource ID (the user's email address)
        * @param {string} [password] - New password
-       * @param {string} [username] - New username
+       * @param {string} [displayName] - New display name
        * @param {boolean} [isAdmin] - New admin status
        */
-      update: (id, password, username, isAdmin, auditMessage) =>
-        this._request('PATCH', `/api/v1/users/${id}`, { auditMessage,
-          body: bodyOf({ password, username, 'is-admin': isAdmin }),
+      update: (id, password, displayName, isAdmin, auditMessage) =>
+        this._request("PATCH", `/api/v1/users/${id}`, {
+          auditMessage,
+          body: bodyOf({
+            password,
+            "display-name": displayName,
+            "is-admin": isAdmin,
+          }),
+        }),
+      /**
+       * Build a URL for a user's profile picture, suitable for use directly as
+       * an `<img>` src. An image element cannot send an Authorization header,
+       * so the session token rides in the query string, the same way document
+       * media does.
+       *
+       * Pass the user record's `avatarHash` as the second argument whenever you
+       * have it: the URL then addresses that exact picture, so the browser can
+       * cache it indefinitely and still pick up a replacement the moment the
+       * user changes it. Returns null when the user has no picture, so callers
+       * can fall back to initials without a wasted request.
+       * @param {string} id - The user ID
+       * @param {string} [avatarHash] - The user record's `avatarHash`
+       * @returns {string|null}
+       */
+      avatarUrl: (id, avatarHash) => {
+        if (avatarHash === null) return null;
+        const params = new URLSearchParams({ token: this.token });
+        if (avatarHash) params.set("v", avatarHash);
+        return `${this.baseUrl}/api/v1/users/${id}/avatar?${params}`;
+      },
+      /**
+       * Fetch a user's profile picture as raw bytes. Most callers want
+       * avatarUrl() instead. This one is for non-browser consumers.
+       * @param {string} id - The user ID
+       */
+      getAvatar: (id) =>
+        this._request("GET", `/api/v1/users/${id}/avatar`, {
+          noBatch: true,
+          binaryResponse: true,
+        }),
+      /**
+       * Upload a profile picture. Your own, or anyone's if you are an admin.
+       * The server center-crops to a square, scales to the configured edge
+       * length, and re-encodes, so no client-side resizing is needed. Accepts
+       * PNG, JPEG, WebP, and GIF. Resolves to the updated user record.
+       * @param {string} id - The user ID
+       * @param {File} file - The image to upload
+       */
+      setAvatar: (id, file, auditMessage) => {
+        const fd = new FormData();
+        fd.append("file", file);
+        return this._request("PUT", `/api/v1/users/${id}/avatar`, {
+          auditMessage,
+          body: fd,
+          formData: true,
+          noBatch: true,
+        });
+      },
+      /**
+       * Remove a profile picture. Your own, or anyone's if you are an admin.
+       * @param {string} id - The user ID
+       */
+      deleteAvatar: (id, auditMessage) =>
+        this._request("DELETE", `/api/v1/users/${id}/avatar`, {
+          auditMessage,
+          noBatch: true,
         }),
     };
 
+    this.userData = {
+      /**
+       * List a user's private data entries ({key, updatedAt}, plus value when
+       * includeValues). Owner or admin only.
+       * @param {string} userId
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this prefix
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       */
+      list: (userId, { prefix, includeValues } = {}) =>
+        this._request("GET", `/api/v1/users/${userId}/data`, {
+          queryParams: { prefix, "include-values": includeValues },
+        }),
+      /**
+       * Read one private data entry ({key, updatedAt, value}); 404 if absent.
+       * @param {string} userId
+       * @param {string} key
+       */
+      get: (userId, key) =>
+        this._request(
+          "GET",
+          `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
+        ),
+      /**
+       * Create or replace one private data entry. `value` is any JSON (up to
+       * 1 MB), stored as sent. Not audited, not batchable.
+       *
+       * The server stores it verbatim, but this client recases object keys on
+       * the way out and back like any other body (`myKey` <-> `my-key`), so a
+       * value whose keys are camelCase round-trips unchanged while one keyed
+       * by arbitrary strings does not. Put such a map under a `metadata` key,
+       * which both clients pass through untouched.
+       * @param {string} userId
+       * @param {string} key
+       * @param {*} value
+       */
+      put: (userId, key, value) =>
+        this._request(
+          "PUT",
+          `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
+          {
+            body: value,
+            noBatch: true,
+          },
+        ),
+      /**
+       * Delete one private data entry; 404 if absent.
+       * @param {string} userId
+       * @param {string} key
+       */
+      delete: (userId, key) =>
+        this._request(
+          "DELETE",
+          `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
+          {
+            noBatch: true,
+          },
+        ),
+    };
+
     this.apiTokens = {
       /**
        * List a user's named API tokens. Never includes the signed token
@@ -656,8 +988,7 @@ class PlaidClient {
        * 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} userId - The user ID who owns the tokens
        */
-      list: (userId) =>
-        listAll(this, `/api/v1/users/${userId}/tokens`),
+      list: (userId) => listAll(this, `/api/v1/users/${userId}/tokens`),
       /**
        * Fetch a single page of a user's named API tokens.
        * @param {string} userId - The user ID who owns the tokens
@@ -688,7 +1019,8 @@ class PlaidClient {
        * @returns {Promise<{id: string, name: string, token: string}>}
        */
       create: (userId, name, auditMessage) =>
-        this._request('POST', `/api/v1/users/${userId}/tokens`, { auditMessage,
+        this._request("POST", `/api/v1/users/${userId}/tokens`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -697,7 +1029,109 @@ class PlaidClient {
        * @param {string} tokenId - The token ID to revoke
        */
       revoke: (userId, tokenId, auditMessage) =>
-        this._request('DELETE', `/api/v1/users/${userId}/tokens/${tokenId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/users/${userId}/tokens/${tokenId}`, {
+          auditMessage,
+        }),
+    };
+
+    this.invites = {
+      /**
+       * List invites you minted, oldest first. With `projectId`, lists that
+       * project's invites instead (including co-maintainers'), which requires
+       * maintainer or admin on it. Never includes invite codes — the code is
+       * returned once, by create(), and is not recoverable afterward.
+       * Transparently follows pagination cursors and returns the full flat array.
+       * 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 {object} [opts]
+       * @param {string} [opts.projectId] - List this project's invites instead of your own
+       */
+      list: ({ projectId } = {}) =>
+        listAll(this, "/api/v1/invites", {
+          query: { "project-id": projectId },
+        }),
+      /**
+       * Fetch a single page of invites.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: ({ projectId, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/invites", {
+          limit,
+          cursor,
+          query: { "project-id": projectId },
+        }),
+      /**
+       * Async-iterate invites page by page; yields each page's entries array.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {number} [opts.pageSize] - Per-request page size
+       * 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: ({ projectId, pageSize } = {}) =>
+        iterPages(this, "/api/v1/invites", {
+          pageSize,
+          query: { "project-id": projectId },
+        }),
+      /**
+       * Mint an invite. The returned `code` is shown ONLY here — it is never
+       * stored and cannot be recovered, so build and hand off the link now.
+       * Use PlaidClient.inviteUrl() to turn it into one.
+       *
+       * Admins may mint anything. A project maintainer may mint role grants on
+       * projects they maintain, and nothing else: no admin grant, no grantless
+       * invite, no password resets — so for a non-admin, projectId/projectRole
+       * are required in practice (403 without them).
+       *
+       * EVERY option is optional; `create()` with no arguments mints a
+       * single-use signup link granting nothing but an account. Two pairing
+       * rules the server enforces with a 400: projectId and projectRole must be
+       * given TOGETHER, and targetUserId may not be combined with projectId,
+       * grantAdmin, or a maxUses above 1.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - Project the redeemer joins (requires projectRole)
+       * @param {string} [opts.projectRole] - "reader" | "writer" | "maintainer" (requires projectId)
+       * @param {boolean} [opts.grantAdmin] - Make the new account a global admin (admin only)
+       * @param {string} [opts.targetUserId] - Password reset for that user instead of a signup; admin only, single-use, grants nothing
+       * @param {number} [opts.maxUses] - How many accounts this link may create (default 1)
+       * @param {number} [opts.ttlDays] - Days until it expires (default 14, max 365)
+       * @param {string} [opts.note] - Human label shown in your invite list
+       * @returns {Promise<{id: string, code: string, kind: string, status: string}>}
+       */
+      create: (
+        {
+          projectId,
+          projectRole,
+          grantAdmin,
+          targetUserId,
+          maxUses,
+          ttlDays,
+          note,
+        } = {},
+        auditMessage,
+      ) =>
+        this._request("POST", "/api/v1/invites", {
+          auditMessage,
+          body: bodyOf({
+            "project-id": projectId,
+            "project-role": projectRole,
+            "grant-admin": grantAdmin,
+            "target-user-id": targetUserId,
+            "max-uses": maxUses,
+            "ttl-days": ttlDays,
+            note,
+          }),
+        }),
+      /**
+       * Revoke an invite, killing the link immediately. Idempotent. Allowed for
+       * the creator, an admin, or a maintainer of the invite's project.
+       * @param {string} id - The invite ID
+       */
+      revoke: (id, auditMessage) =>
+        this._request("DELETE", `/api/v1/invites/${id}`, { auditMessage }),
     };
 
     this.tokenLayers = {
@@ -707,7 +1141,8 @@ class PlaidClient {
        * @param {string} direction - The direction ("up" or "down")
        */
       shift: (tokenLayerId, direction, auditMessage) =>
-        this._request('POST', `/api/v1/token-layers/${tokenLayerId}/shift`, { auditMessage,
+        this._request("POST", `/api/v1/token-layers/${tokenLayerId}/shift`, {
+          auditMessage,
           body: bodyOf({ direction }),
         }),
       /**
@@ -717,9 +1152,21 @@ 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, auditMessage) =>
-        this._request('POST', '/api/v1/token-layers', { auditMessage,
-          body: bodyOf({ 'text-layer-id': textLayerId, name, 'overlap-mode': overlapMode, 'parent-token-layer-id': parentTokenLayerId }),
+      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,
+          }),
         }),
       /**
        * Set a configuration value for a layer in an editor namespace.
@@ -728,10 +1175,18 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (tokenLayerId, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (
+        tokenLayerId,
+        namespace,
+        configKey,
+        configValue,
+        auditMessage,
+      ) =>
+        this._request(
+          "PUT",
+          `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`,
+          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} tokenLayerId - The token layer ID
@@ -739,31 +1194,36 @@ class PlaidClient {
        * @param {string} configKey - The config key
        */
       deleteConfig: (tokenLayerId, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+        this._request(
+          "DELETE",
+          `/api/v1/token-layers/${tokenLayerId}/config/${namespace}/${configKey}`,
+          { auditMessage, skipResponseTransform: true },
+        ),
       /**
        * Get a token layer by ID.
        * @param {string} tokenLayerId - The token layer ID
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (tokenLayerId, asOf) =>
-        this._request('GET', `/api/v1/token-layers/${tokenLayerId}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/token-layers/${tokenLayerId}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a token layer.
        * @param {string} tokenLayerId - The token layer ID
        */
       delete: (tokenLayerId, auditMessage) =>
-        this._request('DELETE', `/api/v1/token-layers/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/token-layers/${tokenLayerId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/token-layers/${tokenLayerId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
     };
@@ -775,29 +1235,33 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       checkLock: (documentId, asOf) =>
-        this._request('GET', `/api/v1/documents/${documentId}/lock`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/documents/${documentId}/lock`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Acquire or refresh a document lock
        * @param {string} documentId - The document ID
        */
       acquireLock: (documentId, auditMessage) =>
-        this._request('POST', `/api/v1/documents/${documentId}/lock`, { auditMessage }),
+        this._request("POST", `/api/v1/documents/${documentId}/lock`, {
+          auditMessage,
+        }),
       /**
        * Release a document lock
        * @param {string} documentId - The document ID
        */
       releaseLock: (documentId, auditMessage) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/lock`, { auditMessage }),
+        this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
+          auditMessage,
+        }),
       /**
-       * Get media file for a document
+       * Get the media file for a document. Media is not versioned, so there is
+       * no as-of form: the route refuses the parameter. Prefer the document's
+       * own `mediaUrl`, which carries the file's version for caching.
        * @param {string} documentId - The document ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      getMedia: (documentId, asOf) =>
-        this._request('GET', `/api/v1/documents/${documentId}/media`, {
-          queryParams: { 'as-of': asOf },
+      getMedia: (documentId) =>
+        this._request("GET", `/api/v1/documents/${documentId}/media`, {
           noBatch: true,
           binaryResponse: true,
         }),
@@ -805,12 +1269,18 @@ class PlaidClient {
        * Upload a media file for a document. Uses Apache Tika for content validation.
        * @param {string} documentId - The document ID
        * @param {File} file - The file to upload
+       * @param {string} [auditMessage] - Custom audit-log message for this write
+       * @param {object} [options] - `{ onProgress }`: called with `{ loaded, total }` (bytes) as the file goes up. In a browser the upload then travels by XMLHttpRequest, and the request timeout only fires when the upload stalls, not on total time.
        */
-      uploadMedia: (documentId, file, auditMessage) => {
+      uploadMedia: (documentId, file, auditMessage, { onProgress } = {}) => {
         const fd = new FormData();
-        fd.append('file', file);
-        return this._request('PUT', `/api/v1/documents/${documentId}/media`, { auditMessage,
-          body: fd, formData: true, noBatch: true,
+        fd.append("file", file);
+        return this._request("PUT", `/api/v1/documents/${documentId}/media`, {
+          auditMessage,
+          body: fd,
+          formData: true,
+          noBatch: true,
+          onUploadProgress: onProgress,
         });
       },
       /**
@@ -818,7 +1288,8 @@ class PlaidClient {
        * @param {string} documentId - The document ID
        */
       deleteMedia: (documentId, auditMessage) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/media`, { auditMessage,
+        this._request("DELETE", `/api/v1/documents/${documentId}/media`, {
+          auditMessage,
           noBatch: true,
         }),
       /**
@@ -827,15 +1298,18 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (documentId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        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, auditMessage) =>
-        this._request('DELETE', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
+        this._request("DELETE", `/api/v1/documents/${documentId}/metadata`, {
+          auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -844,8 +1318,10 @@ class PlaidClient {
        * @param {any} body - The metadata patch
        */
       patchMetadata: (documentId, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/documents/${documentId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PATCH", `/api/v1/documents/${documentId}/metadata`, {
+          auditMessage,
+          rawBody: body,
+          skipResponseTransform: true,
         }),
       /**
        * Get audit log for a document. Transparently follows pagination cursors
@@ -855,34 +1331,78 @@ class PlaidClient {
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
        * @param {string} [asOf] - Temporal query timestamp
+       * @param {string[]|string} [opTypes] - Only return operations of these
+       *   types, spelled as in an entry's `op/type` (e.g.
+       *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
+       *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (documentId, startTime, endTime, asOf) =>
+      audit: (documentId, startTime, endTime, asOf, opTypes) =>
         listAll(this, `/api/v1/documents/${documentId}/audit`, {
-          query: { 'start-time': startTime, 'end-time': endTime, 'as-of': asOf },
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+          },
+        }),
+      /**
+       * Restore a document to its state at an earlier time, as one
+       * operation: what was deleted since then comes back under its original
+       * id, what was added since is removed, and what changed is set back,
+       * across every layer. A layer deleted since then, or a vocabulary entry
+       * that no longer exists, is skipped and reported under `skipped`.
+       * Resolves to a summary of the changes. Maintainers only.
+       * @param {string} documentId - The document ID
+       * @param {string} asOf - The moment to go back to (ISO-8601 instant),
+       *   typically a history entry's `endTime`
+       * @param {object} [options] - `{ dryRun }`: with `dryRun` true nothing
+       *   is written and the summary says what would change
+       * @param {string} [auditMessage] - Custom audit message for this operation
+       */
+      restore: (documentId, asOf, { dryRun } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/documents/${documentId}/restore`, {
+          queryParams: { "as-of": asOf, "dry-run": dryRun ? "true" : undefined },
+          auditMessage,
         }),
       /**
        * Get a document. Set `includeBody` to true to include all data.
+       *
+       * `layers` narrows a body read to the layers you name (ids of any kind:
+       * text, token, span, or relation). A layer comes back when it is named
+       * or is an ancestor of a named layer, and carries its own
+       * texts/tokens/spans/relations/vocabs only when it is itself named — so
+       * name the text layer too if you also want the text body. An id that is
+       * not a layer of this document's project is an error, not a quietly
+       * smaller response. Requires `includeBody`.
        * @param {string} documentId - The document ID
        * @param {boolean} [includeBody] - Include document body data
        * @param {string} [asOf] - Temporal query timestamp
+       * @param {string[]|string} [layers] - Layer ids to restrict a body read to
        */
-      get: (documentId, includeBody, asOf) =>
-        this._request('GET', `/api/v1/documents/${documentId}`, {
-          queryParams: { 'include-body': includeBody, 'as-of': asOf },
+      get: (documentId, includeBody, asOf, layers) =>
+        this._request("GET", `/api/v1/documents/${documentId}`, {
+          queryParams: {
+            "include-body": includeBody,
+            "as-of": asOf,
+            layers: layersParam(layers),
+          },
         }),
       /**
        * Delete a document and all data contained.
        * @param {string} documentId - The document ID
        */
       delete: (documentId, auditMessage) =>
-        this._request('DELETE', `/api/v1/documents/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/documents/${documentId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/documents/${documentId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -892,8 +1412,9 @@ class PlaidClient {
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
       create: (projectId, name, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/documents', { auditMessage,
-          body: bodyOf({ 'project-id': projectId, name, metadata }),
+        this._request("POST", "/api/v1/documents", {
+          auditMessage,
+          body: bodyOf({ "project-id": projectId, name, metadata }),
         }),
     };
 
@@ -904,28 +1425,36 @@ class PlaidClient {
        * @param {string} userId - The user ID
        */
       addWriter: (id, userId, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${id}/writers/${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, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/writers/${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, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${id}/readers/${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, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/readers/${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
@@ -934,9 +1463,11 @@ class PlaidClient {
        * @param {any} configValue - Configuration value to set
        */
       setConfig: (id, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/projects/${id}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+        this._request(
+          "PUT",
+          `/api/v1/projects/${id}/config/${namespace}/${configKey}`,
+          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+        ),
       /**
        * Remove a configuration value for a project.
        * @param {string} id - The resource ID
@@ -944,23 +1475,31 @@ class PlaidClient {
        * @param {string} configKey - The config key
        */
       deleteConfig: (id, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+        this._request(
+          "DELETE",
+          `/api/v1/projects/${id}/config/${namespace}/${configKey}`,
+          { auditMessage, skipResponseTransform: true },
+        ),
       /**
        * Assign a user as a maintainer for this project.
        * @param {string} id - The resource ID
        * @param {string} userId - The user ID
        */
       addMaintainer: (id, userId, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${id}/maintainers/${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, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/maintainers/${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.
@@ -969,10 +1508,33 @@ class PlaidClient {
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
        * @param {string} [asOf] - Temporal query timestamp
+       * @param {string[]|string} [opTypes] - Only return operations of these
+       *   types, spelled as in an entry's `op/type` (e.g.
+       *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
+       *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (projectId, startTime, endTime, asOf) =>
+      audit: (projectId, startTime, endTime, asOf, opTypes) =>
         listAll(this, `/api/v1/projects/${projectId}/audit`, {
-          query: { 'start-time': startTime, 'end-time': endTime, 'as-of': asOf },
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+          },
+        }),
+      /**
+       * When the calling user last wrote to each document in a project, as a
+       * `{documentId: timestamp}` map. Documents they have never written to
+       * are absent. One request covers a whole document list.
+       *
+       * The response is NOT key-transformed: its keys are document ids, and
+       * camelCasing would mangle the hyphens in a UUID.
+       * @param {string} projectId - The project ID
+       * @returns {Promise<Object<string, string>>}
+       */
+      myLastEdits: (projectId) =>
+        this._request("GET", `/api/v1/projects/${projectId}/audit/last-edits`, {
+          skipResponseTransform: true,
         }),
       /**
        * Link a vocabulary to a project.
@@ -980,14 +1542,18 @@ class PlaidClient {
        * @param {string} vocabId - The vocab layer ID
        */
       linkVocab: (id, vocabId, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${id}/vocabs/${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, auditMessage) =>
-        this._request('DELETE', `/api/v1/projects/${id}/vocabs/${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.
@@ -995,8 +1561,8 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (id, asOf) =>
-        this._request('GET', `/api/v1/projects/${id}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/projects/${id}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * List all documents in a project. Transparently follows pagination
@@ -1007,8 +1573,7 @@ class PlaidClient {
        * server rejects `?as-of=` on the documents-list route with a 400.
        * @param {string} id - The project ID
        */
-      listDocuments: (id) =>
-        listAll(this, `/api/v1/projects/${id}/documents`),
+      listDocuments: (id) => listAll(this, `/api/v1/projects/${id}/documents`),
       /**
        * Fetch a single page of a project's documents.
        *
@@ -1048,14 +1613,18 @@ class PlaidClient {
        * @param {number} [options.timeout=0] - Per-request timeout in ms (0/null disables)
        */
       delete: (id, auditMessage, { timeout = 0 } = {}) =>
-        this._request('DELETE', `/api/v1/projects/${id}`, { auditMessage, timeout }),
+        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, auditMessage) =>
-        this._request('PATCH', `/api/v1/projects/${id}`, { auditMessage,
+        this._request("PATCH", `/api/v1/projects/${id}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -1065,7 +1634,7 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       list: (asOf) =>
-        listAll(this, '/api/v1/projects', { query: { 'as-of': asOf } }),
+        listAll(this, "/api/v1/projects", { query: { "as-of": asOf } }),
       /**
        * Fetch a single page of projects.
        * @param {object} [opts]
@@ -1075,7 +1644,11 @@ class PlaidClient {
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
       listPage: ({ limit, cursor, asOf } = {}) =>
-        listPage(this, '/api/v1/projects', { limit, cursor, query: { 'as-of': asOf } }),
+        listPage(this, "/api/v1/projects", {
+          limit,
+          cursor,
+          query: { "as-of": asOf },
+        }),
       /**
        * Async-iterate projects page by page; yields each page's entries array.
        * @param {object} [opts]
@@ -1085,13 +1658,17 @@ class PlaidClient {
        * @returns {AsyncGenerator<Array>}
        */
       iterPages: ({ pageSize, asOf } = {}) =>
-        iterPages(this, '/api/v1/projects', { pageSize, query: { 'as-of': asOf } }),
+        iterPages(this, "/api/v1/projects", {
+          pageSize,
+          query: { "as-of": asOf },
+        }),
       /**
        * Create a new project. Note: this also registers the user as a maintainer.
        * @param {string} name - The name
        */
       create: (name, auditMessage) =>
-        this._request('POST', '/api/v1/projects', { auditMessage,
+        this._request("POST", "/api/v1/projects", {
+          auditMessage,
           body: bodyOf({ name }),
         }),
     };
@@ -1104,10 +1681,18 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (textLayerId, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (
+        textLayerId,
+        namespace,
+        configKey,
+        configValue,
+        auditMessage,
+      ) =>
+        this._request(
+          "PUT",
+          `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`,
+          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} textLayerId - The text layer ID
@@ -1115,31 +1700,36 @@ class PlaidClient {
        * @param {string} configKey - The config key
        */
       deleteConfig: (textLayerId, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+        this._request(
+          "DELETE",
+          `/api/v1/text-layers/${textLayerId}/config/${namespace}/${configKey}`,
+          { auditMessage, skipResponseTransform: true },
+        ),
       /**
        * Get a text layer by ID.
        * @param {string} textLayerId - The text layer ID
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (textLayerId, asOf) =>
-        this._request('GET', `/api/v1/text-layers/${textLayerId}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/text-layers/${textLayerId}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a text layer.
        * @param {string} textLayerId - The text layer ID
        */
       delete: (textLayerId, auditMessage) =>
-        this._request('DELETE', `/api/v1/text-layers/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/text-layers/${textLayerId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/text-layers/${textLayerId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
       /**
@@ -1148,7 +1738,8 @@ class PlaidClient {
        * @param {string} direction - The direction ("up" or "down")
        */
       shift: (textLayerId, direction, auditMessage) =>
-        this._request('POST', `/api/v1/text-layers/${textLayerId}/shift`, { auditMessage,
+        this._request("POST", `/api/v1/text-layers/${textLayerId}/shift`, {
+          auditMessage,
           body: bodyOf({ direction }),
         }),
       /**
@@ -1157,8 +1748,9 @@ class PlaidClient {
        * @param {string} name - The name
        */
       create: (projectId, name, auditMessage) =>
-        this._request('POST', '/api/v1/text-layers', { auditMessage,
-          body: bodyOf({ 'project-id': projectId, name }),
+        this._request("POST", "/api/v1/text-layers", {
+          auditMessage,
+          body: bodyOf({ "project-id": projectId, name }),
         }),
     };
 
@@ -1169,15 +1761,18 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (id, body, auditMessage) =>
-        this._request('PUT', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        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, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
+        this._request("DELETE", `/api/v1/vocab-items/${id}/metadata`, {
+          auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -1186,8 +1781,10 @@ class PlaidClient {
        * @param {any} body - The metadata patch
        */
       patchMetadata: (id, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/vocab-items/${id}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PATCH", `/api/v1/vocab-items/${id}/metadata`, {
+          auditMessage,
+          rawBody: body,
+          skipResponseTransform: true,
         }),
       /**
        * Create a new vocab item
@@ -1196,8 +1793,9 @@ class PlaidClient {
        * @param {any} [metadata] - Metadata map. Omit to leave unset; pass null to send JSON null.
        */
       create: (vocabLayerId, form, metadata, auditMessage) =>
-        this._request('POST', '/api/v1/vocab-items', { auditMessage,
-          body: bodyOf({ 'vocab-layer-id': vocabLayerId, form, metadata }),
+        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
@@ -1205,36 +1803,43 @@ class PlaidClient {
        * @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 }),
+        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 }),
+        this._request("DELETE", "/api/v1/vocab-items/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * Get a vocab item by ID
        * @param {string} id - The resource ID
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (id, asOf) =>
-        this._request('GET', `/api/v1/vocab-items/${id}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/vocab-items/${id}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a vocab item
        * @param {string} id - The resource ID
        */
       delete: (id, auditMessage) =>
-        this._request('DELETE', `/api/v1/vocab-items/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/vocab-items/${id}`, { auditMessage,
+        this._request("PATCH", `/api/v1/vocab-items/${id}`, {
+          auditMessage,
           body: bodyOf({ form }),
         }),
     };
@@ -1246,17 +1851,20 @@ class PlaidClient {
        * @param {string} direction - The direction ("up" or "down")
        */
       shift: (relationLayerId, direction, auditMessage) =>
-        this._request('POST', `/api/v1/relation-layers/${relationLayerId}/shift`, { auditMessage,
-          body: bodyOf({ direction }),
-        }),
+        this._request(
+          "POST",
+          `/api/v1/relation-layers/${relationLayerId}/shift`,
+          { auditMessage, body: bodyOf({ direction }) },
+        ),
       /**
        * Create a new relation layer.
        * @param {string} spanLayerId - The span layer ID
        * @param {string} name - The name
        */
       create: (spanLayerId, name, auditMessage) =>
-        this._request('POST', '/api/v1/relation-layers', { auditMessage,
-          body: bodyOf({ 'span-layer-id': spanLayerId, name }),
+        this._request("POST", "/api/v1/relation-layers", {
+          auditMessage,
+          body: bodyOf({ "span-layer-id": spanLayerId, name }),
         }),
       /**
        * Set a configuration value for a layer in an editor namespace.
@@ -1265,10 +1873,18 @@ class PlaidClient {
        * @param {string} configKey - The config key
        * @param {any} configValue - Configuration value to set
        */
-      setConfig: (relationLayerId, namespace, configKey, configValue, auditMessage) =>
-        this._request('PUT', `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          rawBody: configValue, skipResponseTransform: true,
-        }),
+      setConfig: (
+        relationLayerId,
+        namespace,
+        configKey,
+        configValue,
+        auditMessage,
+      ) =>
+        this._request(
+          "PUT",
+          `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`,
+          { auditMessage, rawBody: configValue, skipResponseTransform: true },
+        ),
       /**
        * Remove a configuration value for a layer.
        * @param {string} relationLayerId - The relation layer ID
@@ -1276,31 +1892,36 @@ class PlaidClient {
        * @param {string} configKey - The config key
        */
       deleteConfig: (relationLayerId, namespace, configKey, auditMessage) =>
-        this._request('DELETE', `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`, { auditMessage,
-          skipResponseTransform: true,
-        }),
+        this._request(
+          "DELETE",
+          `/api/v1/relation-layers/${relationLayerId}/config/${namespace}/${configKey}`,
+          { auditMessage, skipResponseTransform: true },
+        ),
       /**
        * Get a relation layer by ID.
        * @param {string} relationLayerId - The relation layer ID
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (relationLayerId, asOf) =>
-        this._request('GET', `/api/v1/relation-layers/${relationLayerId}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/relation-layers/${relationLayerId}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a relation layer.
        * @param {string} relationLayerId - The relation layer ID
        */
       delete: (relationLayerId, auditMessage) =>
-        this._request('DELETE', `/api/v1/relation-layers/${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, auditMessage) =>
-        this._request('PATCH', `/api/v1/relation-layers/${relationLayerId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/relation-layers/${relationLayerId}`, {
+          auditMessage,
           body: bodyOf({ name }),
         }),
     };
@@ -1324,9 +1945,25 @@ 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, auditMessage) =>
-        this._request('POST', '/api/v1/tokens', { auditMessage,
-          body: bodyOf({ 'token-layer-id': tokenLayerId, text, begin, end, precedence, metadata }),
+      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,
+          }),
         }),
       /**
        * Get a token.
@@ -1334,8 +1971,8 @@ class PlaidClient {
        * @param {string} [asOf] - Temporal query timestamp
        */
       get: (tokenId, asOf) =>
-        this._request('GET', `/api/v1/tokens/${tokenId}`, {
-          queryParams: { 'as-of': asOf },
+        this._request("GET", `/api/v1/tokens/${tokenId}`, {
+          queryParams: { "as-of": asOf },
         }),
       /**
        * Delete a token and remove it from any spans. If this causes a span to
@@ -1343,7 +1980,7 @@ class PlaidClient {
        * @param {string} tokenId - The token ID
        */
       delete: (tokenId, auditMessage) =>
-        this._request('DELETE', `/api/v1/tokens/${tokenId}`, { auditMessage }),
+        this._request("DELETE", `/api/v1/tokens/${tokenId}`, { auditMessage }),
       /**
        * Update a token.
        * @param {string} tokenId - The token ID
@@ -1355,7 +1992,8 @@ class PlaidClient {
        *   drops undefined, so the three cases map correctly to the server.
        */
       update: (tokenId, begin, end, precedence, auditMessage) =>
-        this._request('PATCH', `/api/v1/tokens/${tokenId}`, { auditMessage,
+        this._request("PATCH", `/api/v1/tokens/${tokenId}`, {
+          auditMessage,
           body: bodyOf({ begin, end, precedence }),
         }),
       /**
@@ -1364,13 +2002,13 @@ class PlaidClient {
        * @returns {Promise<{ids: string[]}>} The created entity IDs, in input order. (bulkDelete resolves to no value.)
        */
       bulkCreate: (body, auditMessage) =>
-        this._request('POST', '/api/v1/tokens/bulk', { auditMessage, body }),
+        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, auditMessage) =>
-        this._request('DELETE', '/api/v1/tokens/bulk', { auditMessage, body }),
+        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.
@@ -1378,7 +2016,8 @@ class PlaidClient {
        * @param {number} position - Code-point offset to split at (strictly between begin and end)
        */
       split: (tokenId, position, auditMessage) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/split`, { auditMessage,
+        this._request("POST", `/api/v1/tokens/${tokenId}/split`, {
+          auditMessage,
           body: bodyOf({ position }),
         }),
       /**
@@ -1390,8 +2029,9 @@ class PlaidClient {
        * @param {string} otherTokenId - The other token to merge in
        */
       merge: (tokenId, otherTokenId, auditMessage) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/merge`, { auditMessage,
-          body: bodyOf({ 'other-token-id': otherTokenId }),
+        this._request("POST", `/api/v1/tokens/${tokenId}/merge`, {
+          auditMessage,
+          body: bodyOf({ "other-token-id": otherTokenId }),
         }),
       /**
        * Shift a token's boundary. On partitioning layers the adjacent token is
@@ -1402,7 +2042,8 @@ class PlaidClient {
        * @param {number} [end] - New end offset, exclusive (Unicode code points)
        */
       shift: (tokenId, begin, end, auditMessage) =>
-        this._request('POST', `/api/v1/tokens/${tokenId}/shift`, { auditMessage,
+        this._request("POST", `/api/v1/tokens/${tokenId}/shift`, {
+          auditMessage,
           body: bodyOf({ begin, end }),
         }),
       /**
@@ -1411,15 +2052,18 @@ class PlaidClient {
        * @param {any} body - The request body
        */
       setMetadata: (tokenId, body, auditMessage) =>
-        this._request('PUT', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        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, auditMessage) =>
-        this._request('DELETE', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
+        this._request("DELETE", `/api/v1/tokens/${tokenId}/metadata`, {
+          auditMessage,
           skipResponseTransform: true,
         }),
       /**
@@ -1428,8 +2072,10 @@ class PlaidClient {
        * @param {any} body - The metadata patch
        */
       patchMetadata: (tokenId, body, auditMessage) =>
-        this._request('PATCH', `/api/v1/tokens/${tokenId}/metadata`, { auditMessage,
-          rawBody: body, skipResponseTransform: true,
+        this._request("PATCH", `/api/v1/tokens/${tokenId}/metadata`, {
+          auditMessage,
+          rawBody: body,
+          skipResponseTransform: true,
         }),
     };
 
@@ -1445,14 +2091,22 @@ class PlaidClient {
         createSSEConnection(this, projectId, onEvent, path),
 
       /**
-       * Send a message to project listeners
+       * Send a message to project listeners.
+       *
+       * `data` may be any JSON value and is sent VERBATIM (`rawBody`): a
+       * message payload is opaque application data, like `metadata` and
+       * `config`, so its keys must not be re-cased on the way out. Without
+       * this a key such as `case-marker` would reach listeners as
+       * `caseMarker` in JS and `case_marker` in Python. `listen` restores it
+       * verbatim on the way in.
        * @param {string} projectId - The UUID of the project to send to
        * @param {any} data - The message data to send
        * @returns {Promise<any>} Response from the send operation
        */
       sendMessage: (projectId, data, auditMessage) =>
-        this._request('POST', `/api/v1/projects/${projectId}/message`, { auditMessage,
-          body: { body: data },
+        this._request("POST", `/api/v1/projects/${projectId}/message`, {
+          auditMessage,
+          rawBody: { body: data },
         }),
 
       /**
@@ -1462,8 +2116,7 @@ class PlaidClient {
        * @param {string} projectId - The UUID of the project to query
        * @returns {Promise<Array>} Array of discovered service information
        */
-      discoverServices: (projectId) =>
-        discoverServices(this, projectId),
+      discoverServices: (projectId) => discoverServices(this, projectId),
 
       /**
        * Forget a previously-seen (offline) service. Maintainer-only; 409 if
@@ -1477,26 +2130,70 @@ class PlaidClient {
 
       /**
        * Register as a service and handle incoming work requests.
+       *
+       * The registration reopens its channel whenever it drops, so a server
+       * restart needs no service restart.
        * @param {string} projectId - The UUID of the project to serve
        * @param {Object} serviceInfo - Service information {serviceId, serviceName, description}
        * @param {function} onServiceRequest - Callback (data, responseHelper)
        * @param {Object} [extras] - Optional additional service metadata
-       * @returns {Object} Service registration object with .stop() method
+       * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
+       *   connection transitions: 'registered', 'reconnected', 'disconnected'
+       * @returns {Object} Service registration with .stop(), .isRunning(), .isConnected()
        */
-      serve: (projectId, serviceInfo, onServiceRequest, extras) =>
-        serve(this, projectId, serviceInfo, onServiceRequest, extras),
+      serve: (projectId, serviceInfo, onServiceRequest, extras, onStatus) =>
+        serve(this, projectId, serviceInfo, onServiceRequest, extras, onStatus),
 
       /**
        * Request a service to perform work and await its result.
+       *
+       * The request outlives this call: after a timeout, an abort, or a
+       * dropped connection the service goes on, and `attachServiceRequest`
+       * collects the result given the request id, which `opts.onAccepted`
+       * receives as soon as the server has taken the request. Pass
+       * `opts.requestId` (a UUID you mint) to know the id before submitting;
+       * submitting an id that names a request you already made rejoins it
+       * instead of starting another.
        * @param {string} projectId - The UUID of the project
        * @param {string} serviceId - The ID of the service to request
        * @param {any} data - The request data
-       * @param {number} [timeout] - Timeout in milliseconds (default: 10000)
+       * @param {number} [timeout=10000] - Timeout in ms
        * @param {function} [onProgress] - Called with each progress payload {percent, message}
-       * @returns {Promise<any>} Service response
+       * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
+       * @param {Object} [opts] - {requestId, onAccepted}
+       * @returns {Promise<any>} The service's result
        */
-      requestService: (projectId, serviceId, data, timeout, onProgress) =>
-        requestService(this, projectId, serviceId, data, timeout, onProgress),
+      requestService: (projectId, serviceId, data, timeout, onProgress, signal, opts) =>
+        requestService(this, projectId, serviceId, data, timeout, onProgress, signal, opts),
+
+      /**
+       * Rejoin a service request made earlier and await its result: the
+       * latest progress is replayed, then the result comes, or at once if the
+       * request already finished. Only the user who submitted it (or an
+       * admin). Rejects with an error whose `status` is 404 when the request
+       * is unknown or expired (a finished request's result is kept for a
+       * while, not forever).
+       * @param {string} projectId - The UUID of the project
+       * @param {string} requestId - The request id
+       * @param {number} [timeout=10000] - Timeout in ms
+       * @param {function} [onProgress] - Called with each progress payload
+       * @param {AbortSignal} [signal] - Abort to stop waiting
+       * @returns {Promise<any>} The service's result
+       */
+      attachServiceRequest: (projectId, requestId, timeout, onProgress, signal) =>
+        attachServiceRequest(this, projectId, requestId, timeout, onProgress, signal),
+
+      /**
+       * Ask the service to stop a request made earlier. The request still
+       * ends with whatever the service then reports, on the stream of whoever
+       * is awaiting it. Rejects with 404 if unknown or expired, 409 once
+       * finished.
+       * @param {string} projectId - The UUID of the project
+       * @param {string} requestId - The request id
+       * @returns {Promise<void>}
+       */
+      cancelServiceRequest: (projectId, requestId) =>
+        cancelServiceRequest(this, projectId, requestId),
     };
 
     /**
@@ -1534,8 +2231,201 @@ class PlaidClient {
      *   For 'count': {return: 'count', count}. Entity cells are full entity objects
      *   (same shape as the GET endpoints).
      */
+    // bypassBatch: a query is a read. `client.batched()` flips one flag on the
+    // whole client, so a query issued by unrelated code while a batch is open
+    // (the IGT island fetching precedent while a document reconciles) used to
+    // be queued into it: the caller got `{batched: true}` instead of results,
+    // and the server ran the query against the batch's tx Connection, which
+    // 500s and rolls back every write in that batch.
     this.query = (body, auditMessage) =>
-      this._request('POST', '/api/v1/query', { auditMessage, body });
+      this._request("POST", "/api/v1/query", { auditMessage, body, bypassBatch: true });
+
+    // Logical-operation groups (audit-log grouping). There is no create: a
+    // group row is made lazily by the first write carrying `?group-id=`
+    // (see beginOperation). Not an audited write, so no auditMessage arg.
+    this.operationGroups = {
+      /**
+       * Get a logical-operation group (its label + creator).
+       * @param {string} id - The group id
+       */
+      get: (id) => this._request("GET", `/api/v1/operation-groups/${id}`),
+      /**
+       * Relabel a logical-operation group after the fact. Owner or admin only.
+       * @param {string} id - The group id
+       * @param {string|null} message - The new label
+       */
+      update: (id, message) =>
+        this._request("PATCH", `/api/v1/operation-groups/${id}`, {
+          body: { message },
+        }),
+    };
+
+    this.comments = {
+      /**
+       * Post a comment on an entity. Requires write access to the entity's
+       * project, or to the vocabulary for a vocab-item; the author is the
+       * authenticated caller. Comments are not audited and do not bump the
+       * document version.
+       *
+       * A comment outlives its anchor: deleting the entity does not delete
+       * the comment. `anchorLabel` is the caption shown once that happens
+       * ("Gloss of ktab, sentence 4"), so pass what the comment is about.
+       * @param {'document'|'text'|'token'|'span'|'relation'|'vocab-item'} entityType - What kind of thing is being commented on
+       * @param {string} entityId - The commented entity's id
+       * @param {string} body - The comment text (1..10000 characters)
+       * @param {object} [opts]
+       * @param {string} [opts.anchorLabel] - What the comment is about, in words (at most 200 characters)
+       */
+      create: (entityType, entityId, body, { anchorLabel } = {}) =>
+        this._request("POST", "/api/v1/comments", {
+          body: bodyOf({
+            "entity-type": entityType,
+            "entity-id": entityId,
+            body,
+            "anchor-label": anchorLabel,
+          }),
+        }),
+      /**
+       * Read one comment.
+       * @param {string} id - The comment id
+       */
+      get: (id) => this._request("GET", `/api/v1/comments/${id}`),
+      /**
+       * Edit a comment's body. Only the comment's AUTHOR may do this - not
+       * maintainers, not admins. Sets `edited` on the comment.
+       * @param {string} id - The comment id
+       * @param {string} body - The replacement text
+       */
+      update: (id, body) =>
+        this._request("PATCH", `/api/v1/comments/${id}`, { body: { body } }),
+      /**
+       * Delete a comment. The author may delete their own; a project
+       * maintainer (or admin) may delete any.
+       * @param {string} id - The comment id
+       */
+      delete: (id) => this._request("DELETE", `/api/v1/comments/${id}`),
+      /**
+       * List comments in a project, oldest first. Transparently follows
+       * pagination cursors and returns the full flat array.
+       * 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} projectId - The project to read
+       * @param {object} [filters] - Narrow the scope
+       * @param {string} [filters.documentId] - Every comment anywhere in one document
+       * @param {string} [filters.entityType] - With entityId, one entity's thread
+       * @param {string} [filters.entityId] - With entityType, one entity's thread
+       */
+      list: (projectId, { documentId, entityType, entityId } = {}) =>
+        listAll(this, `/api/v1/projects/${projectId}/comments`, {
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Fetch a single page of a project's comments.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {string} [opts.documentId] - Every comment anywhere in one document
+       * @param {string} [opts.entityType] - With entityId, one entity's thread
+       * @param {string} [opts.entityId] - With entityType, one entity's thread
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: (projectId, { limit, cursor, documentId, entityType, entityId } = {}) =>
+        listPage(this, `/api/v1/projects/${projectId}/comments`, {
+          limit,
+          cursor,
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Async-iterate a project's comments page by page; yields each page's entries array.
+       * 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.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.pageSize] - Per-request page size
+       * @param {string} [opts.documentId] - Every comment anywhere in one document
+       * @param {string} [opts.entityType] - With entityId, one entity's thread
+       * @param {string} [opts.entityId] - With entityType, one entity's thread
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: (projectId, { pageSize, documentId, entityType, entityId } = {}) =>
+        iterPages(this, `/api/v1/projects/${projectId}/comments`, {
+          pageSize,
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Comment counts per entity, as an `{entityId: n}` map, over the same
+       * scope and filters as `list`. One cheap request paints a comment
+       * indicator on every annotated item in a document without paging
+       * through the bodies.
+       *
+       * The response is NOT key-transformed: its keys are entity ids, and
+       * camelCasing would mangle the hyphens in a UUID.
+       * @param {string} projectId - The project to read
+       * @param {object} [filters] - Same filters as list()
+       * @returns {Promise<Object<string, number>>}
+       */
+      counts: (projectId, { documentId, entityType, entityId } = {}) =>
+        this._request("GET", `/api/v1/projects/${projectId}/comments/counts`, {
+          queryParams: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+          skipResponseTransform: true,
+        }),
+      /**
+       * List the comments on a vocabulary's entries, oldest first. Requires
+       * read access to the vocabulary. Transparently follows pagination
+       * cursors and returns the full flat array.
+       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching - use listInVocabPage() for a single page in a batch.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [filters]
+       * @param {string} [filters.entityId] - One entry's thread
+       */
+      listInVocab: (vocabId, { entityId } = {}) =>
+        listAll(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
+          query: { "entity-id": entityId },
+        }),
+      /**
+       * Fetch a single page of a vocabulary's comments.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {string} [opts.entityId] - One entry's thread
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listInVocabPage: (vocabId, { limit, cursor, entityId } = {}) =>
+        listPage(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
+          limit,
+          cursor,
+          query: { "entity-id": entityId },
+        }),
+      /**
+       * Comment counts per entry of a vocabulary, as an `{entityId: n}` map.
+       * The response is NOT key-transformed: its keys are entry ids.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [filters]
+       * @param {string} [filters.entityId] - One entry only
+       * @returns {Promise<Object<string, number>>}
+       */
+      countsInVocab: (vocabId, { entityId } = {}) =>
+        this._request("GET", `/api/v1/vocab-layers/${vocabId}/comments/counts`, {
+          queryParams: { "entity-id": entityId },
+          skipResponseTransform: true,
+        }),
+    };
   }
 
   // --- Core methods ---
@@ -1559,51 +2449,96 @@ class PlaidClient {
   }
 
   /**
-   * 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).
+   * Begin a LOGICAL OPERATION: a user-meaningful action ("Merge morphemes",
+   * "Re-transcribe") implemented as many low-level writes, possibly across
+   * several batches and even a service round-trip. Until `endOperation()`,
+   * every write is stamped with a client-minted `?group-id=` (and the message)
+   * so the audit log shows the whole run as ONE expandable entry labeled
+   * `message`, with each write's own description underneath.
+   *
+   * Grouping is orthogonal to batches: a batch is a transaction boundary, an
+   * operation is an intent boundary. An operation is NOT atomic — if write 3
+   * of 5 fails, writes 1–2 stay committed (and logged under the group). Use a
+   * batch inside the operation for any step that must be all-or-nothing.
+   *
+   * Nesting flattens: a `beginOperation` while one is open is a no-op that
+   * joins the outer operation (the outer label wins), and the matching
+   * `endOperation` is likewise a no-op. The label is recorded on the FIRST
+   * write, so an operation that is never ended (crash, closed tab) is still
+   * labeled in the log.
+   *
+   * @param {string} message - Human label for the operation.
+   * @param {object} [opts] - Optional `{ id }`: adopt an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically).
+   * @returns {string} The operation's group id.
    */
-  setAuditMessage(message) {
-    this.auditMessage = message;
-    return this;
+  beginOperation(message, { id } = {}) {
+    if (this.operationGroup) {
+      this.operationGroup.depth += 1;
+      return this.operationGroup.id;
+    }
+    this.operationGroup = {
+      id: id || crypto.randomUUID(),
+      message: message == null ? null : String(message),
+      depth: 1,
+      written: false,
+      refined: undefined,
+    };
+    return this.operationGroup.id;
   }
 
-  /** Clear the ambient custom audit-log message (revert to auto-generated). */
-  clearAuditMessage() {
-    this.auditMessage = null;
-    return this;
+  /**
+   * End the current logical operation. With no argument this is purely local
+   * (no request). Pass a refined `message` to relabel the group now that the
+   * outcome is known (e.g. `endOperation('Merged 3 morphemes')`) — that sends
+   * one PATCH, skipped if the operation never wrote anything. A refine from a
+   * nested (flattened) `endOperation` is ignored; the outer label wins.
+   * @param {string} [message] - Optional refined label.
+   * @returns {Promise<void>}
+   */
+  async endOperation(message) {
+    const group = this.operationGroup;
+    if (!group) return;
+    if (group.depth > 1) {
+      group.depth -= 1;
+      return;
+    }
+    this.operationGroup = null;
+    const refined = message !== undefined ? message : group.refined;
+    if (refined !== undefined && group.written) {
+      try {
+        await this.operationGroups.update(group.id, refined);
+      } catch (e) {
+        // 404: the group never materialized server-side (every tagged write
+        // failed or a batch was aborted). Nothing to relabel — not an error.
+        if (e.status !== 404) throw e;
+      }
+    }
   }
 
   /**
-   * 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):
+   * Run `fn` as one logical operation (see beginOperation), ending it when
+   * `fn` settles — including on throw. `fn` receives a `setMessage(msg)`
+   * callback to refine the label once the outcome is known.
    *
-   *   await client.withAuditMessage('Approve span {spanId}', () =>
-   *     client.spans.update(spanId, ...));
-   *
-   *   await client.withAuditMessage('Import sentence', async () => {
-   *     await client.tokens.create(...);
-   *     await client.spans.create(...);
+   *   await client.withOperation('Merge morphemes', async (setMessage) => {
+   *     await client.batched(() => { ... });
+   *     setMessage(`Merged ${n} morphemes`);
    *   });
    *
-   * @param {string} message - The custom message (template).
-   * @param {() => (Promise<any>|any)} fn - The work to run with the message set.
+   * @param {string} message - Human label for the operation.
+   * @param {function} fn - The work to run; receives `setMessage(msg)` to refine the label once the outcome is known.
    * @returns {Promise<any>} Whatever `fn` resolves to.
    */
-  async withAuditMessage(message, fn) {
-    const prev = this.auditMessage;
-    this.auditMessage = message;
+  async withOperation(message, fn) {
+    this.beginOperation(message);
+    const group = this.operationGroup;
+    const setMessage = (msg) => {
+      if (group.depth === 1) group.refined = msg;
+    };
     try {
-      return await fn();
+      return await fn(setMessage);
     } finally {
-      this.auditMessage = prev;
+      await this.endOperation();
     }
   }
 
@@ -1623,7 +2558,7 @@ class PlaidClient {
    */
   async submitBatch() {
     if (!this.isBatching) {
-      throw new Error('No active batch. Call beginBatch() first.');
+      throw new Error("No active batch. Call beginBatch() first.");
     }
 
     if (this.batchOperations.length === 0) {
@@ -1632,55 +2567,84 @@ class PlaidClient {
     }
 
     try {
-      let url = `${this.baseUrl}/api/v1/batch`;
-      const body = this.batchOperations.map(op => ({
+      const url = `${this.baseUrl}/api/v1/batch`;
+      const ops = this.batchOperations.map((op) => ({
         path: op.path,
         method: op.method.toUpperCase(),
         ...(op.body && { body: op.body }),
       }));
+      // The server caps a batch at MAX_BATCH_OPS so one transaction cannot
+      // hold the write lock without bound. A larger batch goes as consecutive
+      // requests, results concatenated in queue order: it could not have been
+      // one transaction anyway, and a repair or bulk edit over a big document
+      // must not fail on its size alone.
+      const results = [];
+      for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
+        results.push(...(await this._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))));
+      }
+      return results;
+    } finally {
+      this.isBatching = false;
+      this.batchOperations = [];
+    }
+  }
 
-      const fetchOptions = {
-        method: 'POST',
-        headers: {
-          'Authorization': `Bearer ${this.token}`,
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(body),
-      };
-      const signal = timeoutSignal(this.timeout);
-      if (signal) fetchOptions.signal = signal;
+  /** POST one batch request (at most MAX_BATCH_OPS operations); resolves to its transformed results. */
+  async _postBatch(url, body) {
+    const fetchOptions = {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    };
 
-      try {
-        const response = await fetch(url, fetchOptions);
-        if (!response.ok) {
-          throw makeHttpError(response, await parseErrorBody(response), url, 'POST');
+    try {
+      // Retry a 503: the batch is atomic, so a refused one wrote nothing and
+      // repeating it is safe. A fresh timeout signal per attempt — an
+      // AbortSignal.timeout stays aborted once it fires.
+      const response = await retryWhileBusy(async () => {
+        const signal = timeoutSignal(this.batchTimeout);
+        const res = await fetch(
+          url,
+          signal ? { ...fetchOptions, signal } : fetchOptions,
+        );
+        if (!res.ok) {
+          throw makeHttpError(res, await parseErrorBody(res), url, "POST");
         }
+        return res;
+      });
+
+      const results = await response.json();
 
-        const results = await response.json();
-
-        // Extract document versions from each batch response
-        for (const result of results) {
-          if (result.headers && result.headers['X-Document-Versions']) {
-            try {
-              const versionsMap = JSON.parse(result.headers['X-Document-Versions']);
-              if (typeof versionsMap === 'object' && versionsMap !== null) {
-                // Clone once per response, then merge — not once per entry.
-                this.documentVersions = { ...this.documentVersions, ...versionsMap };
-              }
-            } catch (e) {
-              console.warn('Failed to parse document versions header from batch response:', e);
+      // Extract document versions from each batch response
+      for (const result of results) {
+        if (result.headers && result.headers["X-Document-Versions"]) {
+          try {
+            const versionsMap = JSON.parse(
+              result.headers["X-Document-Versions"],
+            );
+            if (typeof versionsMap === "object" && versionsMap !== null) {
+              // Clone once per response, then merge — not once per entry.
+              this.documentVersions = {
+                ...this.documentVersions,
+                ...versionsMap,
+              };
             }
+          } catch (e) {
+            console.warn(
+              "Failed to parse document versions header from batch response:",
+              e,
+            );
           }
         }
-
-        return results.map(result => transformResponse(result));
-      } catch (error) {
-        if (error.status) throw error;
-        throw makeNetworkError(error, url, 'POST');
       }
-    } finally {
-      this.isBatching = false;
-      this.batchOperations = [];
+
+      return results.map((result) => transformResponse(result));
+    } catch (error) {
+      if (error.status) throw error;
+      throw makeNetworkError(error, url, "POST");
     }
   }
 
@@ -1739,29 +2703,114 @@ class PlaidClient {
    * @param {object} [options] - Client options forwarded to the constructor (e.g. { timeout })
    * @returns {Promise<PlaidClient>} - Authenticated client instance
    */
+  /**
+   * Build the link to hand someone for an invite code. The server never sees
+   * an app URL, so the app that minted the invite is the one that names it.
+   * Both SPAs use HashRouter, so the code rides in the fragment — which also
+   * keeps it out of server access logs.
+   * @param {string} appUrl - Where the SPA lives, e.g. "https://plaid.example.org/igt/"
+   * @param {string} code - The code returned by invites.create()
+   * @returns {string}
+   */
+  static inviteUrl(appUrl, code) {
+    return `${appUrl.replace(/#.*$/, "").replace(/\/$/, "")}/#/invite/${encodeURIComponent(code)}`;
+  }
+
+  /**
+   * Describe an invite code, with NO authentication — this is what a signup
+   * page calls before the redeemer has an account. Returns the kind of link
+   * ("signup" or "password-reset"), its status ("active", "used", "expired",
+   * "revoked"), and the project it grants access to, if any.
+   *
+   * Throws a 404-shaped error if the code is unknown. A known-but-dead code
+   * resolves normally with a non-"active" status, so the page can say why.
+   * @param {string} baseUrl - The API base URL
+   * @param {string} code - The invite code
+   * @param {object} [options]
+   * @returns {Promise<{kind: string, status: string, expiresAt: string, projectName?: string, projectRole?: string, email?: string, grantAdmin: boolean}>}
+   */
+  static async lookupInvite(baseUrl, code, options = {}) {
+    return anonymousPost(
+      baseUrl,
+      "/api/v1/invite-codes/lookup",
+      { code },
+      options,
+    );
+  }
+
+  /**
+   * Redeem an invite code, with NO authentication.
+   *
+   * For a signup invite, pass `email` and `password` to create the account
+   * (and optionally `displayName`); the invite's grants are applied in the
+   * same transaction. For a password reset link, pass `password` only.
+   * Resolves to a logged-in client, exactly like login() — the redeemer just
+   * chose these credentials, so there is no reason to send them to a login
+   * form to retype them.
+   * @param {string} baseUrl - The API base URL
+   * @param {string} code - The invite code
+   * @param {object} credentials
+   * @param {string} [credentials.email] - The new account's email address,
+   *   which becomes its id and login (signup only)
+   * @param {string} [credentials.displayName] - How the new user is shown in
+   *   the UI; defaults to the local part of the email (signup only)
+   * @param {string} credentials.password - Desired password (min 8 characters)
+   * @param {object} [options]
+   * @returns {Promise<{client: PlaidClient, userId: string, kind: string}>}
+   */
+  static async redeemInvite(
+    baseUrl,
+    code,
+    { email, password, displayName } = {},
+    options = {},
+  ) {
+    const data = await anonymousPost(
+      baseUrl,
+      "/api/v1/invite-codes/redeem",
+      bodyOf({ code, email, password, "display-name": displayName }),
+      options,
+    );
+    return {
+      client: new PlaidClient(
+        baseUrl.replace(/\/$/, ""),
+        data.token || "",
+        options,
+      ),
+      userId: data.userId,
+      kind: data.kind,
+    };
+  }
+
   static async login(baseUrl, userId, password, options = {}) {
-    baseUrl = baseUrl.replace(/\/$/, '');
+    baseUrl = baseUrl.replace(/\/$/, "");
     const url = `${baseUrl}/api/v1/login`;
     try {
       const fetchOptions = {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ 'user-id': userId, password }),
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ "user-id": userId, password }),
       };
-      const signal = timeoutSignal(options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS);
+      const signal = timeoutSignal(
+        options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
+      );
       if (signal) fetchOptions.signal = signal;
 
       const response = await fetch(url, fetchOptions);
       if (!response.ok) {
-        throw makeHttpError(response, await parseErrorBody(response), url, 'POST');
+        throw makeHttpError(
+          response,
+          await parseErrorBody(response),
+          url,
+          "POST",
+        );
       }
 
       const data = await response.json();
-      const token = data.token || '';
+      const token = data.token || "";
       return new PlaidClient(baseUrl, token, options);
     } catch (error) {
       if (error.status) throw error;
-      throw makeNetworkError(error, url, 'POST');
+      throw makeNetworkError(error, url, "POST");
     }
   }
 }
@@ -1771,8 +2820,21 @@ 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';
+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.
@@ -1784,18 +2846,34 @@ export {
   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".
+} from "./serviceSchema.js";
+// Provenance: the cross-app convention for who made an annotation (flat
+// prov/provSource/provConfirmed metadata; absence = a verifier; 'inferred' =
+// a machine; 'contributed' = a person whose work is reviewed), plus the
+// machine-writer contract. See ./provenance.js and the manual, "Provenance".
 export {
   PROV,
   PROV_STATES,
+  PROV_CONFIRMED,
   stampInferred,
   confirmedInferred,
+  stampContributed,
   provState,
+  provOrigin,
+  isMachine,
   isProtected,
+  needsReview,
   verifyOnEdit,
+  contributeOnEdit,
+  mergeMetadata,
   serviceSource,
-} from './provenance.js';
+  userSource,
+  REVIEW_KEY,
+  PROJECT_ROLES,
+  readReview,
+  projectRole,
+  isReviewed,
+  withReviewedUser,
+  writerPolicy,
+} from "./provenance.js";
+export { MAX_BATCH_OPS };