@larc-iu/plaid-client 0.2.0-alpha.21 → 0.2.0-alpha.23

package/README.md

@@ -0,0 +1,35 @@
+# @larc-iu/plaid-client
+
+The JavaScript client for the [Plaid](https://larc-iu.github.io/plaid/) annotation API.
+It has no dependencies and runs in browsers and in Node.
+
+## From npm
+
+```sh
+npm install @larc-iu/plaid-client@alpha
+```
+
+```js
+import { PlaidClient } from "@larc-iu/plaid-client";
+
+const client = await PlaidClient.login("http://localhost:8080", "user@example.com", "password");
+console.log(await client.projects.list());
+```
+
+## From a Plaid server
+
+Every Plaid server serves the client that matches its own version at `/client/plaid-client.js`, with its type declarations at `/client/plaid-client.d.ts`.
+A page served by Plaid, for example from the folder set as `static_resources_path` in its `config.toml`, can import it without bundling a copy:
+
+```html
+<script type="module">
+  import { PlaidClient } from "/client/plaid-client.js";
+  const client = await PlaidClient.login(location.origin, "user@example.com", "password");
+  console.log(await client.projects.list());
+</script>
+```
+
+## Documentation
+
+- [Manual](https://larc-iu.github.io/plaid/manual.html), which covers the API and its concepts.
+- [API reference](https://larc-iu.github.io/plaid/api-js.html) for this client.

package/index.d.ts

@@ -422,6 +422,8 @@ interface UsersBundle {
 interface UserDataEntry {
   key: string;
   updatedAt: string;
+  /** Raised by one on every write of the entry. A new entry is 1. */
+  version: number;
   value?: any;
 }
 
@@ -446,11 +448,18 @@ interface UserDataBundle {
     opts?: UserDataOptions & { pageSize?: number },
   ): AsyncGenerator<UserDataEntry[]>;
   get(userId: string, key: string): Promise<UserDataEntry & { value: any }>;
+  /**
+   * `version`: write only when the entry is still at this version (0: only
+   * when there is none). Refused with 409, `error: "version-mismatch"` and the
+   * stored `version` and `updatedAt` on the error's `responseData`, when
+   * another write landed since.
+   */
   put(
     userId: string,
     key: string,
     value: any,
-  ): Promise<{ key: string; updatedAt: string }>;
+    opts?: { version?: number },
+  ): Promise<{ key: string; updatedAt: string; version: number }>;
   delete(userId: string, key: string): Promise<any>;
 }
 
@@ -923,6 +932,10 @@ interface AuditPageOptions {
   order?: "asc" | "desc";
   limit?: number;
   cursor?: string;
+  /** Keep only each entry's oldest N operations in `ops` (1..1000). Every entry has `opCount`. */
+  opsLimit?: number;
+  /** Read only this entry rather than a page. */
+  entryId?: string;
 }
 
 /** One user's activity over a scope and window. */
@@ -1115,7 +1128,14 @@ interface DocumentsBundle {
       onProgress?: (progress: { loaded: number; total: number | null }) => void;
     },
   ): Promise<any>;
-  deleteMedia(documentId: string, auditMessage?: string): Promise<any>;
+  deleteMedia(
+    documentId: string,
+    auditMessage?: string,
+    options?: {
+      /** The recording meant, the `?v=` of the document's `mediaUrl`. A 409 when the stored one is another. */
+      mediaVersion?: string;
+    },
+  ): Promise<any>;
   setMetadata(
     documentId: string,
     body: any,
@@ -1458,7 +1478,7 @@ interface TokensBundle {
     tokenId: string,
     position: number,
     auditMessage?: string,
-    options?: { id?: string },
+    options?: { id?: string; keep?: "left" | "right" },
   ): Promise<any>;
   merge(
     tokenId: string,
@@ -1652,7 +1672,7 @@ export declare class PlaidClient {
   } | null;
   beginOperation(
     message: string,
-    opts?: { id?: string; kind?: OperationKind; ref?: string; keys?: KeySeed; minted?: Set<string> },
+    opts?: { groupId?: string; kind?: OperationKind; ref?: string; keys?: KeySeed; minted?: Set<string> },
   ): string;
   /** A seed for the Idempotency-Keys of an operation that may be run again (see beginOperation's `keys`). */
   keySeed(): KeySeed;
@@ -1660,7 +1680,7 @@ export declare class PlaidClient {
   withOperation<T>(
     message: string,
     fn: (setMessage: (msg: string) => void) => Promise<T> | T,
-    opts?: { kind?: OperationKind; ref?: string; id?: string; keys?: KeySeed; minted?: Set<string> },
+    opts?: { kind?: OperationKind; ref?: string; groupId?: string; keys?: KeySeed; minted?: Set<string> },
   ): Promise<T>;
   operationGroups: OperationGroupsBundle;
 
@@ -1893,6 +1913,8 @@ export interface KeySeed {
 }
 /** A fresh UUIDv7, for the id of something a client creates. */
 export function uuidv7(): string;
+/** A fresh random UUID (version 4), from crypto.getRandomValues, so it works on any page. */
+export function uuidv4(): string;
 /** Whether a write's answer was replayed from its Idempotency-Key's first send (`Idempotent-Replayed: true`), so it wrote nothing new. Marked on an object or list answer as a non-enumerable `replayed: true`. */
 export function wasReplayed(answer: unknown): boolean;
 export function createdId(result: any): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larc-iu/plaid-client",
-  "version": "0.2.0-alpha.21",
+  "version": "0.2.0-alpha.23",
   "description": "JavaScript client for the Plaid annotation API",
   "type": "module",
   "repository": {

package/src/documentLock.js

@@ -1,4 +1,5 @@
 import { isUnknownOutcome, retryUnknown } from "./http.js";
+import { uuidv4 } from "./ids.js";
 
 /**
  * Keeping a document lock alive for as long as a `locked()` block runs.
@@ -216,7 +217,7 @@ export class DocumentLock {
 export const LOCK_ACQUIRE_RETRY_MS = 500;
 
 function mintLockId() {
-  return globalThis.crypto.randomUUID();
+  return uuidv4();
 }
 
 /**

package/src/http.js

@@ -69,6 +69,23 @@ export const DEFAULT_TIMEOUT_MS = 30000;
 // nothing and costs a retry stacked on a write that is still running.
 export const DEFAULT_BATCH_TIMEOUT_MS = 180000;
 
+// A query may run for core's own query limit (30 s, `*query-timeout-ms*` in
+// plaid.sql.query.exec), and core then answers 408. The client waits a little
+// longer than that, so the caller gets core's 408 for a query too broad and
+// not a timeout of its own that reads like a lost connection.
+export const DEFAULT_QUERY_TIMEOUT_MS = 35000;
+
+/**
+ * The timeout for a query: the client's own, raised to
+ * DEFAULT_QUERY_TIMEOUT_MS when it is shorter. A disabled timeout (0, null)
+ * stays disabled.
+ */
+export function queryTimeout(client) {
+  const t = client.timeout;
+  if (!t || t <= 0) return t;
+  return Math.max(t, DEFAULT_QUERY_TIMEOUT_MS);
+}
+
 /**
  * Note how far the server's clock is from this machine's, from a response's
  * Date header, for `client.serverNow()`. A time the server stamped (an audit
@@ -738,6 +755,10 @@ export async function queueRequest(batch, method, path, options = {}) {
  *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
  *   noAuth          - Skip Authorization header
  *   binaryResponse  - Return arrayBuffer instead of JSON/text
+ *   noBusyRetry     - If true, a 503 is not retried. For a query: core
+ *                     answers 503 when its queue of large queries stays full
+ *                     until the query's deadline, and asking again at once
+ *                     only joins the same queue.
  *   timeout         - Per-request timeout in ms overriding client.timeout
  *                     for this call (0/null disables). Used for known-long
  *                     ops like project delete.
@@ -756,6 +777,7 @@ export async function makeRequest(client, method, path, options = {}) {
     timeout,
     onUploadProgress,
     learningOmittedVersion,
+    noBusyRetry,
   } = options;
   if (method !== "GET" && omittedStrictDocument(client)) {
     await learnOmittedVersion(client);
@@ -825,12 +847,13 @@ export async function makeRequest(client, method, path, options = {}) {
 
   try {
     const onRetry = (info) => client._noteRetry?.(info);
+    const busy = noBusyRetry ? { onRetry, retries: 0 } : { onRetry };
     const response = keyed
-      ? await retryUnknown(() => retryWhileBusy(attempt, { onRetry }), {
+      ? await retryUnknown(() => retryWhileBusy(attempt, busy), {
           delaysMs: client.retryDelaysMs,
           onRetry,
         })
-      : await retryWhileBusy(attempt, { onRetry });
+      : await retryWhileBusy(attempt, busy);
     noteServerClock(client, response.headers);
 
     if (!response.ok) {

package/src/ids.js

@@ -52,3 +52,23 @@ export function uuidv7() {
   }
   return s;
 }
+
+/**
+ * A random UUIDv4, for ids that need no order (an operation group, a lock
+ * holder). Built on `crypto.getRandomValues`, since `crypto.randomUUID`
+ * exists only in a secure context and a page served over plain HTTP from
+ * another host than localhost is not one.
+ * @returns {string}
+ */
+export function uuidv4() {
+  const b = new Uint8Array(16);
+  crypto.getRandomValues(b);
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  let s = "";
+  for (let i = 0; i < 16; i++) {
+    s += hex[b[i]];
+    if (i === 3 || i === 5 || i === 7 || i === 9) s += "-";
+  }
+  return s;
+}

package/src/index.js

@@ -20,8 +20,9 @@ import {
   REPLAYED_HEADER,
   DEFAULT_TIMEOUT_MS,
   DEFAULT_BATCH_TIMEOUT_MS,
+  queryTimeout,
 } from "./http.js";
-import { uuidv7 } from "./ids.js";
+import { uuidv4, uuidv7 } from "./ids.js";
 import { constraintsBody } from "./constraints.js";
 import { listAll, listPage, iterPages } from "./pagination.js";
 import { recorderFor } from "./events.js";
@@ -133,6 +134,21 @@ 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.
@@ -528,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,
@@ -545,6 +565,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
             "item-id": itemId,
           },
         }),
@@ -1173,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)}>}
@@ -1194,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>}
        */
