@larc-iu/plaid-client 0.0.0

package/index.d.ts

@@ -0,0 +1,270 @@
+/** A single page of a cursor-paginated collection. */
+interface Page<T = any> {
+  entries: T[];
+  nextCursor: string | null;
+}
+
+interface ServiceInfo {
+  serviceId: string;
+  serviceName: string;
+  description: string;
+  extras?: any;
+}
+
+interface DiscoveredService {
+  serviceId: string;
+  serviceName: string;
+  description: string;
+  extras: any;
+}
+
+interface ServiceRegistration {
+  stop(): void;
+  isRunning(): boolean;
+  serviceInfo: ServiceInfo & { extras: any };
+}
+
+interface ResponseHelper {
+  progress(percent: number, message: string): void;
+  complete(data: any): void;
+  error(error: string | Error): void;
+}
+
+interface SSEConnection {
+  close(): void;
+  getStats(): any;
+  readyState: number;
+}
+
+interface VocabLinksBundle {
+  create(vocabItem: string, tokens: any[], metadata?: any): Promise<any>;
+  setMetadata(id: string, body: any): Promise<any>;
+  deleteMetadata(id: string): Promise<any>;
+  get(id: string, asOf?: string): Promise<any>;
+  delete(id: string): Promise<any>;
+}
+
+interface VocabLayersBundle {
+  get(id: string, includeItems?: boolean, asOf?: string): Promise<any>;
+  delete(id: string): Promise<any>;
+  update(id: string, name: string): Promise<any>;
+  setConfig(id: string, namespace: string, configKey: string, configValue: any): Promise<any>;
+  deleteConfig(id: string, namespace: string, configKey: string): Promise<any>;
+  list(asOf?: string): Promise<any[]>;
+  listPage(opts?: { limit?: number; cursor?: string; asOf?: string }): Promise<Page>;
+  iterPages(opts?: { pageSize?: number; asOf?: string }): AsyncGenerator<any[]>;
+  create(name: string): Promise<any>;
+  addMaintainer(id: string, userId: string): Promise<any>;
+  removeMaintainer(id: string, userId: string): Promise<any>;
+}
+
+interface RelationsBundle {
+  setMetadata(relationId: string, body: any): Promise<any>;
+  deleteMetadata(relationId: string): Promise<any>;
+  setTarget(relationId: string, spanId: string): Promise<any>;
+  get(relationId: string, asOf?: string): Promise<any>;
+  delete(relationId: string): Promise<any>;
+  update(relationId: string, value: any): Promise<any>;
+  setSource(relationId: string, spanId: string): Promise<any>;
+  create(layerId: string, sourceId: string, targetId: string, value: any, metadata?: any): Promise<any>;
+  bulkCreate(body: any[]): Promise<any>;
+  bulkDelete(body: any[]): Promise<any>;
+}
+
+interface SpanLayersBundle {
+  setConfig(spanLayerId: string, namespace: string, configKey: string, configValue: any): Promise<any>;
+  deleteConfig(spanLayerId: string, namespace: string, configKey: string): Promise<any>;
+  get(spanLayerId: string, asOf?: string): Promise<any>;
+  delete(spanLayerId: string): Promise<any>;
+  update(spanLayerId: string, name: string): Promise<any>;
+  create(tokenLayerId: string, name: string): Promise<any>;
+  shift(spanLayerId: string, direction: string): Promise<any>;
+}
+
+interface SpansBundle {
+  setTokens(spanId: string, tokens: any[]): Promise<any>;
+  create(spanLayerId: string, tokens: any[], value: any, metadata?: any): Promise<any>;
+  get(spanId: string, asOf?: string): Promise<any>;
+  delete(spanId: string): Promise<any>;
+  update(spanId: string, value: any): Promise<any>;
+  bulkCreate(body: any[]): Promise<any>;
+  bulkDelete(body: any[]): Promise<any>;
+  setMetadata(spanId: string, body: any): Promise<any>;
+  deleteMetadata(spanId: string): Promise<any>;
+}
+
+interface BatchBundle {
+  submit(body: any[]): Promise<any>;
+}
+
+interface TextsBundle {
+  setMetadata(textId: string, body: any): Promise<any>;
+  deleteMetadata(textId: string): Promise<any>;
+  create(textLayerId: string, documentId: string, body: string, metadata?: any): Promise<any>;
+  get(textId: string, asOf?: string): Promise<any>;
+  delete(textId: string): Promise<any>;
+  update(textId: string, body: any): Promise<any>;
+}
+
+interface UsersBundle {
+  list(asOf?: string): Promise<any[]>;
+  listPage(opts?: { limit?: number; cursor?: string; asOf?: string }): Promise<Page>;
+  iterPages(opts?: { pageSize?: number; asOf?: string }): AsyncGenerator<any[]>;
+  create(username: string, password: string, isAdmin: boolean): Promise<any>;
+  audit(userId: string, startTime?: string, endTime?: string, asOf?: string): Promise<any[]>;
+  get(id: string, asOf?: string): Promise<any>;
+  delete(id: string): Promise<any>;
+  update(id: string, password?: string, username?: string, isAdmin?: boolean): Promise<any>;
+}
+
+interface ApiTokensBundle {
+  list(userId: string): Promise<any[]>;
+  listPage(userId: string, opts?: { limit?: number; cursor?: string }): Promise<Page>;
+  iterPages(userId: string, opts?: { pageSize?: number }): AsyncGenerator<any[]>;
+  create(userId: string, name: string): Promise<{ id: string; name: string; token: string }>;
+  revoke(userId: string, tokenId: string): Promise<any>;
+}
+
+interface TokenLayersBundle {
+  shift(tokenLayerId: string, direction: string): Promise<any>;
+  create(textLayerId: string, name: string, overlapMode?: string, parentTokenLayerId?: string): Promise<any>;
+  setConfig(tokenLayerId: string, namespace: string, configKey: string, configValue: any): Promise<any>;
+  deleteConfig(tokenLayerId: string, namespace: string, configKey: string): Promise<any>;
+  get(tokenLayerId: string, asOf?: string): Promise<any>;
+  delete(tokenLayerId: string): Promise<any>;
+  update(tokenLayerId: string, name: string): Promise<any>;
+}
+
+interface DocumentsBundle {
+  checkLock(documentId: string, asOf?: string): Promise<any>;
+  acquireLock(documentId: string): Promise<any>;
+  releaseLock(documentId: string): Promise<any>;
+  getMedia(documentId: string, asOf?: string): Promise<ArrayBuffer>;
+  uploadMedia(documentId: string, file: File): Promise<any>;
+  deleteMedia(documentId: string): Promise<any>;
+  setMetadata(documentId: string, body: any): Promise<any>;
+  deleteMetadata(documentId: string): Promise<any>;
+  audit(documentId: string, startTime?: string, endTime?: string, asOf?: string): Promise<any[]>;
+  get(documentId: string, includeBody?: boolean, asOf?: string): Promise<any>;
+  delete(documentId: string): Promise<any>;
+  update(documentId: string, name: string): Promise<any>;
+  create(projectId: string, name: string, metadata?: any): Promise<any>;
+}
+
+interface MessagesBundle {
+  sendMessage(projectId: string, data: any): Promise<any>;
+  listen(projectId: string, onEvent: (eventType: string, data: any) => void | boolean, path?: string): SSEConnection;
+  /** Discover the services currently connected to a project. `timeout` is ignored (kept for back-compat). */
+  discoverServices(projectId: string, timeout?: number): Promise<DiscoveredService[]>;
+  serve(projectId: string, serviceInfo: ServiceInfo, onServiceRequest: (data: any, responseHelper: ResponseHelper) => void, extras?: any): ServiceRegistration;
+  /** Submit work to a service; streams progress to `onProgress`, resolves with the result. */
+  requestService(projectId: string, serviceId: string, data: any, timeout?: number, onProgress?: (progress: any) => void): Promise<any>;
+}
+
+interface ProjectsBundle {
+  addWriter(id: string, userId: string): Promise<any>;
+  removeWriter(id: string, userId: string): Promise<any>;
+  addReader(id: string, userId: string): Promise<any>;
+  removeReader(id: string, userId: string): Promise<any>;
+  setConfig(id: string, namespace: string, configKey: string, configValue: any): Promise<any>;
+  deleteConfig(id: string, namespace: string, configKey: string): Promise<any>;
+  addMaintainer(id: string, userId: string): Promise<any>;
+  removeMaintainer(id: string, userId: string): Promise<any>;
+  audit(projectId: string, startTime?: string, endTime?: string, asOf?: string): Promise<any[]>;
+  linkVocab(id: string, vocabId: string): Promise<any>;
+  unlinkVocab(id: string, vocabId: string): Promise<any>;
+  get(id: string, asOf?: string): Promise<any>;
+  listDocuments(id: string): Promise<any[]>;
+  listDocumentsPage(id: string, opts?: { limit?: number; cursor?: string }): Promise<Page>;
+  iterDocuments(id: string, opts?: { pageSize?: number }): AsyncGenerator<any[]>;
+  delete(id: string): Promise<any>;
+  update(id: string, name: string): Promise<any>;
+  list(asOf?: string): Promise<any[]>;
+  listPage(opts?: { limit?: number; cursor?: string; asOf?: string }): Promise<Page>;
+  iterPages(opts?: { pageSize?: number; asOf?: string }): AsyncGenerator<any[]>;
+  create(name: string): Promise<any>;
+}
+
+interface TextLayersBundle {
+  setConfig(textLayerId: string, namespace: string, configKey: string, configValue: any): Promise<any>;
+  deleteConfig(textLayerId: string, namespace: string, configKey: string): Promise<any>;
+  get(textLayerId: string, asOf?: string): Promise<any>;
+  delete(textLayerId: string): Promise<any>;
+  update(textLayerId: string, name: string): Promise<any>;
+  shift(textLayerId: string, direction: string): Promise<any>;
+  create(projectId: string, name: string): Promise<any>;
+}
+
+interface VocabItemsBundle {
+  setMetadata(id: string, body: any): Promise<any>;
+  deleteMetadata(id: string): Promise<any>;
+  create(vocabLayerId: string, form: string, metadata?: any): Promise<any>;
+  get(id: string, asOf?: string): Promise<any>;
+  delete(id: string): Promise<any>;
+  update(id: string, form: string): Promise<any>;
+}
+
+interface RelationLayersBundle {
+  shift(relationLayerId: string, direction: string): Promise<any>;
+  create(spanLayerId: string, name: string): Promise<any>;
+  setConfig(relationLayerId: string, namespace: string, configKey: string, configValue: any): Promise<any>;
+  deleteConfig(relationLayerId: string, namespace: string, configKey: string): Promise<any>;
+  get(relationLayerId: string, asOf?: string): Promise<any>;
+  delete(relationLayerId: string): Promise<any>;
+  update(relationLayerId: string, name: string): Promise<any>;
+}
+
+interface TokensBundle {
+  create(tokenLayerId: string, text: string, begin: number, end: number, precedence?: number | null, metadata?: any): Promise<any>;
+  get(tokenId: string, asOf?: string): Promise<any>;
+  delete(tokenId: string): Promise<any>;
+  update(tokenId: string, begin?: number, end?: number, precedence?: number | null): Promise<any>;
+  bulkCreate(body: any[]): Promise<any>;
+  bulkDelete(body: any[]): Promise<any>;
+  split(tokenId: string, position: number): Promise<any>;
+  merge(tokenId: string, otherTokenId: string): Promise<any>;
+  shift(tokenId: string, begin?: number, end?: number): Promise<any>;
+  setMetadata(tokenId: string, body: any): Promise<any>;
+  deleteMetadata(tokenId: string): Promise<any>;
+}
+
+interface PlaidClientOptions {
+  /** Per-request timeout in ms (default 30000; 0 or null disables it). */
+  timeout?: number | null;
+}
+
+export declare class PlaidClient {
+  constructor(baseUrl: string, token: string, options?: PlaidClientOptions);
+  static login(baseUrl: string, userId: string, password: string, options?: PlaidClientOptions): Promise<PlaidClient>;
+  timeout: number | null;
+
+  // Batch control methods
+  beginBatch(): void;
+  submitBatch(): Promise<any[]>;
+  abortBatch(): void;
+  isBatchMode(): boolean;
+
+  // Strict mode methods
+  enterStrictMode(documentId: string): void;
+  exitStrictMode(): void;
+
+  vocabLinks: VocabLinksBundle;
+  vocabLayers: VocabLayersBundle;
+  relations: RelationsBundle;
+  spanLayers: SpanLayersBundle;
+  spans: SpansBundle;
+  batch: BatchBundle;
+  texts: TextsBundle;
+  users: UsersBundle;
+  apiTokens: ApiTokensBundle;
+  tokenLayers: TokenLayersBundle;
+  documents: DocumentsBundle;
+  messages: MessagesBundle;
+  projects: ProjectsBundle;
+  textLayers: TextLayersBundle;
+  vocabItems: VocabItemsBundle;
+  relationLayers: RelationLayersBundle;
+  tokens: TokensBundle;
+}
+
+export default PlaidClient;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@larc-iu/plaid-client",
+  "version": "0.0.0",
+  "description": "JavaScript client for the Plaid annotation API",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/larc-iu/plaid.git",
+    "directory": "plaid-client-js"
+  },
+  "homepage": "https://github.com/larc-iu/plaid#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "src/",
+    "index.d.ts"
+  ]
+}

