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

package/src/metadataOps.js

@@ -0,0 +1,117 @@
+/**
+ * Metadata ops: the body of every metadata PATCH, and the `metadata` of a
+ * bulk update entry. An op is `{op: 'set', path, value}` or
+ * `{op: 'delete', path}`, where `path` is a non-empty array of keys into the
+ * nested metadata, the first a top-level key. See the manual, "Metadata".
+ */
+
+import { PLAID_NAMESPACE } from './roles.js';
+import { PROVENANCE_KEYS } from './provenance.js';
+
+const RESERVED_KEYS = new Set([PLAID_NAMESPACE, ...PROVENANCE_KEYS]);
+
+/**
+ * True for a top-level metadata key Plaid keeps for itself: the shared `plaid`
+ * namespace (settings every app reads, such as the text direction) and the
+ * provenance keys. Neither is ever a user's metadata field, so an app neither
+ * lists it as one nor writes a field's value to it.
+ * @param {string} key
+ * @returns {boolean}
+ */
+export const isReservedMetadataKey = (key) => RESERVED_KEYS.has(key);
+
+// The longest top-level key the server takes, in UTF-16 code units (Java's
+// String length, which is what it counts).
+const MAX_KEY_LENGTH = 200;
+
+// Java's Character.isWhitespace, which the server's blank check uses: the
+// Unicode space separators except the three no-break spaces, and the ASCII
+// whitespace controls.
+const isJavaWhitespace = (c) =>
+  (/[\p{Zs}\p{Zl}\p{Zp}]/u.test(c) && c !== '\u00A0' && c !== '\u2007' && c !== '\u202F') ||
+  /[\t\n\u000B\f\r\u001C-\u001F]/.test(c);
+
+/**
+ * True when the server accepts `k` as a top-level metadata key: not blank,
+ * at most 200 UTF-16 code units, and no ASCII control character.
+ * @param {string} k
+ * @returns {boolean}
+ */
+const validMetadataKey = (k) =>
+  typeof k === 'string' &&
+  k.length <= MAX_KEY_LENGTH &&
+  !/[\u0000-\u001F\u007F]/.test(k) &&
+  ![...k].every(isJavaWhitespace);
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The ops that set each top-level key of `fragment`, deleting a key whose
+ * value is null. This is how a provenance fragment (verifyOnEdit,
+ * contributeOnEdit, ...) is sent as a patch.
+ * @param {Object|null|undefined} fragment
+ * @returns {Array<{op: string, path: string[], value?: any}>}
+ */
+export const metadataOps = (fragment) =>
+  Object.entries(fragment || {}).map(([k, v]) =>
+    v === null ? { op: 'delete', path: [k] } : { op: 'set', path: [k], value: v },
+  );
+
+const applyOp = (node, path, depth, o) => {
+  const [k, ...more] = path.slice(depth);
+  if (more.length === 0) {
+    const out = { ...node };
+    if (o.op === 'set') out[k] = o.value;
+    else delete out[k];
+    return out;
+  }
+  const child = Object.prototype.hasOwnProperty.call(node, k) ? node[k] : undefined;
+  if (child === undefined) {
+    return o.op === 'set' ? { ...node, [k]: applyOp({}, path, depth + 1, o) } : node;
+  }
+  if (!isObject(child)) {
+    throw new Error(
+      `Metadata path ${JSON.stringify(path.slice(0, depth + 1))} holds a value that is not an object`,
+    );
+  }
+  return { ...node, [k]: applyOp(child, path, depth + 1, o) };
+};
+
+/**
+ * Apply ops to a local copy of an entity's metadata the way the server does,
+ * for an optimistic update. Returns a new object and never mutates its input.
+ * Throws where the server would refuse (a path through a non-object, or a
+ * first key that is blank, over 200 characters or holds a control character).
+ * @param {Object|null|undefined} metadata
+ * @param {Array<{op: string, path: string[], value?: any}>} ops
+ * @returns {Object}
+ */
+export const applyMetadataOps = (metadata, ops) =>
+  (ops || []).reduce((m, o) => {
+    if (!Array.isArray(o.path) || o.path.length === 0) {
+      throw new Error('A metadata op needs a non-empty path');
+    }
+    if (!validMetadataKey(o.path[0])) {
+      throw new Error('Invalid metadata key');
+    }
+    if (o.op !== 'set' && o.op !== 'delete') {
+      throw new Error(`Unknown metadata op '${o.op}': expected set or delete`);
+    }
+    if (o.op === 'set' && !('value' in o)) {
+      throw new Error('A set op needs a value');
+    }
+    return applyOp(m, o.path, 0, o);
+  }, { ...(metadata || {}) });
+
+/**
+ * Merge a top-level fragment into a local copy, a null value deleting the
+ * key: applyMetadataOps over metadataOps(fragment), so the same result as
+ * sending those ops, refused where the server would refuse them. How an app
+ * mirrors a provenance stamp (verifyOnEdit, contributeOnEdit, ...) on the row
+ * it shows. Returns a new object.
+ * @param {Object|null|undefined} metadata
+ * @param {Object|null|undefined} fragment
+ * @returns {Object}
+ */
+export const mergeMetadata = (metadata, fragment) =>
+  applyMetadataOps(metadata, metadataOps(fragment));

