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

package/src/index.js

@@ -85,6 +85,31 @@ async function anonymousPost(baseUrl, path, body, options = {}) {
   }
 }
 
+/**
+ * GET a path with no authentication, for the two endpoints a client may need
+ * before it has a session: /health and /api/v1/info.
+ */
+async function anonymousGet(baseUrl, path, options = {}) {
+  const base = baseUrl.replace(/\/$/, "");
+  const url = `${base}${path}`;
+  try {
+    const fetchOptions = { method: "GET" };
+    const signal = timeoutSignal(
+      options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
+    );
+    if (signal) fetchOptions.signal = signal;
+
+    const response = await fetch(url, fetchOptions);
+    if (!response.ok) {
+      throw makeHttpError(response, await parseErrorBody(response), url, "GET");
+    }
+    return transformResponse(await response.json());
+  } catch (error) {
+    if (error.status) throw error;
+    throw makeNetworkError(error, url, "GET");
+  }
+}
+
 /**
  * The server's cap on operations per batch request (plaid.rest-api.v1.batch).
  * A batch queued past it is submitted as consecutive requests.
@@ -450,6 +475,16 @@ class PlaidClient {
           auditMessage,
           body,
         }),
+      /**
+       * 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.
+       * @returns {Promise<{count: number}>} How many relations were updated.
+       */
+      bulkUpdate: (body, auditMessage) =>
+        this._request("PATCH", "/api/v1/relations/bulk", {
+          auditMessage,
+          body,
+        }),
     };
 
     this.spanLayers = {
@@ -600,6 +635,16 @@ class PlaidClient {
        */
       bulkDelete: (body, auditMessage) =>
         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.
+       * @returns {Promise<{count: number}>} How many spans were updated.
+       */
+      bulkUpdate: (body, auditMessage) =>
+        this._request("PATCH", "/api/v1/spans/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * Replace all metadata for a span.
        * @param {string} spanId - The span ID
@@ -633,6 +678,42 @@ class PlaidClient {
         }),
     };
 
+    // Server-level facts. Fetched at most once: the limits cannot change while
+    // the server is up, and a caller asking "will this file be accepted" should
+    // not pay a round trip to find out.
+    let infoPromise = null;
+    this.server = {
+      /**
+       * This server's version and the limits it enforces, e.g.
+       * `{ limits: { mediaFileBytes, jsonBodyBytes, batchOperations, … } }`.
+       * Sizes are in bytes. Unauthenticated.
+       */
+      info: () => {
+        if (!infoPromise) {
+          // bypassBatch: a read belongs to whoever asked for it, not to
+          // whatever batch happens to be open on this shared client.
+          infoPromise = this._request("GET", "/api/v1/info", {
+            bypassBatch: true,
+          }).catch((err) => {
+            // A failure must not be cached: a client that starts before the
+            // server is up would never see the limits at all.
+            infoPromise = null;
+            throw err;
+          });
+        }
+        return infoPromise;
+      },
+      /** Just the limits, which is what a caller almost always wants. */
+      limits: async () => (await this.server.info()).limits,
+      /**
+       * Liveness, version and database size. Unauthenticated, and served
+       * outside the REST router at /health, so it answers even while the API
+       * is refusing requests. Never cached — the point is that it is current.
+       * @returns {Promise<{ok: boolean, version: string, uptimeMs: number, audit: object}>}
+       */
+      health: () => PlaidClient.health(this.baseUrl, { timeout: this.timeout }),
+    };
+
     this.batch = {
       /**
        * Execute multiple API operations atomically. If any operation fails, all
@@ -812,6 +893,31 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
           },
         }),
+      /**
+       * One page of the same log, newest-first with `order: "desc"`. Use this
+       * rather than audit() wherever the caller wants the recent end of a log
+       * that may be long: audit() walks every page before it resolves.
+       * @param {object} [opts]
+       * @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
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        userId,
+        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/users/${userId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+            order,
+          },
+        }),
       /**
        * Get a user by ID
        * @param {string} id - The resource ID
@@ -924,14 +1030,21 @@ class PlaidClient {
       /**
        * List a user's private data entries ({key, updatedAt}, plus value when
        * includeValues). Owner or admin only.
+       *
+       * 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.
        * @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
        */
-      list: (userId, { prefix, includeValues } = {}) =>
+      list: (userId, { prefix, pattern, includeValues } = {}) =>
         this._request("GET", `/api/v1/users/${userId}/data`, {
-          queryParams: { prefix, "include-values": includeValues },
+          queryParams: { prefix, pattern, "include-values": includeValues },
         }),
       /**
        * Read one private data entry ({key, updatedAt, value}); 404 if absent.
@@ -1044,37 +1157,40 @@ class PlaidClient {
        * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @param {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)
        */
-      list: ({ projectId } = {}) =>
+      list: ({ projectId, all } = {}) =>
         listAll(this, "/api/v1/invites", {
-          query: { "project-id": projectId },
+          query: { "project-id": projectId, all },
         }),
       /**
        * Fetch a single page of invites.
        * @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)
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ projectId, limit, cursor } = {}) =>
+      listPage: ({ projectId, all, limit, cursor } = {}) =>
         listPage(this, "/api/v1/invites", {
           limit,
           cursor,
-          query: { "project-id": projectId },
+          query: { "project-id": projectId, all },
         }),
       /**
        * Async-iterate invites page by page; yields each page's entries array.
        * @param {object} [opts]
        * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {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, pageSize } = {}) =>
+      iterPages: ({ projectId, all, pageSize } = {}) =>
         iterPages(this, "/api/v1/invites", {
           pageSize,
-          query: { "project-id": projectId },
+          query: { "project-id": projectId, all },
         }),
       /**
        * Mint an invite. The returned `code` is shown ONLY here — it is never
@@ -1134,6 +1250,206 @@ class PlaidClient {
         this._request("DELETE", `/api/v1/invites/${id}`, { auditMessage }),
     };
 
+    this.admin = {
+      /**
+       * Everything about the server in one read: version and JVM uptime,
+       * database size and per-table row counts, media directory usage, backup
+       * configuration and the backups on disk, and the settings an operator
+       * gets asked to confirm. Carries no secrets. Runs a count per table and
+       * 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"),
+      /**
+       * 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}>}
+       */
+      backup: () => this._request("POST", "/api/v1/admin/backup"),
+      /**
+       * 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"),
+      /**
+       * 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}`),
+      /**
+       * 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"),
+      /**
+       * Forget recorded rate-limit failures. With `ip`, clears that address,
+       * narrowed to one account with `userId`. With neither, clears every
+       * bucket. Only ever unblocks. Admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.ip] - Clear only this address
+       * @param {string} [opts.userId] - Narrow to one account on that address
+       */
+      clearRateLimits: ({ ip, userId } = {}) =>
+        this._request("DELETE", "/api/v1/admin/rate-limits", {
+          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.
+       * @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", {
+          queryParams: { lines },
+        }),
+      /**
+       * Private user-data entries across every account, each carrying its
+       * `userId`. `/users/:userId/data` has always been owner-or-admin; this
+       * is the same reach across accounts at once. Transparently follows
+       * pagination cursors and returns the full flat array. Admin only.
+       *
+       * 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:*`. 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
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @returns {Promise<Array<{userId: string, key: string, updatedAt: string, value?: *}>>}
+       */
+      userData: ({ prefix, pattern, includeValues } = {}) =>
+        listAll(this, "/api/v1/admin/user-data", {
+          query: {
+            prefix,
+            pattern,
+            "include-values": includeValues,
+          },
+        }),
+      /**
+       * One page of private user-data entries across accounts, ordered by
+       * (user, key). Admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this
+       * @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)}>}
+       */
+      userDataPage: ({ prefix, pattern, includeValues, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/admin/user-data", {
+          limit,
+          cursor,
+          query: {
+            prefix,
+            pattern,
+            "include-values": includeValues,
+          },
+        }),
+    };
+
+    this.audit = {
+      /**
+       * The audit log across every project, oldest first. Same fold, window
+       * 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
+       * @param {string[]|string} [opts.opTypes] - Only these op types (e.g.
+       *   `['span-layer/create']`). An entry appears when one of its operations
+       *   matches, carrying only the ones that did.
+       */
+      list: ({ startTime, endTime, opTypes } = {}) =>
+        listAll(this, "/api/v1/audit", {
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+          },
+        }),
+      /**
+       * Fetch a single page of the instance-wide audit log. Admin only.
+       * @param {object} [opts]
+       * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first, which
+       *   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
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: ({ startTime, endTime, opTypes, order, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/audit", {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            order,
+          },
+        }),
+      /**
+       * 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 } = {}) =>
+        iterPages(this, "/api/v1/audit", {
+          pageSize,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+          },
+        }),
+      /**
+       * Per-user activity counts. `changes` is the number of logical actions,
+       * folded the way the audit feed folds them, so one "Confirm word
+       * analysis" counts once however many rows it wrote; `operations` is the
+       * unfolded row count. Only users who did something appear — subtract
+       * from the roster you already hold to find the ones who did not.
+       *
+       * With `projectId`, scoped to that project and open to its maintainers.
+       * Without one, instance-wide and admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - Scope to one project
+       * @param {string} [opts.startTime] - Only count at or after this instant
+       * @param {string} [opts.endTime] - Only count at or before this instant
+       * @param {boolean} [opts.daily] - Also return `byDay`, a list of
+       *   `{date, changes}` per user, oldest first, at the cost of a second
+       *   grouped scan
+       * @returns {Promise<Array<{user: object, operations: number, changes: number, documents: number, firstTs: string, lastTs: string, byDay?: object}>>}
+       */
+      tally: async ({ projectId, startTime, endTime, daily } = {}) => {
+        const path = projectId
+          ? `/api/v1/projects/${projectId}/audit/tally`
+          : "/api/v1/audit/tally";
+        const result = await this._request("GET", path, {
+          queryParams: {
+            "start-time": startTime,
+            "end-time": endTime,
+            daily,
+          },
+        });
+        return result.entries;
+      },
+    };
+
     this.tokenLayers = {
       /**
        * Shift a token layer's display order.
@@ -1345,6 +1661,31 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
           },
         }),
+      /**
+       * One page of the same log, newest-first with `order: "desc"`. Use this
+       * rather than audit() wherever the caller wants the recent end of a log
+       * that may be long: audit() walks every page before it resolves.
+       * @param {object} [opts]
+       * @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
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        documentId,
+        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/documents/${documentId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+            order,
+          },
+        }),
       /**
        * Restore a document to its state at an earlier time, as one
        * operation: what was deleted since then comes back under its original
@@ -1361,7 +1702,10 @@ class PlaidClient {
        */
       restore: (documentId, asOf, { dryRun } = {}, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/restore`, {
-          queryParams: { "as-of": asOf, "dry-run": dryRun ? "true" : undefined },
+          queryParams: {
+            "as-of": asOf,
+            "dry-run": dryRun ? "true" : undefined,
+          },
           auditMessage,
         }),
       /**
@@ -1416,6 +1760,25 @@ class PlaidClient {
           auditMessage,
           body: bodyOf({ "project-id": projectId, name, metadata }),
         }),
+      /**
+       * Copy a document and everything in it into a new document of the same
+       * project, as one operation. The copy shares the source's layers and
+       * the vocabulary entries its links name, and holds the source's texts,
+       * tokens, spans, relations and vocab links under fresh ids, with their
+       * metadata. Comments do not travel. The media file does, unless
+       * `includeMedia` is false. Resolves to `{ id }`, plus `mediaError` when
+       * the source had media the copy could not take with it.
+       * @param {string} documentId - The document to copy
+       * @param {string} name - The new document's name
+       * @param {object} [options] - `{ includeMedia }`: false leaves the media
+       *   file behind
+       * @param {string} [auditMessage] - Custom audit message for this operation
+       */
+      copy: (documentId, name, { includeMedia } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/documents/${documentId}/copy`, {
+          auditMessage,
+          body: bodyOf({ name, "include-media": includeMedia }),
+        }),
     };
 
     this.projects = {
@@ -1522,6 +1885,31 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
           },
         }),
