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

package/src/pagination.js

@@ -10,6 +10,10 @@
  * Each helper threads the client through to `client._request`, so auth
  * headers, base URL, and response transforms all apply exactly as for any
  * other request.
+ *
+ * A page is a read, so it goes over the wire even when the helper is handed a
+ * batch (see the note at the top of http.js): each page is answered from the
+ * pool, in order, against the state no batch has committed yet.
  */
 
 // Merge caller query params with paging params, dropping undefined/null so we
@@ -21,16 +25,23 @@ function buildQueryParams(query, limit, cursor) {
   return params;
 }
 
+// Every collection endpoint answers with the envelope. A bare array or any
+// other shape is a broken endpoint, so name it and stop rather than return a
+// silently truncated result.
+function entriesOf(response, path) {
+  if (!response || !Array.isArray(response.entries)) {
+    throw new Error(
+      `GET ${path} did not return a paginated envelope (no 'entries' array)`,
+    );
+  }
+  return response.entries;
+}
+
 /**
  * Fetch every page and return the full flat array of entries, transparently
  * following `nextCursor` until it is null. This is what `.list()` calls so it
  * stays backward compatible with the pre-pagination (bare-array) contract.
  *
- * NOTE: This auto-paginates and therefore CANNOT be used inside a batch — each
- * page's request needs the previous page's `nextCursor`, which doesn't exist
- * until the batch executes. It throws immediately when `client.isBatching` is
- * true. Use `listPage` for a single page inside a batch.
- *
  * @param {object} client - PlaidClient instance
  * @param {string} path - API path, e.g. '/api/v1/projects'
  * @param {object} [opts]
@@ -39,11 +50,6 @@ function buildQueryParams(query, limit, cursor) {
  * @returns {Promise<Array>} The concatenated entries across all pages
  */
 export async function listAll(client, path, { pageSize = 1000, query = {} } = {}) {
-  if (client.isBatching) {
-    throw new Error(
-      `Cannot auto-paginate ${path} inside a batch: list methods follow cursors across multiple requests, which a batch cannot do. Use listPage() for a single page inside a batch, or call list() outside the batch.`,
-    );
-  }
   const all = [];
   let cursor = null;
   let prevCursor;
@@ -51,19 +57,7 @@ export async function listAll(client, path, { pageSize = 1000, query = {} } = {}
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
     });
-    // Compatibility shim: a non-paginated server (or proxy) may return a bare
-    // array. Treat it as a terminal full result with no further paging.
-    if (Array.isArray(response)) {
-      all.push(...response);
-      break;
-    }
-    if (response && Array.isArray(response.entries)) {
-      all.push(...response.entries);
-    } else {
-      throw new Error(
-        "Unexpected list response shape (no 'entries'); server may be incompatible.",
-      );
-    }
+    all.push(...entriesOf(response, path));
     prevCursor = cursor;
     cursor = response.nextCursor;
     // Guard against a buggy server/proxy that returns a constant non-null
@@ -98,11 +92,6 @@ export async function listPage(client, path, { limit, cursor, query = {} } = {})
  * Async generator yielding each page's entries array in turn, following
  * `nextCursor` until it is null.
  *
- * NOTE: This auto-paginates and therefore CANNOT be used inside a batch — each
- * page's request needs the previous page's `nextCursor`, which doesn't exist
- * until the batch executes. It throws on first iteration when
- * `client.isBatching` is true. Use `listPage` for a single page inside a batch.
- *
  * @param {object} client - PlaidClient instance
  * @param {string} path - API path
  * @param {object} [opts]
@@ -111,18 +100,13 @@ export async function listPage(client, path, { limit, cursor, query = {} } = {})
  * @yields {Array} The entries array for each page
  */
 export async function* iterPages(client, path, { pageSize = 1000, query = {} } = {}) {
-  if (client.isBatching) {
-    throw new Error(
-      `Cannot auto-paginate ${path} inside a batch: list methods follow cursors across multiple requests, which a batch cannot do. Use listPage() for a single page inside a batch, or call list() outside the batch.`,
-    );
-  }
   let cursor = null;
   let prevCursor;
   do {
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
     });
-    const entries = (response && Array.isArray(response.entries)) ? response.entries : [];
+    const entries = entriesOf(response, path);
     // Suppress the trailing empty page that the server emits when a collection's
     // size is an exact multiple of the page size (a final full page with a
     // non-null cursor, then an empty page). Still follow the cursor below.
@@ -130,7 +114,7 @@ export async function* iterPages(client, path, { pageSize = 1000, query = {} } =
       yield entries;
     }
     prevCursor = cursor;