package/src/http.js

@@ -0,0 +1,212 @@
+import { transformRequest, transformResponse } from './transforms.js';
+
+// Default per-request timeout (ms). Applied to every request unless the client
+// is constructed with a different `timeout` (0 / null disables it). Note: this
+// also bounds media up/downloads — bump it (or disable) for very large files.
+export const DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * Extract and update document versions from response headers and body.
+ */
+export function extractDocumentVersions(client, responseHeaders, responseBody = null) {
+  const docVersionsHeader = responseHeaders.get('X-Document-Versions');
+  if (docVersionsHeader) {
+    try {
+      const versionsMap = JSON.parse(docVersionsHeader);
+      if (typeof versionsMap === 'object' && versionsMap !== null) {
+        // Clone once, then assign — cloning inside the loop is O(n²) and pointless.
+        client.documentVersions = { ...client.documentVersions, ...versionsMap };
+      }
+    } catch (e) {
+      console.warn('Failed to parse document versions header:', e);
+    }
+  }
+
+  if (responseBody && typeof responseBody === 'object') {
+    if (responseBody['document/id'] && responseBody['document/version']) {
+      client.documentVersions = { ...client.documentVersions };
+      client.documentVersions[responseBody['document/id']] = responseBody['document/version'];
+    }
+  }
+}
+
+/**
+ * Read a failed response's body as parsed JSON, falling back to text.
+ */
+export async function parseErrorBody(response) {
+  try {
+    return await response.json();
+  } catch (_) {
+    return { message: await response.text().catch(() => 'Unable to read error response') };
+  }
+}
+
+/**
+ * Create an enriched error from a failed HTTP response.
+ */
+export function makeHttpError(response, errorData, url, method) {
+  const serverMessage = errorData?.error || errorData?.message || response.statusText || 'Unknown error';
+  const error = new Error(`HTTP ${response.status} ${serverMessage} at ${url}`);
+  error.status = response.status;
+  error.statusText = response.statusText;
+  error.url = url;
+  error.method = method;
+  error.responseData = errorData;
+  return error;
+}
+
+/**
+ * Create a network error (status 0). Timeout aborts get a clearer message.
+ */
+export function makeNetworkError(originalError, url, method) {
+  const timedOut = originalError?.name === 'TimeoutError' || originalError?.name === 'AbortError';
+  const message = timedOut
+    ? `Request timed out at ${url}`
+    : `Network error: ${originalError.message} at ${url}`;
+  const error = new Error(message);
+  error.status = 0;
+  error.url = url;
+  error.method = method;
+  error.originalError = originalError;
+  return error;
+}
+
+/**
+ * Build a fetch AbortSignal that fires after `timeout` ms, or undefined when
+ * timeouts are disabled / unsupported.
+ */
+export function timeoutSignal(timeout) {
+  if (timeout && timeout > 0 && typeof AbortSignal !== 'undefined' && AbortSignal.timeout) {
+    return AbortSignal.timeout(timeout);
+  }
+  return undefined;
+}
+
+/**
+ * Generic request method handling all fetch logic.
+ *
+ * Options:
+ *   body            - Object body, run through transformRequest
+ *   rawBody         - Body value passed directly (no transform). Mutually exclusive with body.
+ *   formData        - If true, body is FormData; skip Content-Type header
+ *   queryParams     - Object of query param key/values to append
+ *   noBatch         - If true, throw when in batch mode
+ *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
+ *   noAuth          - Skip Authorization header
+ *   binaryResponse  - Return arrayBuffer instead of JSON/text
+ */
+export async function makeRequest(client, method, path, options = {}) {
+  const {
+    body,
+    rawBody,
+    formData,
+    queryParams,
+    noBatch,
+    skipResponseTransform,
+    noAuth,
+    binaryResponse,
+  } = options;
+
+  // Build URL
+  let url = `${client.baseUrl}${path}`;
+
+  // Append query params
+  if (queryParams) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(queryParams)) {
+      if (value !== undefined && value !== null) {
+        // URLSearchParams stringifies booleans to lowercase 'true'/'false',
+        // which the server's malli coercion requires (the Python client does
+        // this conversion explicitly).
+        params.append(key, value);
+      }
+    }
+    const qs = params.toString();
+    if (qs) url += `?${qs}`;
+  }
+
+  // Prepare request body
+  let requestBody;
+  if (formData) {
+    requestBody = body; // FormData passed directly
+  } else if (rawBody !== undefined) {
+    requestBody = rawBody;
+  } else if (body !== undefined) {
+    requestBody = transformRequest(body);
+  }
+
+  // Strict mode: append document-version for non-GET requests
+  if (client.strictModeDocumentId && method !== 'GET') {
+    const docId = client.strictModeDocumentId;
+    if (client.documentVersions[docId]) {
+      const docVersion = client.documentVersions[docId];
+      const separator = url.includes('?') ? '&' : '?';
+      url += `${separator}document-version=${encodeURIComponent(docVersion)}`;
+    }
+  }
+
+  // Batch mode
+  if (client.isBatching) {
+    if (noBatch) {
+      throw new Error(`This endpoint cannot be used in batch mode: ${path}`);
+    }
+    const operation = {
+      path: url.replace(client.baseUrl, ''),
+      method: method.toUpperCase(),
+    };
+    if (requestBody !== undefined) {
+      operation.body = requestBody;
+    }
+    client.batchOperations.push(operation);
+    return { batched: true };
+  }
+
+  // Build fetch options
+  const headers = {};
+  if (!noAuth) {
+    headers['Authorization'] = `Bearer ${client.token}`;
+  }
+  if (!formData) {
+    headers['Content-Type'] = 'application/json';
+  }
+
+  const fetchOptions = { method, headers };
+  if (requestBody !== undefined) {
+    fetchOptions.body = formData ? requestBody : JSON.stringify(requestBody);
+  }
+  const signal = timeoutSignal(client.timeout);
+  if (signal) fetchOptions.signal = signal;
+
+  try {
+    const response = await fetch(url, fetchOptions);
+
+    if (!response.ok) {
+      throw makeHttpError(response, await parseErrorBody(response), url, method);
+    }
+
+    // Binary response (getMedia)
+    if (binaryResponse) {
+      extractDocumentVersions(client, response.headers);
+      return await response.arrayBuffer();
+    }
+
+    // JSON or text response
+    const contentType = response.headers.get('content-type');
+    if (contentType && contentType.includes('application/json')) {
+      const data = await response.json();
+      extractDocumentVersions(client, response.headers, data);
+      if (skipResponseTransform) {
+        return data;
+      }
+      return transformResponse(data);
+    } else {
+      extractDocumentVersions(client, response.headers);
+      return await response.text();
+    }
+  } catch (error) {
+    if (error.status !== undefined) {
+      throw error;
+    }
+    throw makeNetworkError(error, url, method);
+  }
+}