@larc-iu/plaid-client 0.0.0

package/src/pagination.js

@@ -0,0 +1,142 @@
+/**
+ * Cursor-pagination helpers for collection endpoints.
+ *
+ * The server's collection endpoints return a paginated envelope shaped like
+ * `{ entries: [...], nextCursor: "<opaque-string>" | null }` (the wire key
+ * `next-cursor` is camelCased to `nextCursor` by transformResponse). These
+ * helpers paper over the cursoring so callers can either get the full flat
+ * array transparently, request a single page, or iterate page-by-page.
+ *
+ * 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.
+ */
+
+// Merge caller query params with paging params, dropping undefined/null so we
+// don't emit empty query string values.
+function buildQueryParams(query, limit, cursor) {
+  const params = { ...query };
+  if (limit !== undefined && limit !== null) params.limit = limit;
+  if (cursor !== undefined && cursor !== null) params.cursor = cursor;
+  return params;
+}
+
+/**
+ * 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]
+ * @param {number} [opts.pageSize=1000] - Per-request page size (limit)
+ * @param {object} [opts.query={}] - Extra query params (e.g. { 'as-of': asOf })
+ * @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),
+    });
+    // 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.",
+      );
+    }
+    prevCursor = cursor;
+    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) {
+      throw new Error(
+        'Pagination cursor did not advance; aborting to avoid an infinite loop.',
+      );
+    }
+  } while (cursor !== null && cursor !== undefined);
+  return all;
+}
+
+/**
+ * Fetch a single page and return the raw envelope.
+ *
+ * @param {object} client - PlaidClient instance
+ * @param {string} path - API path
+ * @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 {object} [opts.query={}] - Extra query params
+ * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+ */
+export async function listPage(client, path, { limit, cursor, query = {} } = {}) {
+  return client._request('GET', path, {
+    queryParams: buildQueryParams(query, limit, cursor),
+  });
+}
+
+/**
+ * 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]
+ * @param {number} [opts.pageSize=1000] - Per-request page size (limit)
+ * @param {object} [opts.query={}] - Extra query params
+ * @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 : [];
+    // 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.
+    if (entries.length > 0) {
+      yield entries;
+    }
+    prevCursor = cursor;
+    cursor = response ? response.nextCursor : null;
+    // 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) {
+      throw new Error(
+        'Pagination cursor did not advance; aborting to avoid an infinite loop.',
+      );
+    }
+  } while (cursor !== null && cursor !== undefined);
+}

package/src/services.js

@@ -0,0 +1,220 @@
+/**
+ * Service coordination: discovery + server-mediated request/response RPC.
+ *
+ * All of this runs OFF the broadcast bus (`/listen` + `/message`). A service is
+ * present exactly while its inbound request channel (SSE) is open — that
+ * channel is the registration; there is no separate registry or heartbeat.
+ * Discovery is a synchronous GET. Work requests are addressed: a service
+ * receives them on its channel and reports back via plain POSTs that the
+ * server relays to the one waiting requester.
+ */
+import { transformRequest, transformResponse } from './transforms.js';
+
+/**
+ * Discover the services currently connected to a project — a synchronous GET.
+ * `timeout` is accepted for back-compat and ignored.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {number} [timeout] - Ignored
+ * @returns {Promise<Array>} [{serviceId, serviceName, description, extras}]
+ */
+export function discoverServices(client, projectId, timeout) {
+  return client._request('GET', `/api/v1/projects/${projectId}/services`);
+}
+
+/**
+ * Register a service and handle incoming work requests.
+ *
+ * Opens the service's dedicated request channel — which registers it for
+ * discovery (presence = open channel) — and handles work on it. For each
+ * request, runs `onServiceRequest(data, responseHelper)` where `responseHelper`
+ * has `progress(percent, msg)` / `complete(data)` / `error(err)`.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {Object} serviceInfo - {serviceId, serviceName, description}
+ * @param {function} onServiceRequest - Handler callback (data, responseHelper)
+ * @param {Object} extras - Optional additional metadata
+ * @returns {Object} ServiceRegistration with .stop(), .isRunning(), .serviceInfo
+ */
+export function serve(client, projectId, serviceInfo, onServiceRequest, extras = {}) {
+  const { serviceId, serviceName, description = '' } = serviceInfo;
+  let connection = null;
+  let isRunning = true;
+  let reconnectTimer = null;
+
+  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);
+      });
+
+  const serviceRegistration = {
+    stop: () => {
+      isRunning = false;
+      if (reconnectTimer) { clearInterval(reconnectTimer); reconnectTimer = null; }
+      // Closing the channel deregisters the service server-side.
+      if (connection) connection.close();
+    },
+    isRunning: () => isRunning,
+    serviceInfo: { serviceId, serviceName, description, extras },
+  };
+
+  // Discovery metadata rides the channel's query string — opening the channel
+  // is the registration. Keep wire keys kebab-case (transform extras too) so
+  // they round-trip like the rest of the API.
+  const params = new URLSearchParams();
+  if (serviceName) params.set('service-name', serviceName);
+  if (description) params.set('description', description);
+  if (extras && Object.keys(extras).length) params.set('extras', JSON.stringify(transformRequest(extras)));
+  const qs = params.toString();
+  const channelPath = `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}/requests${qs ? `?${qs}` : ''}`;
+
+  // The channel only carries `connected` (ignored) and `service_request` events.
+  const onChannelEvent = (eventType, payload) => {
+    if (!isRunning) return true;
+    if (eventType !== 'service_request' || !payload) return;
+    const requestId = payload.requestId;
+    if (!requestId) return;
+
+    const responseHelper = {
+      progress: (percent, msg) =>
+        reportEvent(requestId, { status: 'progress', progress: { percent, message: msg } }),
+      complete: (data) =>
+        reportEvent(requestId, { status: 'completed', data }),
+      error: (error) =>
+        reportEvent(requestId, { status: 'error', data: { error: error?.message || error } }),
+    };
+
+    try {
+      onServiceRequest(payload.data, responseHelper);
+    } catch (error) {
+      responseHelper.error(error?.message || error);
+    }
+  };
+  const openChannel = () => client.messages.listen(projectId, onChannelEvent, channelPath);
+  try {
+    connection = openChannel();
+  } catch (error) {
+    throw new Error(`Failed to start service: ${error.message}`);
+  }
+
+  // Reopen the channel if it drops (e.g. the server restarted). Reopening
+  // re-registers the service server-side, so presence and reachability come
+  // back together.
+  reconnectTimer = setInterval(() => {
+    if (!isRunning) return;
+    if (connection && connection.readyState === 2) { // CLOSED (dropped)
+      try { connection = openChannel(); } catch (_) { /* retry next tick */ }
+    }
+  }, 3000);
+
+  return serviceRegistration;
+}
+
+/**
+ * Submit work to a service and await its result.
+ *
+ * Streams the service's progress + result back over a single server-mediated
+ * response (no broadcast). Rejects if no service is connected (503), if the
+ * service reports an error, or on timeout.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} serviceId - Service ID to request
+ * @param {any} data - Request payload
+ * @param {number} [timeout=10000] - Timeout in ms
+ * @param {function} [onProgress] - Called with each progress payload {percent, message}
+ * @returns {Promise<any>} The service's result
+ */
+export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress) {
+  return new Promise((resolve, reject) => {
+    const abortController = new AbortController();
+    let settled = false;
+    const finish = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      abortController.abort();
+      fn(arg);
+    };
+    const timer = setTimeout(
+      () => finish(reject, new Error(`Service request timed out after ${timeout}ms`)),
+      timeout,
+    );
+
+    (async () => {
+      let response;
+      try {
+        response = await fetch(
+          `${client.baseUrl}/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}/requests`,
+          {
+            method: 'POST',
+            headers: {
+              'Authorization': `Bearer ${client.token}`,
+              'Content-Type': 'application/json',
+              'Accept': 'text/event-stream',
+            },
+            body: JSON.stringify(data === undefined ? null : transformRequest(data)),
+            signal: abortController.signal,
+          },
+        );
+      } catch (error) {
+        if (error.name !== 'AbortError') finish(reject, new Error(`Failed to submit service request: ${error.message}`));
+        return;
+      }
+
+      if (response.status === 503) {
+        finish(reject, new Error(`No live service '${serviceId}' on this project`));
+        return;
+      }
+      if (!response.ok) {
+        finish(reject, new Error(`Service request failed: HTTP ${response.status} ${response.statusText}`));
+        return;
+      }
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      let eventType = '';
+      let dataLine = '';
+
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done || settled) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split('\n');
+          buffer = lines.pop() || '';
+          for (const rawLine of lines) {
+            const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+            if (line.startsWith('event: ')) {
+              eventType = line.slice(7).trim();
+            } else if (line.startsWith('data: ')) {
+              dataLine = line.slice(6);
+            } else if (line === '' && eventType && dataLine) {
+              const payload = transformResponse(JSON.parse(dataLine));
+              if (eventType === 'progress') {
+                if (onProgress) { try { onProgress(payload.progress); } catch (_) { /* ignore */ } }
+              } else if (eventType === 'result') {
+                finish(resolve, payload.data);
+                return;
+              } else if (eventType === 'error') {
+                finish(reject, new Error(payload?.error || 'Service request failed'));
+                return;
+              }
+              eventType = '';
+              dataLine = '';
+            }
+          }
+        }
+        finish(reject, new Error('Service closed the connection without a result'));
+      } catch (error) {
+        if (error.name !== 'AbortError') finish(reject, new Error(`Service request stream error: ${error.message}`));
+      }
+    })();
+  });
+}