-    cursor = response ? response.nextCursor : null;
+    cursor = response.nextCursor;
     // Guard against a buggy server/proxy that returns a constant non-null
     // cursor, which would otherwise loop forever.
     if (cursor !== null && cursor !== undefined && cursor === prevCursor) {

package/src/serviceSchema.js

@@ -22,10 +22,15 @@
  *       { key, label, type, description?, default?, required?,
  *         options?: [{value, label}],   // enum / multiselect
  *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
- *         placeholder?, multiline? }    // string
+ *         placeholder?, multiline?,     // string
+ *         scope? }                      // field: 'Sentence' | 'Word' | 'Morpheme'
  *     ]
  *   }
  *
+ * A `field` parameter names one of the project's annotation fields at its
+ * `scope`. A UI that knows the project offers those fields to choose from; to
+ * everything here, and to a UI that does not, it is a string.
+ *
  * A parameter's `key` is a string VALUE, so it passes over the wire verbatim;
  * the UI sends `{ [param.key]: value }` in the request data. Declare each `key`
  * in your service's own convention (Python: snake_case; JS: camelCase) and read
@@ -50,6 +55,20 @@ export const TASKS = Object.freeze({
   LINK_VOCAB: "link-vocab",
   /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
   ANALYZE: "analyze",
+  /**
+   * Draft a meaning representation graph over the sentences of a document,
+   * for correction by hand. The request names a `scope` ('document' or
+   * 'sentence'), a `sentence` number when the scope is one sentence, and
+   * `overwrite`. See plaid-umr's drafting services.
+   *
+   * Apart from `analyze` on purpose. A task is the CONTRACT a spot offers a
+   * service against, and these two share almost none of it: an analyze
+   * request names the three token layers plus the language, metalanguage and
+   * orthography, and writes morphemes and glosses. Both claimed `analyze` for
+   * a while, so every app offering an analyze spot offered the other app's
+   * services, which could not answer the request they would have been given.
+   */
+  DRAFT_GRAPH: "draft-graph",
   /** Propose a free translation for each sentence. */
   TRANSLATE: "translate",
   /**
@@ -64,6 +83,13 @@ export const TASKS = Object.freeze({
   DETECT_SPEECH: "detect-speech",
   /** A conversational assistant over a project (chat turns; see plaid-agent). */
   ASSIST: "assist",
+  /**
+   * Score one document's annotation against another document's of the same
+   * text (two annotators' copies), writing a report on the scored document's
+   * metadata and never an annotation. The request names the other document
+   * as `against`. See plaid-umr's AnCast service.
+   */
+  COMPARE: "compare",
 });
 
 /**

package/src/services.js

@@ -10,12 +10,82 @@
  */
 import { transformRequest, transformResponse } from './transforms.js';
 