+      /**
+       * One page of the same log, newest-first with `order: "desc"`. Use this
+       * rather than audit() wherever the caller wants the recent end of a log
+       * that may be long: audit() walks every page before it resolves.
+       * @param {object} [opts]
+       * @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
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        projectId,
+        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/projects/${projectId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+            order,
+          },
+        }),
       /**
        * When the calling user last wrote to each document in a project, as a
        * `{documentId: timestamp}` map. Documents they have never written to
@@ -2009,6 +2397,16 @@ class PlaidClient {
        */
       bulkDelete: (body, auditMessage) =>
         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.
+       * @returns {Promise<{count: number}>} How many tokens were updated.
+       */
+      bulkUpdate: (body, auditMessage) =>
+        this._request("PATCH", "/api/v1/tokens/bulk", {
+          auditMessage,
+          body,
+        }),
       /**
        * Split a token at a Unicode code-point offset. The original token becomes the
        * left half (keeps its ID, spans, vocab-links); the new right token's ID is returned.
@@ -2163,8 +2561,25 @@ class PlaidClient {
        * @param {Object} [opts] - {requestId, onAccepted}
        * @returns {Promise<any>} The service's result
        */
-      requestService: (projectId, serviceId, data, timeout, onProgress, signal, opts) =>
-        requestService(this, projectId, serviceId, data, timeout, onProgress, signal, opts),
+      requestService: (
+        projectId,
+        serviceId,
+        data,
+        timeout,
+        onProgress,
+        signal,
+        opts,
+      ) =>
+        requestService(
+          this,
+          projectId,
+          serviceId,
+          data,
+          timeout,
+          onProgress,
+          signal,
+          opts,
+        ),
 
       /**
        * Rejoin a service request made earlier and await its result: the
@@ -2180,8 +2595,21 @@ class PlaidClient {
        * @param {AbortSignal} [signal] - Abort to stop waiting
        * @returns {Promise<any>} The service's result
        */
