@larc-iu/plaid-client 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/index.js

@@ -21,6 +21,8 @@ import {
   discardService,
   serve,
   requestService,
+  attachServiceRequest,
+  cancelServiceRequest,
 } from "./services.js";
 
 // Helper: normalize a document-read `layers` filter to the wire's
@@ -83,6 +85,12 @@ async function anonymousPost(baseUrl, path, body, options = {}) {
   }
 }
 
+/**
+ * The server's cap on operations per batch request (plaid.rest-api.v1.batch).
+ * A batch queued past it is submitted as consecutive requests.
+ */
+const MAX_BATCH_OPS = 1000;
+
 class PlaidClient {
   /**
    * Create a new PlaidClient instance
@@ -1247,13 +1255,13 @@ class PlaidClient {
           auditMessage,
         }),
       /**
-       * Get media file for a document
+       * Get the media file for a document. Media is not versioned, so there is
+       * no as-of form: the route refuses the parameter. Prefer the document's
+       * own `mediaUrl`, which carries the file's version for caching.
        * @param {string} documentId - The document ID
-       * @param {string} [asOf] - Temporal query timestamp
        */
-      getMedia: (documentId, asOf) =>
+      getMedia: (documentId) =>
         this._request("GET", `/api/v1/documents/${documentId}/media`, {
-          queryParams: { "as-of": asOf },
           noBatch: true,
           binaryResponse: true,
         }),
@@ -1261,8 +1269,10 @@ class PlaidClient {
        * Upload a media file for a document. Uses Apache Tika for content validation.
        * @param {string} documentId - The document ID
        * @param {File} file - The file to upload
+       * @param {string} [auditMessage] - Custom audit-log message for this write
+       * @param {object} [options] - `{ onProgress }`: called with `{ loaded, total }` (bytes) as the file goes up. In a browser the upload then travels by XMLHttpRequest, and the request timeout only fires when the upload stalls, not on total time.
        */
-      uploadMedia: (documentId, file, auditMessage) => {
+      uploadMedia: (documentId, file, auditMessage, { onProgress } = {}) => {
         const fd = new FormData();
         fd.append("file", file);
         return this._request("PUT", `/api/v1/documents/${documentId}/media`, {
@@ -1270,6 +1280,7 @@ class PlaidClient {
           body: fd,
           formData: true,
           noBatch: true,
+          onUploadProgress: onProgress,
         });
       },
       /**
@@ -1334,6 +1345,25 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
           },
         }),
+      /**
+       * Restore a document to its state at an earlier time, as one
+       * operation: what was deleted since then comes back under its original
+       * id, what was added since is removed, and what changed is set back,
+       * across every layer. A layer deleted since then, or a vocabulary entry
+       * that no longer exists, is skipped and reported under `skipped`.
+       * Resolves to a summary of the changes. Maintainers only.
+       * @param {string} documentId - The document ID
+       * @param {string} asOf - The moment to go back to (ISO-8601 instant),
+       *   typically a history entry's `endTime`
+       * @param {object} [options] - `{ dryRun }`: with `dryRun` true nothing
+       *   is written and the summary says what would change
+       * @param {string} [auditMessage] - Custom audit message for this operation
+       */
+      restore: (documentId, asOf, { dryRun } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/documents/${documentId}/restore`, {
+          queryParams: { "as-of": asOf, "dry-run": dryRun ? "true" : undefined },
+          auditMessage,
+        }),
       /**
        * Get a document. Set `includeBody` to true to include all data.
        *
@@ -2102,16 +2132,54 @@ class PlaidClient {
 
       /**
        * Request a service to perform work and await its result.
+       *
+       * The request outlives this call: after a timeout, an abort, or a
+       * dropped connection the service goes on, and `attachServiceRequest`
+       * collects the result given the request id, which `opts.onAccepted`
+       * receives as soon as the server has taken the request. Pass
+       * `opts.requestId` (a UUID you mint) to know the id before submitting;
+       * submitting an id that names a request you already made rejoins it
+       * instead of starting another.
        * @param {string} projectId - The UUID of the project
        * @param {string} serviceId - The ID of the service to request
        * @param {any} data - The request data
-       * @param {number} [timeout] - Timeout in milliseconds (default: 10000)
+       * @param {number} [timeout=10000] - Timeout in ms
        * @param {function} [onProgress] - Called with each progress payload {percent, message}
        * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
-       * @returns {Promise<any>} Service response
+       * @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),
+
+      /**
+       * Rejoin a service request made earlier and await its result: the
+       * latest progress is replayed, then the result comes, or at once if the
+       * request already finished. Only the user who submitted it (or an
+       * admin). Rejects with an error whose `status` is 404 when the request
+       * is unknown or expired (a finished request's result is kept for a
+       * while, not forever).
+       * @param {string} projectId - The UUID of the project
+       * @param {string} requestId - The request id
+       * @param {number} [timeout=10000] - Timeout in ms
+       * @param {function} [onProgress] - Called with each progress payload
+       * @param {AbortSignal} [signal] - Abort to stop waiting
+       * @returns {Promise<any>} The service's result
+       */
+      attachServiceRequest: (projectId, requestId, timeout, onProgress, signal) =>
+        attachServiceRequest(this, projectId, requestId, timeout, onProgress, signal),
+
+      /**
+       * Ask the service to stop a request made earlier. The request still
+       * ends with whatever the service then reports, on the stream of whoever
+       * is awaiting it. Rejects with 404 if unknown or expired, 409 once
+       * finished.
+       * @param {string} projectId - The UUID of the project
+       * @param {string} requestId - The request id
+       * @returns {Promise<void>}
        */
-      requestService: (projectId, serviceId, data, timeout, onProgress, signal) =>
-        requestService(this, projectId, serviceId, data, timeout, onProgress, signal),
+      cancelServiceRequest: (projectId, requestId) =>
+        cancelServiceRequest(this, projectId, requestId),
     };
 
     /**
@@ -2181,15 +2249,27 @@ class PlaidClient {
     this.comments = {
       /**
        * Post a comment on an entity. Requires write access to the entity's
-       * project; the author is the authenticated caller. Comments are not
-       * audited and do not bump the document version.
-       * @param {'document'|'text'|'token'|'span'|'relation'} entityType - What kind of thing is being commented on
+       * project, or to the vocabulary for a vocab-item; the author is the
+       * authenticated caller. Comments are not audited and do not bump the
+       * document version.
+       *
+       * A comment outlives its anchor: deleting the entity does not delete
+       * the comment. `anchorLabel` is the caption shown once that happens
+       * ("Gloss of ktab, sentence 4"), so pass what the comment is about.
+       * @param {'document'|'text'|'token'|'span'|'relation'|'vocab-item'} entityType - What kind of thing is being commented on
        * @param {string} entityId - The commented entity's id
        * @param {string} body - The comment text (1..10000 characters)
+       * @param {object} [opts]
+       * @param {string} [opts.anchorLabel] - What the comment is about, in words (at most 200 characters)
        */
-      create: (entityType, entityId, body) =>
+      create: (entityType, entityId, body, { anchorLabel } = {}) =>
         this._request("POST", "/api/v1/comments", {
-          body: bodyOf({ "entity-type": entityType, "entity-id": entityId, body }),
+          body: bodyOf({
+            "entity-type": entityType,
+            "entity-id": entityId,
+            body,
+            "anchor-label": anchorLabel,
+          }),
         }),
       /**
        * Read one comment.
@@ -2290,6 +2370,47 @@ class PlaidClient {
           },
           skipResponseTransform: true,
         }),
+      /**
+       * List the comments on a vocabulary's entries, oldest first. Requires
+       * read access to the vocabulary. Transparently follows pagination
+       * cursors and returns the full flat array.
+       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching - use listInVocabPage() for a single page in a batch.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [filters]
+       * @param {string} [filters.entityId] - One entry's thread
+       */
+      listInVocab: (vocabId, { entityId } = {}) =>
+        listAll(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
+          query: { "entity-id": entityId },
+        }),
+      /**
+       * Fetch a single page of a vocabulary's comments.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {string} [opts.entityId] - One entry's thread
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listInVocabPage: (vocabId, { limit, cursor, entityId } = {}) =>
+        listPage(this, `/api/v1/vocab-layers/${vocabId}/comments`, {
+          limit,
+          cursor,
+          query: { "entity-id": entityId },
+        }),
+      /**
+       * Comment counts per entry of a vocabulary, as an `{entityId: n}` map.
+       * The response is NOT key-transformed: its keys are entry ids.
+       * @param {string} vocabId - The vocab layer to read
+       * @param {object} [filters]
+       * @param {string} [filters.entityId] - One entry only
+       * @returns {Promise<Object<string, number>>}
+       */
+      countsInVocab: (vocabId, { entityId } = {}) =>
+        this._request("GET", `/api/v1/vocab-layers/${vocabId}/comments/counts`, {
+          queryParams: { "entity-id": entityId },
+          skipResponseTransform: true,
+        }),
     };
   }
 
@@ -2432,71 +2553,84 @@ class PlaidClient {
     }
 
     try {
-      let url = `${this.baseUrl}/api/v1/batch`;
-      const body = this.batchOperations.map((op) => ({
+      const url = `${this.baseUrl}/api/v1/batch`;
+      const ops = this.batchOperations.map((op) => ({
         path: op.path,
         method: op.method.toUpperCase(),
         ...(op.body && { body: op.body }),
       }));
+      // The server caps a batch at MAX_BATCH_OPS so one transaction cannot
+      // hold the write lock without bound. A larger batch goes as consecutive
+      // requests, results concatenated in queue order: it could not have been
+      // one transaction anyway, and a repair or bulk edit over a big document
+      // must not fail on its size alone.
+      const results = [];
+      for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
+        results.push(...(await this._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))));
+      }
+      return results;
+    } finally {
+      this.isBatching = false;
+      this.batchOperations = [];
+    }
+  }
 
-      const fetchOptions = {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.token}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify(body),
-      };
+  /** POST one batch request (at most MAX_BATCH_OPS operations); resolves to its transformed results. */
+  async _postBatch(url, body) {
+    const fetchOptions = {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    };
 
-      try {
-        // Retry a 503: the batch is atomic, so a refused one wrote nothing and
-        // repeating it is safe. A fresh timeout signal per attempt — an
-        // AbortSignal.timeout stays aborted once it fires.
-        const response = await retryWhileBusy(async () => {
-          const signal = timeoutSignal(this.batchTimeout);
-          const res = await fetch(
-            url,
-            signal ? { ...fetchOptions, signal } : fetchOptions,
-          );
-          if (!res.ok) {
-            throw makeHttpError(res, await parseErrorBody(res), url, "POST");
-          }
-          return res;
-        });
+    try {
+      // Retry a 503: the batch is atomic, so a refused one wrote nothing and
+      // repeating it is safe. A fresh timeout signal per attempt — an
+      // AbortSignal.timeout stays aborted once it fires.
+      const response = await retryWhileBusy(async () => {
+        const signal = timeoutSignal(this.batchTimeout);
+        const res = await fetch(
+          url,
+          signal ? { ...fetchOptions, signal } : fetchOptions,
+        );
+        if (!res.ok) {
+          throw makeHttpError(res, await parseErrorBody(res), url, "POST");
+        }
+        return res;
+      });
 
-        const results = await response.json();
-
-        // Extract document versions from each batch response
-        for (const result of results) {
-          if (result.headers && result.headers["X-Document-Versions"]) {
-            try {
-              const versionsMap = JSON.parse(
-                result.headers["X-Document-Versions"],
-              );
-              if (typeof versionsMap === "object" && versionsMap !== null) {
-                // Clone once per response, then merge — not once per entry.
-                this.documentVersions = {
-                  ...this.documentVersions,
-                  ...versionsMap,
-                };
-              }
-            } catch (e) {
-              console.warn(
-                "Failed to parse document versions header from batch response:",
-                e,
-              );
+      const results = await response.json();
+
+      // Extract document versions from each batch response
+      for (const result of results) {
+        if (result.headers && result.headers["X-Document-Versions"]) {
+          try {
+            const versionsMap = JSON.parse(
+              result.headers["X-Document-Versions"],
+            );
+            if (typeof versionsMap === "object" && versionsMap !== null) {
+              // Clone once per response, then merge — not once per entry.
+              this.documentVersions = {
+                ...this.documentVersions,
+                ...versionsMap,
+              };
             }
+          } catch (e) {
+            console.warn(
+              "Failed to parse document versions header from batch response:",
+              e,
+            );
           }
         }
-
-        return results.map((result) => transformResponse(result));
-      } catch (error) {
-        if (error.status) throw error;
-        throw makeNetworkError(error, url, "POST");
       }
-    } finally {
-      this.isBatching = false;
-      this.batchOperations = [];
+
+      return results.map((result) => transformResponse(result));
+    } catch (error) {
+      if (error.status) throw error;
+      throw makeNetworkError(error, url, "POST");
     }
   }
 
@@ -2699,19 +2833,33 @@ export {
   buildDefaultValues,
   coerceParamValues,
 } from "./serviceSchema.js";
-// Provenance: the cross-app convention for machine-provided vs human-labeled
-// information (flat prov/provSource/provConfirmed metadata; absence = human),
-// plus the machine-writer contract. See ./provenance.js and the manual,
-// "Provenance".
+// Provenance: the cross-app convention for who made an annotation (flat
+// prov/provSource/provConfirmed metadata; absence = a verifier; 'inferred' =
+// a machine; 'contributed' = a person whose work is reviewed), plus the
+// machine-writer contract. See ./provenance.js and the manual, "Provenance".
 export {
   PROV,
   PROV_STATES,
   PROV_CONFIRMED,
   stampInferred,
   confirmedInferred,
+  stampContributed,
   provState,
+  provOrigin,
   isMachine,
   isProtected,
+  needsReview,
   verifyOnEdit,
+  contributeOnEdit,
+  mergeMetadata,
   serviceSource,
+  userSource,
+  REVIEW_KEY,
+  PROJECT_ROLES,
+  readReview,
+  projectRole,
+  isReviewed,
+  withReviewedUser,
+  writerPolicy,
 } from "./provenance.js";
+export { MAX_BATCH_OPS };