@larc-iu/plaid-client 0.2.0-alpha.12 → 0.2.0-alpha.14

package/src/pagination.js

@@ -10,6 +10,11 @@
  * 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 every request these helpers make carries `bypassBatch`
+ * (see the three classes at the top of http.js). That is what lets them work
+ * while a batch is open on the same client: each page is answered from the
+ * pool, in order, against the state the batch has not committed yet.
  */
 
 // Merge caller query params with paging params, dropping undefined/null so we
@@ -21,16 +26,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,31 +51,15 @@ 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;
   do {
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
+      bypassBatch: true,
     });
-    // 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
@@ -91,6 +87,7 @@ export async function listAll(client, path, { pageSize = 1000, query = {} } = {}
 export async function listPage(client, path, { limit, cursor, query = {} } = {}) {
   return client._request('GET', path, {
     queryParams: buildQueryParams(query, limit, cursor),
+    bypassBatch: true,
   });
 }
 
@@ -98,11 +95,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 +103,14 @@ 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),
+      bypassBatch: true,
     });
-    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 +118,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/services.js

@@ -10,19 +10,96 @@
  */
 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
  * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt}]
  */
 export function discoverServices(client, projectId) {
-  return client._request('GET', `/api/v1/projects/${projectId}/services`);
+  // bypassBatch: the registry is read by whoever asked, not by whatever batch
+  // happens to be open on this shared client. The assistant's availability
+  // probe polls for 49 seconds after a mount and landed inside a Grew rewrite
+  // or an import, where the answer was `{batched: true}`, cached as the
+  // service list, and every later render threw on it until a reload.
+  return client._request('GET', `/api/v1/projects/${projectId}/services`, {
+    bypassBatch: true,
+  });
 }
 
 /**
@@ -39,6 +116,31 @@ export function discardService(client, projectId, serviceId) {
   return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}`);
 }
 
+/**
+ * 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`.
+ *
+ * bypassBatch: these are out-of-band signals to whoever is waiting, not writes
+ * to the project. A service reports them from inside its own
+ * `client.batched()` block, 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, bypassBatch: true },
+  );
+}
+
 /**
  * Register a service and handle incoming work requests.
  *
@@ -86,12 +188,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 +284,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 +304,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 +433,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 +482,30 @@ 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.
+ *
+ * Goes over the wire even while a batch is open on the client. A DELETE, but
+ * not a write: it signals a running service out of band and changes no project
+ * data. The Stop button lives in the app's chrome, on the same client an
+ * import or a bulk edit is batching on, and a stop that waits for that batch to
+ * submit has stopped nothing (and if the batch aborts, it never arrives at
+ * all), while the queued DELETE shifts every result index the batch's caller
+ * reads back.
+ *
+ * @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)}`,
+    { bypassBatch: true },
+  );
 }
 
 /**