package/src/sse.js

@@ -0,0 +1,147 @@
+import { transformResponse } from './transforms.js';
+
+/**
+ * Create an SSE connection to the listen endpoint using fetch-based streaming.
+ * Automatically handles heartbeat confirmations and event parsing.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {function} onEvent - Callback (eventType, data). Return true to stop.
+ * @param {string} [path] - Stream path under baseUrl. Defaults to the project
+ *   /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
+ */
+export function createSSEConnection(client, projectId, onEvent, path) {
+  const streamPath = path || `/api/v1/projects/${projectId}/listen`;
+  const startTime = Date.now();
+  let isConnected = false;
+  let isClosed = false;
+  let clientId = null;
+  let eventStats = { 'audit-log': 0, message: 0, heartbeat: 0, connected: 0, other: 0 };
+  let abortController = new AbortController();
+
+  const sendHeartbeatConfirmation = async () => {
+    if (!clientId || isClosed) return;
+    try {
+      const response = await fetch(`${client.baseUrl}/api/v1/projects/${projectId}/heartbeat`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${client.token}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ 'client-id': clientId }),
+        signal: abortController.signal,
+      });
+      if (!response.ok) { /* heartbeat failed */ }
+    } catch (error) {
+      if (error.name !== 'AbortError') { /* heartbeat error */ }
+    }
+  };
+
+  const sseConnection = {
+    readyState: 0, // CONNECTING
+    close: () => {
+      if (!isClosed) {
+        isClosed = true;
+        isConnected = false;
+        sseConnection.readyState = 2; // CLOSED
+        abortController.abort();
+      }
+    },
+    getStats: () => ({
+      durationSeconds: (Date.now() - startTime) / 1000,
+      isConnected,
+      isClosed,
+      clientId,
+      events: { ...eventStats },
+      readyState: sseConnection.readyState,
+    }),
+  };
+
+  // Start the streaming connection
+  (async () => {
+    try {
+      const url = `${client.baseUrl}${streamPath}`;
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${client.token}`,
+          'Accept': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+        },
+        signal: abortController.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status} ${response.statusText}`);
+      }
+
+      isConnected = true;
+      sseConnection.readyState = 1; // OPEN
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      // Event state persists across read chunks: an event's `event:` and
+      // `data:` lines may land in separate reads, so these are reset only
+      // after an event is dispatched (mirrors the Python client).
+      let eventType = '';
+      let data = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done || isClosed) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const rawLine of lines) {
+          // Strip a trailing CR so CRLF-delimited streams parse cleanly.
+          const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+          if (line.startsWith('event: ')) {
+            eventType = line.slice(7).trim();
+          } else if (line.startsWith('data: ')) {
+            data = line.slice(6);
+          } else if (line === '' && eventType && data) {
+            try {
+              eventStats[eventType] = (eventStats[eventType] || 0) + 1;
+
+              if (eventType === 'connected') {
+                const parsedData = JSON.parse(data);
+                clientId = parsedData['client-id'] || parsedData.clientId;
+              } else if (eventType === 'heartbeat') {
+                sendHeartbeatConfirmation();
+              } else {
+                const parsedData = JSON.parse(data);
+                const shouldStop = onEvent(eventType, transformResponse(parsedData));
+                if (shouldStop === true) {
+                  sseConnection.close();
+                  return;
+                }
+              }
+            } catch (e) {
+              console.warn('Failed to parse SSE event data:', e);
+            }
+
+            eventType = '';
+            data = '';
+          }
+        }
+      }
+    } catch (error) {
+      if (error.name !== 'AbortError') {
+        console.warn('SSE connection error:', error);
+      }
+    } finally {
+      isConnected = false;
+      isClosed = true;
+      sseConnection.readyState = 2; // CLOSED
+    }
+  })();
+
+  return sseConnection;
+}