package/src/provenance.js

@@ -78,7 +78,11 @@
  *   - valueProbs / formProbs: a top-k {label: probability} map over the
  *     alternatives the producer considered, the chosen label included
  *     (provProb, when given, is that label's entry duplicated flat).
- *   - model, and anything else (language, adapter, raw scores).
+ *   - model: what made the prediction (a model name, or a tool and its
+ *     release such as 'stanza==1.11.0'), and version: which version of the
+ *     writer ran ('<release>+<8 hex>', see the manual, "Provenance"). Every
+ *     machine writer records both, one of rules alone only version.
+ *   - anything else (language, adapter, raw scores).
  */
 
 /** The flat metadata keys of the provenance convention. */
@@ -228,8 +232,8 @@ export const verifyOnEdit = (metadata) => (needsReview(metadata) ? PROV_CONFIRME
 /**
  * The metadata fragment a CONTRIBUTOR's edit of this entity should merge in
  * (write-contract rule 3): the contributed stamp, plus provConfirmed: null
- * so an earlier confirmation is dropped (a patch deletes null-valued keys;
- * see mergeMetadata for a full replace). Prediction extras a machine
+ * so an earlier confirmation is dropped (send it with metadataOps, which
+ * turns a null into a delete, or apply it locally with mergeMetadata). Prediction extras a machine
  * recorded stay, as history.
  * @param {Object|null|undefined} metadata - unused today; the fragment is
  *   the same whatever the entity was, and the parameter keeps the shape of
@@ -242,20 +246,6 @@ export const contributeOnEdit = (metadata, userId) => ({
   [PROV.confirmedKey]: null,
 });
 
-/**
- * Merge a metadata fragment the way the server's PATCH does — a null value
- * deletes the key — for callers that keep a local copy or send a full
- * replacement (setMetadata). Returns a new object.
- */
-export const mergeMetadata = (metadata, fragment) => {
-  const out = { ...(metadata || {}) };
-  for (const [k, v] of Object.entries(fragment || {})) {
-    if (v === null) delete out[k];
-    else out[k] = v;
-  }
-  return out;
-};
-
 /** Canonical provSource for a service: 'service:<serviceId>'. */
 export const serviceSource = (serviceId) => `service:${serviceId}`;
 

package/src/requester.js

@@ -0,0 +1,56 @@
+// Who asked for a service run, named in what the run leaves behind.
+//
+// A plain service writes with its own token, so the History entry of a run
+// reads "by <operator> (via <token>)" and the person who pressed the button is
+// recorded nowhere. Core tells every service who asked (`requesterId` in the
+// request data), and every app's services put that person in the History
+// label and in what they store:
+//
+//   AnCast adjudication against lunch, requested by second
+//
+// This is the JS twin of `plaid_client.workflows.requester`, for a service
+// authored with `serve`. The wording and the stored key are the same.
+//
+// The name is the requester's display name, which any signed-in user may
+// read. When it cannot be read the id stands in for it, and with no requester
+// at all the label is left as it was and nothing is stored.
+
+/** The key a run's stored record names its requester under. */
+export const REQUESTED_BY = "requestedBy";
+
+/**
+ * The person who asked for one run: `id` is their account (their email),
+ * `name` how they are shown. Both are null when nobody asked.
+ */
+export function makeRequester(id = null, name = null) {
+  return {
+    id,
+    name,
+    /** A History label with the requester named, or `text` when nobody asked. */
+    label: (text) => (name ? `${text}, requested by ${name}` : text),
+    /** `{ id, name }` for a stored report, or null when nobody asked. */
+    record: () => (id ? { id, name } : null),
+    /** A machine stamp's `provDetail` with the requester's id added. */
+    detail: (detail = {}) => ({ ...(detail || {}), ...(id ? { [REQUESTED_BY]: id } : {}) }),
+  };
+}
+
+/**
+ * The requester of one request, from the `requesterId` core put in its data,
+ * with their display name read through `client`.
+ * @param {object} client - A PlaidClient (only `users.get` is used)
+ * @param {object} data - The request data a `serve` handler receives
+ */
+export async function requesterOf(client, data) {
+  const id = data && typeof data === "object" ? data.requesterId || null : null;
+  if (!id) return makeRequester();
+  let name = null;
+  try {
+    name = (await client.users.get(id))?.displayName || null;
+  } catch (error) {
+    // The id is always there to fall back on, so a failed read costs the
+    // label nothing but the nicer name.
+    console.warn(`Could not read the requester ${id}: ${error?.message || error}`);
+  }
+  return makeRequester(id, name || id);
+}

package/src/services.js

@@ -138,6 +138,13 @@ export function reportRequestEvent(client, projectId, requestId, body) {
   );
 }
 
+/**
+ * HTTP statuses a refused service channel answers with that retrying cannot
+ * fix: a bad or revoked token, no write access to the project, a project that
+ * does not exist. The same set as the Python client's.
+ */
+const PERMANENT_STATUSES = new Set([400, 401, 403, 404, 405, 422]);
+
 /**
  * Register a service and handle incoming work requests.
  *
@@ -152,7 +159,9 @@ export function reportRequestEvent(client, projectId, requestId, body) {
  * @param {function} onServiceRequest - Handler callback (data, responseHelper)
  * @param {Object} extras - Optional additional metadata
  * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
- *   connection-state transitions: 'registered', 'reconnected', 'disconnected'.
+ *   connection-state transitions: 'registered', 'reconnected', 'disconnected',
+ *   and 'stopped' when the server refuses the channel for a reason retrying
+ *   cannot fix (see PERMANENT_STATUSES), which ends the registration.
  *   Called once per transition, not once per retry.
  * @returns {Object} ServiceRegistration with .stop(), .isRunning(), .isConnected(),
  *   .serviceInfo
@@ -237,11 +246,20 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
     const finished = () => cancelled.delete(requestId);
 
     // Every service is told who asked (`requesterId`), beside the payload
-    // when that is a plain object, and on the helper regardless.
+    // when that is a plain object, and on the helper regardless. A delegating
+    // service (extras `delegation: true`) also gets a short-lived token for the
+    // requesting user (`delegatedToken`) and the projects that token reaches
+    // (`delegatedProjects`, the request's own first), as the Python client
+    // hands them over.
     const requesterId = payload.requesterId || null;
+    const extra = {
+      ...(requesterId ? { requesterId } : {}),
+      ...(payload.delegatedToken ? { delegatedToken: payload.delegatedToken } : {}),
+      ...(payload.delegatedProjects ? { delegatedProjects: payload.delegatedProjects } : {}),
+    };
     const data =
-      requesterId && payload.data && typeof payload.data === 'object' && !Array.isArray(payload.data)
-        ? { ...payload.data, requesterId }
+      Object.keys(extra).length && payload.data && typeof payload.data === 'object' && !Array.isArray(payload.data)
+        ? { ...payload.data, ...extra }
         : payload.data;
 
     const scope = createCancelScope(() => cancelled.get(requestId) === true);
@@ -328,10 +346,23 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
   // means a service restart. A reopened channel counts as connected only once
   // the server has actually answered it (readyState OPEN), not merely because
   // the attempt was made.
+  //
+  // A channel the server REFUSED for a reason retrying cannot fix (the token
+  // was revoked, the user lost write access, the project is gone) ends the
+  // registration instead: the server closes a channel whose opener lost the
+  // right to it, and reopening it every few seconds forever would only hide
+  // that from the operator.
   reconnectTimer = setInterval(() => {
     if (!isRunning || !connection) return;
     if (connection.readyState === 1) { noteConnected(); return; }
     if (connection.readyState === 2) { // CLOSED (dropped or failed)
+      const status = connection.error?.status;
+      if (PERMANENT_STATUSES.has(status)) {
+        noteDisconnected();
+        serviceRegistration.stop();
+        report('stopped', `HTTP ${status}`);
+        return;
+      }
       noteDisconnected();
       try { connection = openChannel(); } catch (_) { /* retry next tick */ }
     }