@@ -1256,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,
@@ -1271,6 +1297,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
           },
         }),
       /**
@@ -1446,7 +1474,7 @@ class PlaidClient {
           query: { prefix, pattern, "include-values": includeValues },
         }),
       /**
-       * Read one private data entry ({key, updatedAt, value}); 404 if absent.
+       * Read one private data entry ({key, updatedAt, version, value}); 404 if absent.
        * @param {string} userId
        * @param {string} key
        */
@@ -1464,17 +1492,28 @@ class PlaidClient {
        * 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.
+       *
+       * Every write raises the entry's `version` by one, and reads answer it.
+       * With `version`, the write lands only when the entry is still at that
+       * version (0: only when there is no entry), and is otherwise refused with
+       * 409, `error: "version-mismatch"`, and the stored `version` and
+       * `updatedAt` on the error's `responseData`: read it again and make the
+       * change on what is there.
        * @param {string} userId
        * @param {string} key
        * @param {*} value
+       * @param {object} [opts]
+       * @param {number} [opts.version] - The version this write was made from
+       * @returns {Promise<{key: string, updatedAt: string, version: number}>}
        */
-      put: (userId, key, value) =>
+      put: (userId, key, value, { version } = {}) =>
         this._request(
           "PUT",
           `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
           {
             body: value,
             noBatch: true,
+            queryParams: { version },
           },
         ),
       /**
@@ -1839,9 +1878,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,
@@ -1851,6 +1894,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
           },
         }),
       /**
@@ -2112,6 +2157,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, 32-bit float, A-law or mu-law (IMA or
+       * MS ADPCM, GSM, 64-bit float 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
@@ -2131,15 +2181,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.
@@ -2171,7 +2227,10 @@ class PlaidClient {
         }),
       /**
        * Get audit log for a document. Transparently follows pagination cursors
-       * and returns the full flat array.
+       * and returns the full flat array. Each entry, and each of its `ops`,
+       * says what kind of credential made it as `credential`: `login`,
+       * `named-token`, `service` or `delegated` (absent on older operations),
+       * beside `apiToken` (the named token's id and name) when there was one.
        * @param {string} documentId - The document ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -2200,11 +2259,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,
@@ -2215,6 +2278,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
           },
         }),
       /**
@@ -2401,7 +2466,10 @@ class PlaidClient {
         ),
       /**
        * Get audit log for a project. Transparently follows pagination cursors
-       * and returns the full flat array.
+       * and returns the full flat array. Each entry, and each of its `ops`,
+       * says what kind of credential made it as `credential`: `login`,
+       * `named-token`, `service` or `delegated` (absent on older operations),
+       * beside `apiToken` (the named token's id and name) when there was one.
        * @param {string} projectId - The project ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -2430,11 +2498,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,
@@ -2445,6 +2517,8 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
             kinds: kindsParam(kinds),
             order,
+            "ops-limit": opsLimit,
+            "entry-id": entryId,
           },
         }),
       /**
@@ -2762,8 +2836,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
@@ -2966,8 +3043,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.
        */
@@ -2975,11 +3055,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
@@ -3228,9 +3308,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=`
@@ -3691,6 +3778,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
@@ -3706,10 +3794,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,
@@ -3733,7 +3826,7 @@ class PlaidClient {
       return open.id;
     }
     this.operationGroup = {
-      id: id || crypto.randomUUID(),
+      id: groupId ? String(groupId) : uuidv4(),
       message: message == null ? null : String(message),
       kind: kind == null ? null : String(kind),
       ref: ref == null ? null : String(ref),
@@ -3807,11 +3900,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.
@@ -3957,6 +4050,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,
@@ -4314,7 +4429,8 @@ export {
 // result. See ./created.js.
 export { createdId, createdIds } from "./created.js";
 // UUIDv7 ids for what a client creates. See ./ids.js and the manual,
-// "Retrying a write".
-export { uuidv7 } from "./ids.js";
+// "Retrying a write". uuidv4 works where crypto.randomUUID does not (a page
+// served over plain HTTP from any host but localhost).
+export { uuidv4, uuidv7 } from "./ids.js";
 export { wasReplayed } from "./replayed.js";
 export { MAX_BATCH_OPS };

package/src/services.js

@@ -444,7 +444,8 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * @param {string} serviceId - Service ID to request
  * @param {any} data - Request payload
  * @param {number} [timeout=10000] - How long the service may say NOTHING, in ms.
- *   Every event it sends starts the clock again, so this does not cap a long run
+ *   Every event it sends starts the clock again, so this does not cap a long run.
+ *   0, a negative number or null: no limit (wait until `signal` stops it)
  * @param {function} [onProgress] - Called with each progress payload {percent, message}
  * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
  * @param {Object} [opts]
@@ -494,8 +495,15 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
       url: `${client.baseUrl}/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}/requests${qs}`,
       method: 'POST',
       body: JSON.stringify(payload === undefined ? null : transformRequest(payload)),
+      // `notLive` (with `serviceId`) lets an app say it in the service's own
+      // name rather than its id.
       onStatus: (response) =>
-        response.status === 503 ? new Error(`No live service '${serviceId}' on this project`) : null,
+        response.status === 503
+          ? Object.assign(new Error(`No live service '${serviceId}' on this project`), {
+              notLive: true,
+              serviceId,
+            })
+          : null,
       what: 'Service request',
     },
     timeout,
@@ -526,6 +534,7 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
  * @param {string} projectId - Project UUID
  * @param {string} requestId - The request id (from `onAccepted` or your own)
  * @param {number} [timeout=10000] - How long the service may say NOTHING, in ms
+ *   (0, a negative number or null: no limit)
  * @param {function} [onProgress] - Called with each progress payload {percent, message}
  * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
  * @returns {Promise<any>} The service's result
@@ -702,9 +711,11 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
     // deadline on the whole run it killed working transcriptions at the
     // five-minute default and left their writes to land on a document the page
     // had already handed back to the user as editable.
+    // 0, a negative number or null is no limit, as for every other timeout.
     let timer;
     const waitAgain = () => {
       clearTimeout(timer);
+      if (!(timeout > 0)) return;
       timer = setTimeout(
         () =>
           finish(reject, stillRunning(new Error(`${what} timed out after ${timeout}ms of silence`))),

package/src/textEdits.js

@@ -20,6 +20,22 @@
 
 const codePoints = (s) => [...s];
 
+// The last body split into code points, kept: an edit log composes the same
+// long body once for each of its kept states, and splitting it each time made
+// a save on a long text block the page (H31-TEXT-1). Frozen, as every caller
+// shares it.
+let lastBody = null;
+let lastPoints = Object.freeze([]);
+
+/** The code points of `body`, as a frozen array shared with other callers. */
+export function bodyCodePoints(body) {
+  if (body !== lastBody) {
+    lastPoints = Object.freeze(codePoints(body));
+    lastBody = body;
+  }
+  return lastPoints;
+}
+
 function opName(op) {
   return JSON.stringify(op);
 }
@@ -98,7 +114,7 @@ function cutAt(segs, at) {
  * malformed or out-of-bounds op.
  */
 export function composeTextEdits(body, ops) {
-  const old = codePoints(body);
+  const old = bodyCodePoints(body);
   let segs = old.length ? [{ old: true, start: 0, end: old.length }] : [];
   let len = old.length;
   for (const op of ops) {
@@ -128,7 +144,7 @@ export function composeTextEdits(body, ops) {
       close(seg.start);
       kept = seg.end;
     } else {
-      typed.push(...seg.chars);
+      for (const c of seg.chars) typed.push(c);
     }
   }
   close(old.length);