package/src/transforms.js

@@ -0,0 +1,70 @@
+/**
+ * Convert kebab-case/namespaced key to camelCase.
+ * 'layer-id' -> 'layerId'
+ * 'relation/layer' -> 'layer' (namespace stripped)
+ * Hyphens before a digit are also consumed ('layer-2' -> 'layer2') so no stray
+ * hyphen is ever left in the key. (The Python client uses snake_case, where the
+ * analogous key is 'layer_2' — the local spelling differs by convention, but
+ * neither leaves a separator that doesn't belong to the convention.)
+ */
+export function transformKeyToCamel(key) {
+  return key.replace(/^[^/]+\//, '').replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Convert camelCase key to kebab-case.
+ * 'layerId' -> 'layer-id'
+ */
+export function transformKeyFromCamel(key) {
+  return key.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
+
+// `metadata` and `config` are opaque, client-agnostic buckets: their contents
+// are arbitrary user/application data whose keys must NOT vary by client. We
+// pass their values through verbatim (no recursion) so object keys inside them
+// are never re-cased or namespace-stripped — a label like `case-marker` used as
+// a map key survives intact. Everything else is API envelope and gets the
+// usual case conversion.
+const OPAQUE_KEYS = new Set(['metadata', 'config']);
+
+/**
+ * Recursively transform request object keys from camelCase to kebab-case.
+ * Preserves `metadata` and `config` contents without transformation.
+ */
+export function transformRequest(obj) {
+  if (obj === null || obj === undefined) return obj;
+  if (Array.isArray(obj)) return obj.map(item => transformRequest(item));
+  if (typeof obj !== 'object') return 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)) {
+      transformed[newKey] = value;
+    } else {
+      transformed[newKey] = transformRequest(value);
+    }
+  }
+  return transformed;
+}
+
+/**
+ * Recursively transform response object keys from kebab-case/namespaced to camelCase.
+ * Preserves `metadata` and `config` contents without transformation.
+ */
+export function transformResponse(obj) {
+  if (obj === null || obj === undefined) return obj;
+  if (Array.isArray(obj)) return obj.map(item => transformResponse(item));
+  if (typeof obj !== 'object') return obj;
+
+  const transformed = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const newKey = transformKeyToCamel(key);
+    if (OPAQUE_KEYS.has(newKey) && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      transformed[newKey] = value;
+    } else {
+      transformed[newKey] = transformResponse(value);
+    }
+  }
+  return transformed;
+}