@@ -368,6 +399,11 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * @param {Object} [opts]
  * @param {string} [opts.requestId] - A client-minted request id (UUID)
  * @param {function} [opts.onAccepted] - Called with the request id once the server has it
+ * @param {string[]} [opts.projectIds] - Other projects the request is about, beside
+ *   `projectId`. A delegating service's token is scoped to `projectId` and to those of
+ *   these the requester can read, and reaches nothing else
+ * @param {boolean} [opts.noOperation] - Carry no open operation: the service's writes
+ *   are a group of their own, not part of whatever operation this client has open
  * @returns {Promise<any>} The service's result
  */
 export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress, signal, opts = {}) {
@@ -376,12 +412,31 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
   // (the Python BaseService adopts the id around process_request). Only for a
   // plain-object payload — that's the only shape the service param schema
   // delivers anyway.
-  const group = client.operationGroup;
+  // Its kind and reference go too, so a service that writes before the
+  // requester does still records them.
+  //
+  // `opts.noOperation` sends none: the service starts a group of its own. For
+  // a request that is its own action whatever else is on the wire, such as
+  // approving an assistant's plan or starting a service run. The client holds
+  // one open operation, so without it an edit still saving at that moment
+  // would take in every write the request makes, under the edit's kind.
+  const group = opts.noOperation ? null : client.operationGroup;
   const payload =
     group && data && typeof data === 'object' && !Array.isArray(data)
-      ? { ...data, operationGroup: { id: group.id, message: group.message } }
+      ? {
+          ...data,
+          operationGroup: {
+            id: group.id,
+            message: group.message,
+            ...(group.kind ? { kind: group.kind } : {}),
+            ...(group.ref ? { ref: group.ref } : {}),
+          },
+        }
       : data;
-  const qs = opts.requestId ? `?request-id=${encodeURIComponent(opts.requestId)}` : '';
+  const query = new URLSearchParams();
+  if (opts.requestId) query.set('request-id', opts.requestId);
+  if (opts.projectIds?.length) query.set('project-ids', opts.projectIds.join(','));
+  const qs = String(query) ? `?${query}` : '';
   return streamServiceRequest(
     client,
     {

package/src/sse.js

@@ -12,6 +12,11 @@ import { transformResponse } from './transforms.js';
 // cadences, so a healthy idle stream never trips it.
 export const SSE_IDLE_TIMEOUT_MS = 60000;
 
+// The last failure warned about per stream URL, so a stream retried every few
+// seconds through an outage warns once per distinct failure rather than once
+// per attempt. Cleared when the stream opens. Mirrors the Python client.
+const lastWarning = new Map();
+
 /**
  * Project a parsed SSE `data:` object onto what a listener callback sees.
  *
@@ -42,7 +47,10 @@ export function eventPayload(eventType, parsed) {
  *   /listen bus; service request channels pass their own. Only /listen emits
  *   `heartbeat` events needing a POST confirmation — other streams keep
  *   themselves alive with ignored SSE comments.
- * @returns {Object} SSE connection with .close(), .getStats(), .readyState
+ * @returns {Object} SSE connection with .close(), .getStats(), .readyState,
+ *   and .error: once CLOSED, why (null when this side closed it). A refused
+ *   stream's error carries the HTTP `status`, and a stream the server ended
+ *   carries an error named `StreamClosed`.
  */
 export function createSSEConnection(client, projectId, onEvent, path) {
   const streamPath = path || `/api/v1/projects/${projectId}/listen`;
@@ -88,6 +96,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
 
   const sseConnection = {
     readyState: 0, // CONNECTING
+    error: null,
     close: () => {
       if (!isClosed) {
         isClosed = true;
@@ -130,11 +139,14 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           // takes over.
           console.warn('Service registration rejected (409): another instance of this service is already connected; will retry');
         }
-        throw new Error(`HTTP ${response.status} ${response.statusText}`);
+        const refused = new Error(`HTTP ${response.status} ${response.statusText}`);
+        refused.status = response.status;
+        throw refused;
       }
 
       isConnected = true;
       sseConnection.readyState = 1; // OPEN
+      lastWarning.delete(url);
 
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
@@ -188,9 +200,23 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           }
         }
       }
+      if (!isClosed) {
+        // The server ended the stream, for instance because the opener lost
+        // the right to it. Say so, so a caller can tell it from a close of
+        // its own.
+        sseConnection.error = Object.assign(new Error('The server closed the stream'), {
+          name: 'StreamClosed',
+        });
+      }
     } catch (error) {
+      if (!isClosed) sseConnection.error = error;
       if (error.name !== 'AbortError') {
-        console.warn('SSE connection error:', error);
+        const url = `${client.baseUrl}${streamPath}`;
+        const message = String(error?.message || error);
+        if (lastWarning.get(url) !== message) {
+          lastWarning.set(url, message);
+          console.warn('SSE connection error:', error);
+        }
       }
     } finally {
       clearIdleTimer();

package/src/transforms.js

@@ -27,6 +27,12 @@ export function transformKeyFromCamel(key) {
 // usual case conversion.
 const OPAQUE_KEYS = new Set(['metadata', 'config', 'bindings']);
 
+// A request's `metadata` may also be a list of metadata ops (a bulk update
+// entry), whose values are user data too, so it passes through verbatim.
+const isOpaque = (key, value) =>
+  typeof value === 'object' && value !== null &&
+  (Array.isArray(value) ? key === 'metadata' : OPAQUE_KEYS.has(key));
+
 /**
  * Recursively transform request object keys from camelCase to kebab-case.
  * Preserves `metadata` and `config` contents without transformation.
@@ -39,7 +45,7 @@ export function transformRequest(obj) {
   const transformed = {};
   for (const [key, value] of Object.entries(obj)) {
     const newKey = transformKeyFromCamel(key);
-    if (OPAQUE_KEYS.has(key) && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    if (isOpaque(key, value)) {
       transformed[newKey] = value;
     } else {
       transformed[newKey] = transformRequest(value);