-      attachServiceRequest: (projectId, requestId, timeout, onProgress, signal) =>
-        attachServiceRequest(this, projectId, requestId, timeout, onProgress, signal),
+      attachServiceRequest: (
+        projectId,
+        requestId,
+        timeout,
+        onProgress,
+        signal,
+      ) =>
+        attachServiceRequest(
+          this,
+          projectId,
+          requestId,
+          timeout,
+          onProgress,
+          signal,
+        ),
 
       /**
        * Ask the service to stop a request made earlier. The request still
@@ -2238,7 +2666,11 @@ class PlaidClient {
     // and the server ran the query against the batch's tx Connection, which
     // 500s and rolls back every write in that batch.
     this.query = (body, auditMessage) =>
-      this._request("POST", "/api/v1/query", { auditMessage, body, bypassBatch: true });
+      this._request("POST", "/api/v1/query", {
+        auditMessage,
+        body,
+        bypassBatch: true,
+      });
 
     // Logical-operation groups (audit-log grouping). There is no create: a
     // group row is made lazily by the first write carrying `?group-id=`
@@ -2333,7 +2765,10 @@ class PlaidClient {
        * @param {string} [opts.entityId] - With entityType, one entity's thread
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: (projectId, { limit, cursor, documentId, entityType, entityId } = {}) =>
+      listPage: (
+        projectId,
+        { limit, cursor, documentId, entityType, entityId } = {},
+      ) =>
         listPage(this, `/api/v1/projects/${projectId}/comments`, {
           limit,
           cursor,
@@ -2354,7 +2789,10 @@ class PlaidClient {
        * @param {string} [opts.entityId] - With entityType, one entity's thread
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: (projectId, { pageSize, documentId, entityType, entityId } = {}) =>
+      iterPages: (
+        projectId,
+        { pageSize, documentId, entityType, entityId } = {},
+      ) =>
         iterPages(this, `/api/v1/projects/${projectId}/comments`, {
           pageSize,
           query: {
@@ -2421,10 +2859,14 @@ class PlaidClient {
        * @returns {Promise<Object<string, number>>}
        */
       countsInVocab: (vocabId, { entityId } = {}) =>
