@larc-iu/plaid-client 0.2.0-alpha.20 → 0.2.0-alpha.22

package/src/index.js

@@ -20,6 +20,7 @@ import {
   REPLAYED_HEADER,
   DEFAULT_TIMEOUT_MS,
   DEFAULT_BATCH_TIMEOUT_MS,
+  queryTimeout,
 } from "./http.js";
 import { uuidv7 } from "./ids.js";
 import { constraintsBody } from "./constraints.js";
@@ -133,6 +134,27 @@ async function anonymousGet(baseUrl, path, options = {}) {
  */
 const MAX_BATCH_OPS = 1000;
 
+/**
+ * The kinds an operation may say it is (`?group-kind=`), the server's closed
+ * list (plaid.sql.operation-group/kinds). An operation of any other kind is
+ * refused when it begins, before it writes anything.
+ */
+const OPERATION_KINDS = [
+  "assistant-plan",
+  "service-run",
+  "import",
+  "bulk-edit",
+  "guess-adoption",
+  "repair",
+  "review",
+];
+
+/**
+ * How long `admin.backup()` waits for the server to finish writing a backup:
+ * minutes on a large database, past the usual per-request timeout.
+ */
+export const BACKUP_TIMEOUT_MS = 30 * 60 * 1000;
+
 /**
  * A batch is the client with a different `_request` (see `queueRequest`) and
  * its own copy of the bundles. Everything else resolves to the client through
@@ -337,10 +359,37 @@ class PlaidClient {
     // the stored token and route back to login. See makeRequest in http.js.
     this.onAuthError = options.onAuthError || null;
     this._authErrorFired = false;
+    // Who hears that a request is being sent again (onRetry).
+    this._retryListeners = new Set();
 
     this._installResources();
   }
 
+  /**
+   * Hear every time a request is sent again: after a 503 (the database was
+   * busy), or for a keyed write after its answer was lost (no response, 502,
+   * 504). The listener gets `{ attempt, retries, delay, error }` before the
+   * wait. A screen that writes through the client directly can say it is
+   * retrying while the server does not answer, though the browser is online.
+   * @param {(info: {attempt: number, retries: number, delay: number, error: Error}) => void} listener
+   * @returns {() => void} the unsubscribe
+   */
+  onRetry(listener) {
+    this._retryListeners.add(listener);
+    return () => this._retryListeners.delete(listener);
+  }
+
+  /** Tell every `onRetry` listener. A listener that throws is passed over. */
+  _noteRetry(info) {
+    for (const listener of this._retryListeners) {
+      try {
+        listener(info);
+      } catch (_) {
+        /* a listener must not stop the retry */
+      }
+    }
+  }
+
   /**
    * The server's time now, as its last response's Date header put it (to the
    * second), else this machine's. Judge a time the server stamped, such as an
@@ -495,13 +544,17 @@ class PlaidClient {
        * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {number} [opts.opsLimit] - Keep only each entry's oldest N
+       *   operations in `ops` (1..1000). `opCount` on every entry says how
+       *   many it has
+       * @param {string} [opts.entryId] - Read only this entry, not a page
        * @param {string} [opts.itemId] - Only the changes that wrote this one
        *   entry, each with only its operations that did
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
       auditPage: (
         id,
-        { startTime, endTime, opTypes, kinds, order, limit, cursor, itemId } = {},
+        { startTime, endTime, opTypes, kinds, order, limit, cursor, opsLimit, entryId, itemId } = {},
       ) =>
         listPage(this, `/api/v1/vocab-layers/${id}/audit`, {
           limit,
@@ -512,6 +565,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
             "item-id": itemId,
           },
         }),
@@ -1140,14 +1195,14 @@ class PlaidClient {
        * List (or search) users. Transparently follows pagination cursors and
        * returns the full flat array. Admin-or-maintainer only.
        * @param {object} [opts]
-       * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
+       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
        */
       list: ({ q } = {}) =>
         listAll(this, "/api/v1/users", { query: { q } }),
       /**
        * Fetch a single page of users (optionally filtered by `q`).
        * @param {object} [opts]
-       * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
+       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
        * @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)}>}
@@ -1161,7 +1216,7 @@ class PlaidClient {
       /**
        * Async-iterate users page by page; yields each page's entries array.
        * @param {object} [opts]
-       * @param {string} [opts.q] - Filter to users whose display name or email contains this text (case-insensitive)
+       * @param {string} [opts.q] - Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
        * @param {number} [opts.pageSize] - Per-request page size
        * @returns {AsyncGenerator<Array>}
        */
@@ -1171,7 +1226,8 @@ class PlaidClient {
           query: { q },
         }),
       /**
-       * Create a new user.
+       * Create a new user. Admin only, and not with a named API token (403):
+       * it needs a sign-in token.
        * @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
@@ -1222,11 +1278,15 @@ class PlaidClient {
        * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {number} [opts.opsLimit] - Keep only each entry's oldest N
+       *   operations in `ops` (1..1000). `opCount` on every entry says how
+       *   many it has
+       * @param {string} [opts.entryId] - Read only this entry, not a page
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
       auditPage: (
         userId,
-        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, kinds, order, limit, cursor, opsLimit, entryId } = {},
       ) =>
         listPage(this, `/api/v1/users/${userId}/audit`, {
           limit,
@@ -1237,6 +1297,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
           },
         }),
       /**
@@ -1266,7 +1328,8 @@ class PlaidClient {
       /**
        * 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.
+       * name or password. A password change cannot be made with a named API
+       * token (403): it needs a sign-in token.
        *
        * 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.
@@ -1489,6 +1552,8 @@ class PlaidClient {
        * Mint a named API token for a user. The returned `token` is the signed
        * credential and is shown ONLY here — store it immediately. API tokens
        * do not expire and survive password changes / logout; revoke to kill.
+       * A client signed in with a named API token cannot do this (403): it
+       * needs a sign-in token.
        * @param {string} userId - The user ID who will own the token
        * @param {string} name - A human label, e.g. "Stanza parser"
        * @returns {Promise<{id: string, name: string, token: string}>}
@@ -1497,11 +1562,14 @@ class PlaidClient {
         this._request("POST", `/api/v1/users/${userId}/tokens`, {
           auditMessage,
           body: bodyOf({ name }),
-          // The answer is the secret, which the server never keeps.
-          noIdempotency: true,
+          // The answer is the secret, which the server never keeps, so it
+          // takes no Idempotency-Key and a batch cannot carry it.
+          noBatch: true,
         }),
       /**
        * Revoke a named API token (soft-revoke; idempotent).
+       * A client signed in with a named API token cannot do this (403): it
+       * needs a sign-in token.
        * @param {string} userId - The user ID who owns the token
        * @param {string} tokenId - The token ID to revoke
        */