+// An absolute URL anywhere in an error message, with the phrase that introduces
+// it (`... at http://host/api/v1/spans`). Client and transport errors name the
+// endpoint they called, which is the service operator's business and not the
+// requester's.
+const URL_IN_TEXT = /(?:\s+(?:at|for url:?))?\s*\b[a-zA-Z][\w+.-]*:\/\/\S+/g;
+
+/**
+ * What a requester is told when an error carries no message of its own.
+ * Naming the JS class instead would say nothing they can act on.
+ */
+export const UNKNOWN_FAILURE = 'The service could not finish this request.';
+
+const redact = (text, secrets) => {
+  let out = text;
+  for (const secret of secrets || []) {
+    if (secret && String(secret).length >= 8) out = out.split(String(secret)).join('[redacted]');
+  }
+  return out.trim();
+};
+
+/**
+ * One line about a failure that is safe to show the person who asked.
+ *
+ * Strips absolute URLs (so an internal host never reaches a requester's screen)
+ * and any `secrets` given (a model provider's API key can come back inside its
+ * own error text). The whole error still goes to the operator's console: this
+ * is the requester's half only. The Python twin is `requester_message`.
+ *
+ * @param {any} error
+ * @param {string[]} [secrets]
+ * @returns {string}
+ */
+export function requesterMessage(error, secrets = []) {
+  if (error && typeof error.status === 'number') {
+    if (!error.status) return 'The Plaid server could not be reached.';
+    let text = String(error.message || '');
+    if (error.url) text = text.split(` at ${error.url}`).join('').split(error.url).join('');
+    text = text.trim().replace(/[\s,:;]+$/, '');
+    return redact(text, secrets) || `HTTP ${error.status}`;
+  }
+  // An Error is read by its message and nothing else: `String(new TypeError(''))`
+  // is 'TypeError', which names the class to the requester and tells them
+  // nothing they can act on.
+  const raw =
+    error && typeof error === 'object' && 'message' in error
+      ? String(error.message ?? '')
+      : String(error ?? '');
+  const text = raw.replace(URL_IN_TEXT, '').trim().replace(/[\s,:;]+$/, '');
+  return redact(text, secrets) || UNKNOWN_FAILURE;
+}
+
+/**
+ * What the requester is told when a request fails, named by the service.
+ *
+ * Every path that reports a failed request goes through here, so a raw message
+ * cannot reach a requester from one of them. (Python's twin additionally lets a
+ * `ValueError` through unprefixed, as an authored refusal; JS has no
+ * distinguished refusal type, so every failure is named by the service.)
+ *
+ * @param {any} error
+ * @param {string} [serviceName]
+ * @param {string[]} [secrets]
+ * @returns {string}
+ */
+export function serviceErrorMessage(error, serviceName = '', secrets = []) {
+  const text = requesterMessage(error, secrets);
+  return serviceName ? `${serviceName}: ${text}` : text;
+}
+
 /**
  * Discover the services seen on a project — a synchronous GET. Returns every
  * service ever registered on the project: currently connected ones carry
  * `online: true`; previously-seen offline ones carry `online: false` plus a
  * `lastSeenAt` stamp. Callers that need a service they can actually submit
- * work to should filter on `online`.
+ * work to should filter on `online`. Goes over the wire even while a batch is
+ * open on the client.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
@@ -36,7 +106,36 @@ export function discoverServices(client, projectId) {
  * @returns {Promise<void>}
  */
 export function discardService(client, projectId, serviceId) {
-  return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}`);
+  // outOfBand: the registry is not project data (see the note at the top of
+  // http.js).
+  return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}`, {
+    outOfBand: true,
+  });
+}
+
+/**
+ * POST a progress, result or error event for an in-flight request; the server
+ * relays it to the waiting requester. The Python twin is `_report_event`.
+ *
+ * outOfBand: these are signals to whoever is waiting, not writes to the
+ * project (see the note at the top of http.js). A service may report them on
+ * the batch it is filling, where queueing them would hold every one back until
+ * submit, deliver none at all if the batch aborts, and take slots in the
+ * batch's results. The requester would hear nothing and wait out its idle
+ * timeout on work that had already finished.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} requestId - The request id
+ * @param {Object} body - The event payload
+ * @returns {Promise<any>}
+ */
+export function reportRequestEvent(client, projectId, requestId, body) {
+  return client._request(
+    'POST',
+    `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}/events`,
+    { body, outOfBand: true },
+  );
 }
 
 /**
@@ -86,12 +185,10 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
   };
 
   const reportEvent = (requestId, body) =>
-    client
-      ._request('POST', `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}/events`, { body })
-      .catch((error) => {
-        // 404 just means the requester already went away; nothing to do.
-        console.warn('Failed to report request event:', error.message || error);
-      });
+    reportRequestEvent(client, projectId, requestId, body).catch((error) => {
+      // 404 just means the requester already went away; nothing to do.
+      console.warn('Failed to report request event:', error.message || error);
+    });
 
   const serviceRegistration = {
     stop: () => {
@@ -184,9 +281,17 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
           data: { ...(data || {}), stopped: true },
         });
       },
+      // Every failure a requester is shown goes out through here, whoever
+      // reports it, so the scrub lives here rather than only in `settle`: a
+      // service that catches its own error and calls `helper.error(err)`
+      // would otherwise put the endpoint the client called on the requester's
+      // screen. Already-sanitized text passes through unchanged.
       error: (error) => {
         finished();
-        return reportEvent(requestId, { status: 'error', data: { error: error?.message || error } });
+        return reportEvent(requestId, {
+          status: 'error',
+          data: { error: requesterMessage(error) },
+        });
       },
     };
 
@@ -196,7 +301,11 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
       if (error instanceof ServiceCancelled || error?.name === 'ServiceCancelled') {
         responseHelper.stopped();
       } else {
-        responseHelper.error(error?.message || error);
+        // What reaches the requester is the sanitized half: the raw message
+        // names the endpoint the client called, which is the operator's
+        // business. The console keeps the whole error.
+        console.error(`Service ${serviceId} failed request ${requestId}:`, error);
+        responseHelper.error(serviceErrorMessage(error, serviceName));
       }
     };
     try {
@@ -321,16 +430,6 @@ export function attachServiceRequest(client, projectId, requestId, timeout = 100
   );
 }
 
-/**
- * Ask the service to stop a request made earlier (by this user). 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 {Object} client - PlaidClient instance
- * @param {string} projectId - Project UUID
- * @param {string} requestId - The request id
- * @returns {Promise<void>}
- */
 /**
  * Thrown inside a handler when the requester has asked it to stop.
  *
@@ -380,8 +479,25 @@ export function createCancelScope(isCancelled) {
   };
 }
 
+/**
+ * Ask the service to stop a request made earlier (by this user). 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.
+ *
+ * outOfBand: a DELETE, but not a write. It signals a running service and
+ * changes no project data (see the note at the top of http.js).
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} requestId - The request id
+ * @returns {Promise<void>}
+ */
 export function cancelServiceRequest(client, projectId, requestId) {
-  return client._request('DELETE', `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}`);
+  return client._request(
+    'DELETE',
+    `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}`,
+    { outOfBand: true },
+  );
 }
 
 /**