-        this._request("GET", `/api/v1/vocab-layers/${vocabId}/comments/counts`, {
-          queryParams: { "entity-id": entityId },
-          skipResponseTransform: true,
-        }),
+        this._request(
+          "GET",
+          `/api/v1/vocab-layers/${vocabId}/comments/counts`,
+          {
+            queryParams: { "entity-id": entityId },
+            skipResponseTransform: true,
+          },
+        ),
     };
   }
 
@@ -2580,7 +3022,9 @@ class PlaidClient {
       // must not fail on its size alone.
       const results = [];
       for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
-        results.push(...(await this._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))));
+        results.push(
+          ...(await this._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))),
+        );
       }
       return results;
     } finally {
@@ -2703,6 +3147,27 @@ class PlaidClient {
    * @param {object} [options] - Client options forwarded to the constructor (e.g. { timeout })
    * @returns {Promise<PlaidClient>} - Authenticated client instance
    */
+  /**
+   * Liveness, version and database size, with NO authentication and no client
+   * instance — for a launcher or status page checking whether a server is up
+   * before anyone logs in.
+   * @param {string} baseUrl - The API base URL
+   * @param {object} [options]
+   */
+  static async health(baseUrl, options = {}) {
+    return anonymousGet(baseUrl, "/health", options);
+  }
+
+  /**
+   * The limits this server enforces, with NO authentication and no client
+   * instance. See the instance method for the shape.
+   * @param {string} baseUrl - The API base URL
+   * @param {object} [options]
+   */
+  static async info(baseUrl, options = {}) {
+    return anonymousGet(baseUrl, "/api/v1/info", options);
+  }
+
   /**
    * Build the link to hand someone for an invite code. The server never sees
    * an app URL, so the app that minted the invite is the one that names it.
@@ -2730,12 +3195,7 @@ class PlaidClient {
    * @returns {Promise<{kind: string, status: string, expiresAt: string, projectName?: string, projectRole?: string, email?: string, grantAdmin: boolean}>}
    */
   static async lookupInvite(baseUrl, code, options = {}) {
-    return anonymousPost(
-      baseUrl,
-      "/api/v1/invite-codes/lookup",
-      { code },
-      options,
-    );
+    return anonymousPost(baseUrl, "/api/v1/invites/lookup", { code }, options);
   }
 
   /**
@@ -2766,7 +3226,7 @@ class PlaidClient {
   ) {
     const data = await anonymousPost(
       baseUrl,
-      "/api/v1/invite-codes/redeem",
+      "/api/v1/invites/redeem",
       bodyOf({ code, email, password, "display-name": displayName }),
       options,
     );
@@ -2831,6 +3291,7 @@ export {
 export {
   PLAID_NAMESPACE,
   ROLE_KEY,
+  PRESERVE_ON_SPLIT_KEY,
   ROLES,
   readRole,
   findByRole,
@@ -2847,6 +3308,11 @@ export {
   buildDefaultValues,
   coerceParamValues,
 } from "./serviceSchema.js";
+// Cooperative cancellation for a service AUTHORED in JS: `progress()` is a
+// checkpoint that throws ServiceCancelled once the requester stops the
+// request, and `critical()` holds that off around writes. See ./services.js
+// and the manual, "Stopping a request".
+export { ServiceCancelled, createCancelScope } from "./services.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
@@ -2855,6 +3321,7 @@ export {
   PROV,
   PROV_STATES,
   PROV_CONFIRMED,
+  PROVENANCE_KEYS,
   stampInferred,
   confirmedInferred,
   stampContributed,