@@ -1564,6 +1632,9 @@ class PlaidClient {
        * invite, no password resets — so for a non-admin, projectId/projectRole
        * are required in practice (403 without them).
        *
+       * Needs a signed-in session: a client signed in with a named API token
+       * cannot mint any invite (403).
+       *
        * 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
@@ -1593,8 +1664,9 @@ class PlaidClient {
       ) =>
         this._request("POST", "/api/v1/invites", {
           auditMessage,
-          // The answer is the code, which the server never keeps.
-          noIdempotency: true,
+          // The answer is the code, which the server never keeps, so it
+          // takes no Idempotency-Key and a batch cannot carry it.
+          noBatch: true,
           body: bodyOf({
             "project-id": projectId,
             "project-role": projectRole,
@@ -1629,13 +1701,22 @@ class PlaidClient {
        * 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.
+       *
+       * The server answers once the backup is written, which takes minutes on
+       * a large database, so this waits up to `BACKUP_TIMEOUT_MS` (30 minutes)
+       * rather than the client's usual timeout. A proxy in front of the server
+       * may still give up first (a 504): the backup goes on, and its file
+       * shows in `server().backup.backups` once it is written.
        * @returns {Promise<{ok: boolean, directory: string, backups: Array}>}
        *
        * outOfBand, as every admin action on the server itself is: none of them
        * writes project data (see the note at the top of http.js).
        */
       backup: () =>
-        this._request("POST", "/api/v1/admin/backup", { outOfBand: true }),
+        this._request("POST", "/api/v1/admin/backup", {
+          outOfBand: true,
+          timeout: BACKUP_TIMEOUT_MS,
+        }),
       /**
        * Documents currently held by an editing lock, with who holds each and
        * when it expires on its own. Admin only.
@@ -1786,9 +1867,13 @@ class PlaidClient {
        *   is what a feed wants. A cursor belongs to the direction that made it.
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {number} [opts.opsLimit] - Keep only each entry's oldest N
+       *   operations in `ops` (1..1000). `opCount` on every entry says how
+       *   many it has
+       * @param {string} [opts.entryId] - Read only this entry, not a page
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ startTime, endTime, opTypes, kinds, order, limit, cursor } = {}) =>
+      listPage: ({ startTime, endTime, opTypes, kinds, order, limit, cursor, opsLimit, entryId } = {}) =>
         listPage(this, "/api/v1/audit", {
           limit,
           cursor,
@@ -1798,6 +1883,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
           },
         }),
       /**
@@ -2059,6 +2146,11 @@ class PlaidClient {
         }),
       /**
        * Upload a media file for a document. Uses Apache Tika for content validation.
+       * A document that already has a recording refuses it with a 409
+       * (`media-exists`, and the current `media-url`): delete that one first.
+       * A WAV whose samples are not PCM or float (IMA or MS ADPCM, GSM, A-law
+       * and the rest), which browsers cannot play, is refused with a 415
+       * whose `error` names its coding.
        * @param {string} documentId - The document ID
        * @param {File} file - The file to upload
        * @param {string} [auditMessage] - Custom audit-log message for this write
@@ -2078,15 +2170,21 @@ class PlaidClient {
       /**
        * Delete media file for a document
        * @param {string} documentId - The document ID
+       * @param {string} [auditMessage] - Audit message for this write
+       * @param {{mediaVersion?: string}} [options] - `mediaVersion`: the
+       *   recording meant, the `?v=` of the document's `mediaUrl`. The delete
+       *   is refused with a 409 (`media-changed`, and the current `media-url`)
+       *   when the stored recording is another one.
        */
       // 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) =>
+      deleteMedia: (documentId, auditMessage, { mediaVersion } = {}) =>
         this._request("DELETE", `/api/v1/documents/${documentId}/media`, {
           auditMessage,
+          queryParams: { "media-version": mediaVersion },
         }),
       /**
        * Replace all metadata for a document.
@@ -2147,11 +2245,15 @@ class PlaidClient {
        * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {number} [opts.opsLimit] - Keep only each entry's oldest N
+       *   operations in `ops` (1..1000). `opCount` on every entry says how
+       *   many it has
+       * @param {string} [opts.entryId] - Read only this entry, not a page
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
       auditPage: (
         documentId,
-        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, kinds, order, limit, cursor, opsLimit, entryId } = {},
       ) =>
         listPage(this, `/api/v1/documents/${documentId}/audit`, {
           limit,
@@ -2162,6 +2264,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
           },
         }),
       /**
@@ -2377,11 +2481,15 @@ class PlaidClient {
        * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {number} [opts.opsLimit] - Keep only each entry's oldest N
+       *   operations in `ops` (1..1000). `opCount` on every entry says how
+       *   many it has
+       * @param {string} [opts.entryId] - Read only this entry, not a page
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
       auditPage: (
         projectId,
-        { startTime, endTime, opTypes, kinds, order, limit, cursor } = {},
+        { startTime, endTime, opTypes, kinds, order, limit, cursor, opsLimit, entryId } = {},
       ) =>
         listPage(this, `/api/v1/projects/${projectId}/audit`, {
           limit,
@@ -2392,6 +2500,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
           },
         }),
       /**
@@ -2709,8 +2819,11 @@ class PlaidClient {
        * losers are deleted. Links are read when the merge runs, so one made
        * after the caller looked moves too. Every loser must be in the
        * survivor's vocabulary, and a loser that is already gone is skipped, so
-       * a repeated merge changes nothing. References to a loser in other
-       * entries' metadata are the caller's to rewrite, in the same batch.
+       * a repeated merge changes nothing. Metadata naming a loser by its id,
+       * in the vocabulary's other entries and in the documents of every
+       * project it is linked to, is rewritten to name the survivor. A
+       * reference to a loser in the survivor's own metadata is the caller's to
+       * rewrite, in the same batch.
        * Needs maintainer rights on the vocabulary.
        * @param {string} survivorId - The entry that stays
        * @param {string[]} loserIds - The entries merged into it
@@ -2913,8 +3026,11 @@ class PlaidClient {
        * @param {string} tokenId - The token ID
        * @param {number} position - Code-point offset to split at (strictly between begin and end)
        * @param {string} [auditMessage] - Audit message for this write
-       * @param {{id?: string}} [options] - `id`: the right half's id, a UUIDv7 this
-       *   client minted. A relation layer whose relations must stay inside one token
+       * @param {{id?: string, keep?: "left"|"right"}} [options] - `id`: the new
+       *   token's id, a UUIDv7 this client minted. `keep`: the half the original token
+       *   (its id, spans, vocab-links, comments and metadata) stays on, `"left"` by
+       *   default. With `"right"` the new token, whose id is answered, is the left
+       *   half. A relation layer whose relations must stay inside one token
        *   of this layer declares a same-ancestor constraint, and the server deletes
        *   the relations the split leaves crossing in the same transaction.
        */
@@ -2922,11 +3038,11 @@ class PlaidClient {
         tokenId,
         position,
         auditMessage,
-        { id } = {},
+        { id, keep } = {},
       ) =>
         this._request("POST", `/api/v1/tokens/${tokenId}/split`, {
           auditMessage,
-          body: bodyOf({ id, position }),
+          body: bodyOf({ id, keep, position }),
         }),
       /**
        * Merge two tokens. The left token (smaller begin) survives with the combined
@@ -3175,9 +3291,16 @@ class PlaidClient {
      */
     // outOfBand: a query is a read that travels as a POST (see the note at
     // the top of http.js). Made on a batch it goes over the wire like any
-    // read, and it never joins a logical operation.
+    // read, and it never joins a logical operation. It waits past core's own
+    // query limit, so a query too broad answers with core's 408, and a 503
+    // from core's full queue of large queries is not retried.
     this.query = (body) =>
-      this._request("POST", "/api/v1/query", { body, outOfBand: true });
+      this._request("POST", "/api/v1/query", {
+        body,
+        outOfBand: true,
+        timeout: queryTimeout(this),
+        noBusyRetry: true,
+      });
 
     // Logical-operation groups (audit-log grouping). There is no create: a
     // group row is made lazily by the first write carrying `?group-id=`
@@ -3638,6 +3761,7 @@ class PlaidClient {
    * `kind` says what kind of operation this is, for a program reading the
    * log: one of `assistant-plan`, `service-run`, `import`, `bulk-edit`,
    * `guess-adoption`, `repair` or `review` (the server refuses any other).
+   * Any other kind throws here, before anything is written.
    * `ref` is a short string naming what the operation came from, in the
    * shape its kind documents (the core manual, "Kinds of operation"). Both
    * are recorded from the first write like the label, and a nested operation
@@ -3653,10 +3777,15 @@ class PlaidClient {
    * matching end, and the outer numbering resumes after it.
    *
    * @param {string} message - Human label for the operation.
-   * @param {object} [opts] - Optional `{ id, kind, ref, keys }`. `id` adopts an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically). `kind`, `ref` and `keys` are described above.
+   * @param {object} [opts] - Optional `{ groupId, kind, ref, keys, minted }`. `groupId` adopts an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically). Python's is `group_id`. `kind`, `ref` and `keys` are described above. `minted` is the ids the operation mints for what it creates: a create refused 409 id-taken for one of them was made by an earlier send of the operation, and answers as made.
    * @returns {string} The operation's group id.
    */
-  beginOperation(message, { id, kind, ref, keys, minted } = {}) {
+  beginOperation(message, { groupId, kind, ref, keys, minted } = {}) {
+    if (kind != null && !OPERATION_KINDS.includes(String(kind))) {
+      throw new Error(
+        `Unknown operation kind "${kind}". It is one of: ${OPERATION_KINDS.join(", ")}.`,
+      );
+    }
     const frame = {
       keys: keys || null,
       count: 0,
@@ -3680,7 +3809,7 @@ class PlaidClient {
       return open.id;
     }
     this.operationGroup = {
-      id: id || crypto.randomUUID(),
+      id: groupId ? String(groupId) : crypto.randomUUID(),
       message: message == null ? null : String(message),
       kind: kind == null ? null : String(kind),
       ref: ref == null ? null : String(ref),
@@ -3754,11 +3883,11 @@ class PlaidClient {
    *
    * @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.
-   * @param {object} [opts] - Optional `{ kind, ref, id, keys }`, as for beginOperation.
+   * @param {object} [opts] - Optional `{ kind, ref, groupId, keys, minted }`, as for beginOperation. `kind` is one of `assistant-plan`, `service-run`, `import`, `bulk-edit`, `guess-adoption`, `repair` or `review`, and any other throws before `fn` runs.
    * @returns {Promise<any>} Whatever `fn` resolves to.
    */
-  async withOperation(message, fn, { kind, ref, id, keys, minted } = {}) {
-    this.beginOperation(message, { kind, ref, id, keys, minted });
+  async withOperation(message, fn, { kind, ref, groupId, keys, minted } = {}) {
+    this.beginOperation(message, { kind, ref, groupId, keys, minted });
     const group = this.operationGroup;
     // The key frame this call opened is ended by this call, whatever else
     // began or ended meanwhile, not by whichever end comes at its depth.
@@ -3854,8 +3983,10 @@ class PlaidClient {
         }
         return res;
       };
-      const response = await retryUnknown(() => retryWhileBusy(attempt), {
+      const onRetry = (info) => this._noteRetry(info);
+      const response = await retryUnknown(() => retryWhileBusy(attempt, { onRetry }), {
         delaysMs: this.retryDelaysMs,
+        onRetry,
       }).catch((error) => {
         error.idempotencyKey = key;
         // 401 means the token is missing, expired or invalid: fire the app's
@@ -3902,6 +4033,28 @@ class PlaidClient {
           }
         }
       }
+      // The batch's own header holds each document's version after the whole
+      // batch, the layer rules' remedies at its end included, which no single
+      // operation's answer does: a split that deletes a relation crossing
+      // the new boundary moves the version once more.
+      const outerVersions = response.headers?.get?.("X-Document-Versions");
+      if (outerVersions) {
+        try {
+          const versionsMap = JSON.parse(outerVersions);
+          if (typeof versionsMap === "object" && versionsMap !== null) {
+            this.documentVersions = mergeVersions(
+              this.documentVersions,
+              versionsMap,
+              replayed,
+            );
+          }
+        } catch (e) {
+          console.warn(
+            "Failed to parse document versions header from batch response:",
+            e,
+          );
+        }
+      }
 
       const out = results.map((result) => ({
         ...result,
@@ -3982,7 +4135,8 @@ class PlaidClient {
    * 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.
+   * "revoked", or "inactive" when its creator can no longer grant what it
+   * grants), 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.
@@ -4176,7 +4330,7 @@ function constraintMethods(client, kind) {
 
 export default PlaidClient;
 export { PlaidClient };
-export { CONSTRAINT_TYPES, valueSetAllows, violationsOf } from "./constraints.js";
+export { valueSetAllows, violationsOf } from "./constraints.js";
 
 // Unicode code-point helpers for text offsets (token begin/end are code-point
 // indices). See ./codepoint.js.
@@ -4185,7 +4339,6 @@ export {
   cpSlice,
   cpSlicer,
   utf16ToCp,
-  cpToUtf16,
   cpIndexOf,
 } from "./codepoint.js";
 export { composeTextEdits, gapsToOps, applyTextOps } from "./textEdits.js";
@@ -4193,7 +4346,6 @@ export {
   PLAID_NAMESPACE,
   ROLE_KEY,
   PRESERVE_ON_SPLIT_KEY,
-  PLAIN_EDITS_KEY,
   SPLIT_ON_SPACE_KEY,
   ROLES,
   readRole,
@@ -4222,11 +4374,7 @@ export { REQUESTED_BY, makeRequester, requesterOf } from "./requester.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";
+export { 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
@@ -4234,7 +4382,6 @@ export {
 export {
   PROV,
   PROV_STATES,
-  PROV_CONFIRMED,
   PROVENANCE_KEYS,
   stampInferred,
   confirmedInferred,
@@ -4244,12 +4391,9 @@ export {
   isMachine,
   isProtected,
   needsReview,
-  verifyOnEdit,
   contributeOnEdit,
   serviceSource,
-  userSource,
   REVIEW_KEY,
-  PROJECT_ROLES,
   readReview,
   projectRole,
   isReviewed,

package/src/metadataOps.js

@@ -80,8 +80,10 @@ const applyOp = (node, path, depth, o) => {
 /**
  * Apply ops to a local copy of an entity's metadata the way the server does,
  * for an optimistic update. Returns a new object and never mutates its input.
- * Throws where the server would refuse (a path through a non-object, or a
- * first key that is blank, over 200 characters or holds a control character).
+ * Throws on part of what the server refuses: an empty path, an op other than
+ * set or delete, a path through a non-object, or a first key that is blank,
+ * over 200 characters or holds a control character. The server's caps on
+ * depth, key count, string length and size are not checked here.
  * @param {Object|null|undefined} metadata
  * @param {Array<{op: string, path: string[], value?: any}>} ops
  * @returns {Object}

package/src/provenance.js

@@ -257,9 +257,6 @@ export const userSource = (userId) => `user:${userId}`;
 /** The config key, under the `plaid` namespace, holding the review lists. */
 export const REVIEW_KEY = 'review';
 
-/** The project roles a review list may name. */
-export const PROJECT_ROLES = Object.freeze(['reader', 'writer', 'maintainer']);
-
 /**
  * The project's review lists, normalized: { users: string[], roles: string[] }.
  * @param {Object|null|undefined} config - a project's `config`

package/src/roles.js

@@ -35,19 +35,10 @@ export const ROLE_KEY = 'role';
 export const PRESERVE_ON_SPLIT_KEY = 'preserveOnSplit';
 
 /**
- * Layer config key (true) asking Plaid to take a text edit plainly on the
- * layer: an edit inside a token, or touching its edge with no whitespace
- * between, grows or shrinks it, a typed space never splits it, a deleted one
- * never joins two, and only a token whose whole text is deleted goes. See the
- * manual's `Changing a text's body`.
- */
-export const PLAIN_EDITS_KEY = 'plainEdits';
-
-/**
- * Layer config key (true), beside PLAIN_EDITS_KEY: a space typed inside a
- * token of the text's words splits it, the token going on the half sharing
- * more letters with it. Declared on a word layer another app shares, it holds
- * for the whole text.
+ * Layer config key (true): a space typed inside a token of the text's words
+ * splits it, the token going on the half sharing more letters with it.
+ * Declared on a word layer another app shares, it holds for the whole text.
+ * See the manual's `Changing a text's body`.
  */
 export const SPLIT_ON_SPACE_KEY = 'splitOnSpace';