@larc-iu/plaid-client 0.2.0-alpha.13 → 0.2.0-alpha.14

package/src/index.js

@@ -15,6 +15,7 @@ import {
   DEFAULT_BATCH_TIMEOUT_MS,
 } from "./http.js";
 import { listAll, listPage, iterPages } from "./pagination.js";
+import { withDocumentLock } from "./documentLock.js";
 import { createSSEConnection } from "./sse.js";
 import {
   discoverServices,
@@ -145,6 +146,10 @@ class PlaidClient {
     this.batchOperations = [];
     this.documentVersions = {};
     this.strictModeDocumentId = null;
+    // Set to a DocumentLockLost while a `documents.locked()` block's keep-alive
+    // has failed. Every write throws it until the block exits; see
+    // documentLock.js.
+    this.documentLockLost = 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.
@@ -229,6 +234,7 @@ class PlaidClient {
        */
       get: (id, asOf) =>
         this._request("GET", `/api/v1/vocab-links/${id}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -248,6 +254,7 @@ class PlaidClient {
        */
       get: (id, includeItems, asOf) =>
         this._request("GET", `/api/v1/vocab-layers/${id}`, {
+          bypassBatch: true,
           queryParams: { "include-items": includeItems, "as-of": asOf },
         }),
       /**
@@ -294,7 +301,6 @@ class PlaidClient {
       /**
        * List all vocab layers accessible to user. 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} [asOf] - Temporal query timestamp
        */
       list: (asOf) =>
@@ -318,7 +324,6 @@ class PlaidClient {
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
        * @param {string} [opts.asOf] - Temporal query timestamp
-       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
       iterPages: ({ pageSize, asOf } = {}) =>
@@ -408,6 +413,7 @@ class PlaidClient {
        */
       get: (relationId, asOf) =>
         this._request("GET", `/api/v1/relations/${relationId}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -477,7 +483,7 @@ class PlaidClient {
         }),
       /**
        * Update many relations in a single operation: set values and/or patch metadata.
-       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The relations may lie in several documents of one project; every document touched has its version bumped. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The relations may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many relations were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -526,6 +532,7 @@ class PlaidClient {
        */
       get: (spanLayerId, asOf) =>
         this._request("GET", `/api/v1/span-layers/${spanLayerId}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -604,6 +611,7 @@ class PlaidClient {
        */
       get: (spanId, asOf) =>
         this._request("GET", `/api/v1/spans/${spanId}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -637,7 +645,7 @@ class PlaidClient {
         this._request("DELETE", "/api/v1/spans/bulk", { auditMessage, body }),
       /**
        * Update many spans in a single operation: set values and/or patch metadata.
-       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The spans may lie in several documents of one project; every document touched has its version bumped. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, value?, metadata?}`. `value` is set only when the key is present (null sends JSON null); `metadata` is a patch, a null value deleting that key. The spans may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many spans were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -785,6 +793,7 @@ class PlaidClient {
        */
       get: (textId, asOf) =>
         this._request("GET", `/api/v1/texts/${textId}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -816,7 +825,6 @@ class PlaidClient {
       /**
        * List (or search) users. Transparently follows pagination cursors and
        * returns the full flat array. Admin-or-maintainer only.
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @param {object} [opts]
        * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
        * @param {string} [opts.asOf] - Temporal query timestamp
@@ -844,7 +852,6 @@ class PlaidClient {
        * @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 } = {}) =>
@@ -874,7 +881,6 @@ class PlaidClient {
       /**
        * Get audit log for a user's actions. 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} userId - The user ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -925,6 +931,7 @@ class PlaidClient {
        */
       get: (id, asOf) =>
         this._request("GET", `/api/v1/users/${id}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -994,7 +1001,7 @@ class PlaidClient {
        */
       getAvatar: (id) =>
         this._request("GET", `/api/v1/users/${id}/avatar`, {
-          noBatch: true,
+          bypassBatch: true,
           binaryResponse: true,
         }),
       /**
@@ -1019,32 +1026,86 @@ class PlaidClient {
        * Remove a profile picture. Your own, or anyone's if you are an admin.
        * @param {string} id - The user ID
        */
+      // No flag: the upload beside this one is multipart and cannot be
+      // batched, but a DELETE carries no blob, so the batch transport takes
+      // it. It is an ordinary audited write and queues like any other.
       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.
+       * includeValues), ordered by key. Owner or admin only. Transparently
+       * follows pagination cursors and returns the full flat array.
        *
        * Narrow with `prefix` (the literal head of a key) and/or `pattern`, a
        * GLOB over the whole key (`*` any run, `?` one character) — the way to
        * ask for a key convention identified by a segment in the middle, e.g.
        * `igt:assistant:*:meta:*` for every conversation's sidebar entry across
        * every project without dragging down the transcripts beside them.
+       *
+       * `pageSize` is exposed here, and defaults lower than elsewhere, because
+       * one value runs to 1 MB: a page of them with `includeValues` is the
+       * largest response this API can be asked for. Raise it when the listing
+       * is keys, or the values are known to be small.
+       * @param {string} userId
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this prefix
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @param {number} [opts.pageSize=100] - Entries per request (1..1000)
+       */
+      list: (userId, { prefix, pattern, includeValues, pageSize = 100 } = {}) =>
+        // Every page carries bypassBatch (the pagination helpers set it): a
+        // read belongs to whoever asked for it, not to whatever batch happens
+        // to be open on this shared client. The assistant panel is app chrome
+        // in both SPAs, so it reads this store while an import or a bulk edit
+        // holds a batch open. Queued, the read answered `{batched: true}` (the
+        // sidebar then threw on `.map`) and took a slot in the batch's
+        // results, shifting every index the caller counted on.
+        listAll(this, `/api/v1/users/${userId}/data`, {
+          pageSize,
+          query: { prefix, pattern, "include-values": includeValues },
+        }),
+      /**
+       * One page of a user's private data entries, ordered by key.
+       * @param {string} userId
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this prefix
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @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: (
+        userId,
+        { prefix, pattern, includeValues, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/users/${userId}/data`, {
+          limit,
+          cursor,
+          query: { prefix, pattern, "include-values": includeValues },
+        }),
+      /**
+       * Async generator over a user's private data entries, one page at a time.
        * @param {string} userId
        * @param {object} [opts]
        * @param {string} [opts.prefix] - Only keys starting with this prefix
        * @param {string} [opts.pattern] - Only keys matching this GLOB
        * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @param {number} [opts.pageSize=100] - Entries per request (1..1000)
        */
-      list: (userId, { prefix, pattern, includeValues } = {}) =>
-        this._request("GET", `/api/v1/users/${userId}/data`, {
-          queryParams: { prefix, pattern, "include-values": includeValues },
+      iterPages: (
+        userId,
+        { prefix, pattern, includeValues, pageSize = 100 } = {},
+      ) =>
+        iterPages(this, `/api/v1/users/${userId}/data`, {
+          pageSize,
+          query: { prefix, pattern, "include-values": includeValues },
         }),
       /**
        * Read one private data entry ({key, updatedAt, value}); 404 if absent.
@@ -1052,9 +1113,11 @@ class PlaidClient {
        * @param {string} key
        */
       get: (userId, key) =>
+        // bypassBatch for the same reason as list() above.
         this._request(
           "GET",
           `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
+          { bypassBatch: true },
         ),
       /**
        * Create or replace one private data entry. `value` is any JSON (up to
@@ -1098,7 +1161,6 @@ class PlaidClient {
        * List a user's named API tokens. Never includes the signed token
        * string itself — that is only returned once, by create().
        * 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} userId - The user ID who owns the tokens
        */
       list: (userId) => listAll(this, `/api/v1/users/${userId}/tokens`),
@@ -1118,7 +1180,6 @@ class PlaidClient {
        * @param {string} userId - The user ID who owns the tokens
        * @param {object} [opts]
        * @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: (userId, { pageSize } = {}) =>
@@ -1154,7 +1215,6 @@ class PlaidClient {
        * 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
        * @param {boolean} [opts.all] - List every invite on the server (admin only)
@@ -1184,7 +1244,6 @@ class PlaidClient {
        * @param {string} [opts.projectId] - List this project's invites instead of your own
        * @param {boolean} [opts.all] - List every invite on the server (admin only)
        * @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, all, pageSize } = {}) =>
@@ -1259,35 +1318,48 @@ class PlaidClient {
        * walks the media directory, so open it, do not poll it. Admin only.
        * @returns {Promise<{version: string, jvm: object, database: object, media: object, backup: object, settings: object}>}
        */
-      server: () => this._request("GET", "/api/v1/admin/server"),
+      server: () =>
+        this._request("GET", "/api/v1/admin/server", { bypassBatch: true }),
       /**
        * Take a database backup right now, outside the nightly schedule.
        * Resolves to the backup block with `ok` reporting whether the snapshot
        * succeeded. Uses VACUUM INTO, which only reads, so it is safe while
        * people are working. Admin only.
        * @returns {Promise<{ok: boolean, directory: string, backups: Array}>}
+       *
+       * Goes over the wire even while a batch is open, as every admin action
+       * on the server itself does: none of them writes project data, and a
+       * backup taken inside somebody's open write transaction is not what the
+       * caller asked for.
        */
-      backup: () => this._request("POST", "/api/v1/admin/backup"),
+      backup: () =>
+        this._request("POST", "/api/v1/admin/backup", { bypassBatch: true }),
       /**
        * Documents currently held by an editing lock, with who holds each and
        * when it expires on its own. Admin only.
        * @returns {Promise<{entries: Array<{documentId: string, userId: string, expiresAt: number}>}>}
        */
-      locks: () => this._request("GET", "/api/v1/admin/locks"),
+      locks: () =>
+        this._request("GET", "/api/v1/admin/locks", { bypassBatch: true }),
       /**
        * Drop the lock on a document whoever holds it. Idempotent. For a client
        * that went away without releasing one. Admin only.
        * @param {string} documentId - The document ID
        */
       releaseLock: (documentId) =>
-        this._request("DELETE", `/api/v1/admin/locks/${documentId}`),
+        this._request("DELETE", `/api/v1/admin/locks/${documentId}`, {
+          bypassBatch: true,
+        }),
       /**
        * Live login and invite rate-limit buckets: the address, the account
        * where there is one, failures inside the window, the limit, and whether
        * it is currently blocking. Admin only.
        * @returns {Promise<{windowMs: number, logins: Array, ips: Array, invites: Array}>}
        */
-      rateLimits: () => this._request("GET", "/api/v1/admin/rate-limits"),
+      rateLimits: () =>
+        this._request("GET", "/api/v1/admin/rate-limits", {
+          bypassBatch: true,
+        }),
       /**
        * Forget recorded rate-limit failures. With `ip`, clears that address,
        * narrowed to one account with `userId`. With neither, clears every
@@ -1298,18 +1370,45 @@ class PlaidClient {
        */
       clearRateLimits: ({ ip, userId } = {}) =>
         this._request("DELETE", "/api/v1/admin/rate-limits", {
+          bypassBatch: true,
           queryParams: { ip, "user-id": userId },
         }),
       /**
-       * The tail of the configured log file. Resolves with an `error` string
-       * instead of lines when no log file is configured or it does not exist
-       * yet. Admin only.
+       * What the server has logged, structured and filtered, from an in-memory
+       * buffer kept whether or not a log file is configured. `requests` is one
+       * entry per HTTP request (method, path, status, duration, and who made
+       * it), `events` is everything else, with a stack trace where there was
+       * one. They are buffered separately so a burst of requests cannot evict
+       * an error. Both come newest first, `matched` counts what passed the
+       * filters, and request `stats` describe the filtered set. Covers Plaid's
+       * own log stream since the last restart: for library messages and older
+       * history, see `logFile`. Admin only.
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Max entries per kind (default 200, max 2000)
+       * @param {string} [opts.q] - Substring of any field, case-insensitive
+       * @param {string} [opts.level] - Minimum level for events, e.g. "warn"
+       * @param {string} [opts.status] - "2xx".."5xx", an exact code, or "failures"
+       * @param {string} [opts.user] - Only requests made by this account
+       * @param {string} [opts.method] - Only requests with this HTTP method
+       * @returns {Promise<{requests: object, events: object, file: (string|null)}>}
+       */
+      logs: ({ limit, q, level, status, user, method } = {}) =>
+        this._request("GET", "/api/v1/admin/logs", {
+          bypassBatch: true,
+          queryParams: { limit, q, level, status, user, method },
+        }),
+      /**
+       * The tail of the configured log file, as text lines. The only place
+       * third-party library messages and anything from before the last restart
+       * can be read. Resolves with an `error` string instead of lines when no
+       * log file is configured or it does not exist yet. Admin only.
        * @param {object} [opts]
        * @param {number} [opts.lines] - How many lines (default 200, max 2000)
        * @returns {Promise<{file: (string|null), lines: string[], error?: string}>}
        */
-      logs: ({ lines } = {}) =>
-        this._request("GET", "/api/v1/admin/logs", {
+      logFile: ({ lines } = {}) =>
+        this._request("GET", "/api/v1/admin/logs/file", {
+          bypassBatch: true,
           queryParams: { lines },
         }),
       /**
@@ -1323,7 +1422,6 @@ class PlaidClient {
        * ask for a key convention identified by a segment in the middle, e.g.
        * `igt:assistant:*:meta:*`. Values come only with `includeValues`, and
        * are recased like any other body (see `userData.put`).
-       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use userDataPage() for a single page in a batch.
        * @param {object} [opts]
        * @param {string} [opts.prefix] - Only keys starting with this
        * @param {string} [opts.pattern] - Only keys matching this GLOB
@@ -1367,7 +1465,6 @@ class PlaidClient {
        * and op-type filter as the per-project read, with the entity scope
        * dropped. Admin only. 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.startTime] - Only operations at or after this instant
        * @param {string} [opts.endTime] - Only operations at or before this instant
@@ -1405,7 +1502,6 @@ class PlaidClient {
         }),
       /**
        * Async-iterate the instance-wide audit log page by page. Admin only.
-       * 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: ({ startTime, endTime, opTypes, pageSize } = {}) =>
@@ -1440,6 +1536,7 @@ class PlaidClient {
           ? `/api/v1/projects/${projectId}/audit/tally`
           : "/api/v1/audit/tally";
         const result = await this._request("GET", path, {
+          bypassBatch: true,
           queryParams: {
             "start-time": startTime,
             "end-time": endTime,
@@ -1522,6 +1619,7 @@ class PlaidClient {
        */
       get: (tokenLayerId, asOf) =>
         this._request("GET", `/api/v1/token-layers/${tokenLayerId}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -1552,24 +1650,72 @@ class PlaidClient {
        */
       checkLock: (documentId, asOf) =>
         this._request("GET", `/api/v1/documents/${documentId}/lock`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
-       * Acquire or refresh a document lock
+       * Acquire or refresh a document lock.
+       *
+       * Goes over the wire even while a batch is open. The lock is an
+       * out-of-band signal, not project data: a queued acquire is taken only
+       * when the batch submits, which is after every write it was meant to
+       * guard, and until then it answers success to a caller that does not
+       * hold it and cannot see the 423 saying somebody else does.
        * @param {string} documentId - The document ID
        */
       acquireLock: (documentId, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/lock`, {
           auditMessage,
+          bypassBatch: true,
         }),
       /**
-       * Release a document lock
+       * Release a document lock. Goes over the wire even while a batch is
+       * open, for the same reason as acquireLock: queued, the lock is held
+       * until the batch submits, and not released at all if it aborts.
        * @param {string} documentId - The document ID
        */
       releaseLock: (documentId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/lock`, {
           auditMessage,
+          bypassBatch: true,
         }),
+      /**
+       * Hold this document's server-enforced lock for the length of `fn`,
+       * releasing it on the way out (including on error). Resolves to what
+       * `fn` returned.
+       *
+       *   await client.documents.locked(docId, async () => {
+       *     // delete + recreate tokens
+       *   });
+       *
+       * Wrap any multi-step, server-side mutation of a document that must not
+       * interleave with a human editor or another service, e.g. a parser or
+       * tokenizer that deletes and recreates a document's tokens, spans and
+       * relations. A single atomic call does not need it. While the lock is
+       * held, writes to the document by ANOTHER user are refused with HTTP
+       * 423; the holder's own writes pass and renew it. If another user
+       * already holds it this rejects with a readable 423 and `fn` does not
+       * run.
+       *
+       * The lock is renewed for as long as `fn` runs, so work that computes
+       * for minutes before it writes holds the lock the whole time rather than
+       * only for its first minute. If a renewal fails the lock is gone: every
+       * later write from this client throws `DocumentLockLost`, and a block
+       * that got to the end anyway ends with that error rather than reporting
+       * success. `fn` receives a lock handle and may read `lock.lost` (or call
+       * `lock.raiseIfLost()`) to give up sooner.
+       *
+       * NOT re-entrant: nesting two `locked()` blocks on one document would
+       * release on the inner exit and leave the outer unprotected. Lock at
+       * exactly one level per call path. A lost lock is recorded on the
+       * CLIENT, like batch and strict mode, so it stops every write the client
+       * makes and not only the ones this block makes.
+       * @param {string} documentId - The document ID
+       * @param {(lock: DocumentLock) => any} fn - The work to run while holding it
+       * @param {object} [options] - `{ keepAlive }`: renew on a timer (default true)
+       */
+      locked: (documentId, fn, options) =>
+        withDocumentLock(this, documentId, fn, options),
       /**
        * 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
@@ -1578,7 +1724,7 @@ class PlaidClient {
        */
       getMedia: (documentId) =>
         this._request("GET", `/api/v1/documents/${documentId}/media`, {
-          noBatch: true,
+          bypassBatch: true,
           binaryResponse: true,
         }),
       /**
@@ -1603,10 +1749,14 @@ class PlaidClient {
        * Delete media file for a document
        * @param {string} documentId - The document ID
        */
+      // No flag: the upload above is multipart and cannot be batched, but a
+      // DELETE carries no blob, so the batch transport takes it. It is a write
+      // of the document's own data and queues like any other. Note that the
+      // file removal happens outside the server's transaction, so a batch that
+      // aborts after this op does not bring the file back.
       deleteMedia: (documentId, auditMessage) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/media`, {
           auditMessage,
-          noBatch: true,
         }),
       /**
        * Replace all metadata for a document.
@@ -1642,7 +1792,6 @@ class PlaidClient {
       /**
        * Get audit log for a document. 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} documentId - The document ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -1725,6 +1874,7 @@ class PlaidClient {
        */
       get: (documentId, includeBody, asOf, layers) =>
         this._request("GET", `/api/v1/documents/${documentId}`, {
+          bypassBatch: true,
           queryParams: {
             "include-body": includeBody,
             "as-of": asOf,
@@ -1866,7 +2016,6 @@ class PlaidClient {
       /**
        * Get audit log for a project. 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 ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -1922,6 +2071,7 @@ class PlaidClient {
        */
       myLastEdits: (projectId) =>
         this._request("GET", `/api/v1/projects/${projectId}/audit/last-edits`, {
+          bypassBatch: true,
           skipResponseTransform: true,
         }),
       /**
@@ -1950,12 +2100,12 @@ class PlaidClient {
        */
       get: (id, asOf) =>
         this._request("GET", `/api/v1/projects/${id}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
        * List all documents in a project. 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.
        *
        * Note: this endpoint does not support temporal (`as-of`) queries; the
        * server rejects `?as-of=` on the documents-list route with a 400.
@@ -1984,7 +2134,6 @@ class PlaidClient {
        * @param {string} id - The project ID
        * @param {object} [opts]
        * @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>}
        */
       iterDocuments: (id, { pageSize } = {}) =>
@@ -2018,7 +2167,6 @@ class PlaidClient {
       /**
        * List all projects accessible to user. 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} [asOf] - Temporal query timestamp
        */
       list: (asOf) =>
@@ -2042,7 +2190,6 @@ class PlaidClient {
        * @param {object} [opts]
        * @param {number} [opts.pageSize] - Per-request page size
        * @param {string} [opts.asOf] - Temporal query timestamp
-       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
       iterPages: ({ pageSize, asOf } = {}) =>
@@ -2100,6 +2247,7 @@ class PlaidClient {
        */
       get: (textLayerId, asOf) =>
         this._request("GET", `/api/v1/text-layers/${textLayerId}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -2212,6 +2360,7 @@ class PlaidClient {
        */
       get: (id, asOf) =>
         this._request("GET", `/api/v1/vocab-items/${id}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -2292,6 +2441,7 @@ class PlaidClient {
        */
       get: (relationLayerId, asOf) =>
         this._request("GET", `/api/v1/relation-layers/${relationLayerId}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -2360,6 +2510,7 @@ class PlaidClient {
        */
       get: (tokenId, asOf) =>
         this._request("GET", `/api/v1/tokens/${tokenId}`, {
+          bypassBatch: true,
           queryParams: { "as-of": asOf },
         }),
       /**
@@ -2399,7 +2550,7 @@ class PlaidClient {
         this._request("DELETE", "/api/v1/tokens/bulk", { auditMessage, body }),
       /**
        * Update many tokens in a single operation: patch metadata.
-       * @param {Array} body - Objects of the shape `{id, metadata}`. `metadata` is a patch, a null value deleting that key. The tokens may lie in several documents of one project; every document touched has its version bumped. An unknown id refuses the whole update.
+       * @param {Array} body - Objects of the shape `{id, metadata}`. `metadata` is a patch, a null value deleting that key. The tokens may lie in several documents of one project; every document touched has its version bumped and every new version comes back in `X-Document-Versions`. A `document-version` precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
        * @returns {Promise<{count: number}>} How many tokens were updated.
        */
       bulkUpdate: (body, auditMessage) =>
@@ -2510,7 +2661,8 @@ class PlaidClient {
       /**
        * Discover the services seen on a project (synchronous GET). Currently
        * connected services carry `online: true`; previously-seen offline ones
-       * carry `online: false` plus a `lastSeenAt` stamp.
+       * carry `online: false` plus a `lastSeenAt` stamp. Goes over the wire
+       * even while a batch is open on the client.
        * @param {string} projectId - The UUID of the project to query
        * @returns {Promise<Array>} Array of discovered service information
        */
@@ -2680,7 +2832,10 @@ class PlaidClient {
        * Get a logical-operation group (its label + creator).
        * @param {string} id - The group id
        */
-      get: (id) => this._request("GET", `/api/v1/operation-groups/${id}`),
+      get: (id) =>
+        this._request("GET", `/api/v1/operation-groups/${id}`, {
+          bypassBatch: true,
+        }),
       /**
        * Relabel a logical-operation group after the fact. Owner or admin only.
        * @param {string} id - The group id
@@ -2721,7 +2876,8 @@ class PlaidClient {
        * Read one comment.
        * @param {string} id - The comment id
        */
-      get: (id) => this._request("GET", `/api/v1/comments/${id}`),
+      get: (id) =>
+        this._request("GET", `/api/v1/comments/${id}`, { bypassBatch: true }),
       /**
        * Edit a comment's body. Only the comment's AUTHOR may do this - not
        * maintainers, not admins. Sets `edited` on the comment.
@@ -2739,7 +2895,6 @@ class PlaidClient {
       /**
        * 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
@@ -2780,7 +2935,6 @@ class PlaidClient {
         }),
       /**
        * 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
@@ -2815,6 +2969,7 @@ class PlaidClient {
        */
       counts: (projectId, { documentId, entityType, entityId } = {}) =>
         this._request("GET", `/api/v1/projects/${projectId}/comments/counts`, {
+          bypassBatch: true,
           queryParams: {
             "document-id": documentId,
             "entity-type": entityType,
@@ -2826,7 +2981,6 @@ class PlaidClient {
        * 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
@@ -2863,6 +3017,7 @@ class PlaidClient {
           "GET",
           `/api/v1/vocab-layers/${vocabId}/comments/counts`,
           {
+            bypassBatch: true,
             queryParams: { "entity-id": entityId },
             skipResponseTransform: true,
           },
@@ -2909,6 +3064,12 @@ class PlaidClient {
    * write, so an operation that is never ended (crash, closed tab) is still
    * labeled in the log.
    *
+   * "Every write" is the writes of project data. Reads never join, and neither
+   * do the out-of-band signals shaped like a write (a document lock taken or
+   * renewed, a stopped service request, a service reporting itself, an admin
+   * control): none of them is audited, so there would be nothing under the
+   * label.
+   *
    * @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.
@@ -2984,12 +3145,15 @@ class PlaidClient {
     }
   }
 
-  /** Begin a batch of operations. Subsequent API calls will be queued. */
+  /**
+   * Begin a batch of operations. Subsequent WRITES are queued; reads and
+   * out-of-band signals still go over the wire (see `batched`).
+   */
   beginBatch() {
     this.isBatching = true;
     this.batchOperations = [];
-    // Strict mode stamps the expected document-version on the FIRST write of
-    // the batch only (see _request) — reset the marker per batch.
+    // Strict mode stamps the expected document-version on the FIRST QUEUED
+    // write of the batch only (see _request), so reset the marker per batch.
     this.batchVersionStamped = false;
   }
 
@@ -3122,6 +3286,18 @@ class PlaidClient {
    * parents created earlier in the same `fn`; any op's failure rolls the whole
    * batch back). Not nestable. Named `batched()` because `client.batch` is the
    * low-level batch resource.
+   *
+   * WRITES are what a batch queues, and batch mode is one flag on the whole
+   * client, so it catches every write made while it is open, including writes
+   * made by code that knows nothing about this batch. READS are never caught:
+   * every read method goes over the wire while a batch is open and is answered
+   * from the state the batch has not committed yet, so a read cannot come back
+   * as a batch marker and cannot take a slot in the results array. Neither are
+   * the calls that signal something out of band rather than write project data:
+   * stopping a service request, a service reporting its progress or result,
+   * taking and dropping a document lock, and the admin actions on the server
+   * itself. See the note at the top of `http.js` for which column a new
+   * endpoint belongs in.
    * @param {() => (void | Promise<void>)} fn
    * @returns {Promise<Array>}
    */
@@ -3313,6 +3489,14 @@ export {
 // request, and `critical()` holds that off around writes. See ./services.js
 // and the manual, "Stopping a request".
 export { ServiceCancelled, createCancelScope } from "./services.js";
+// Document locks: `client.documents.locked()` holds one for a block of work and
+// renews it while the block runs. DocumentLockLost is what a write throws once
+// a renewal has failed. See ./documentLock.js.
+export {
+  DOCUMENT_LOCK_TTL_MS,
+  DocumentLock,
+  DocumentLockLost,
+} from "./documentLock.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