@larc-iu/plaid-client 0.1.0-alpha.9 → 0.2.0-alpha.0

package/index.d.ts

@@ -54,6 +54,10 @@ interface DiscoveredService {
   serviceName: string;
   description: string;
   extras: ServiceExtras;
+  /** true while the service holds an open request channel; false for previously-seen offline services. */
+  online: boolean;
+  /** ISO-8601 stamp of when the service was last seen alive, or null/undefined if never persisted. */
+  lastSeenAt?: string | null;
 }
 
 interface ServiceRegistration {
@@ -75,226 +79,250 @@ interface SSEConnection {
 }
 
 interface VocabLinksBundle {
-  create(vocabItem: string, tokens: any[], metadata?: any): Promise<any>;
-  setMetadata(id: string, body: any): Promise<any>;
-  deleteMetadata(id: string): Promise<any>;
-  patchMetadata(id: string, body: any): Promise<any>;
+  create(vocabItem: string, tokens: any[], metadata?: any, auditMessage?: string): Promise<any>;
+  bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
+  bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  setMetadata(id: string, body: any, auditMessage?: string): Promise<any>;
+  deleteMetadata(id: string, auditMessage?: string): Promise<any>;
+  patchMetadata(id: string, body: any, auditMessage?: string): Promise<any>;
   get(id: string, asOf?: string): Promise<any>;
-  delete(id: string): Promise<any>;
+  delete(id: string, auditMessage?: 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>;
+  delete(id: string, auditMessage?: string): Promise<any>;
+  update(id: string, name: string, auditMessage?: string): Promise<any>;
+  setConfig(id: string, namespace: string, configKey: string, configValue: any, auditMessage?: string): Promise<any>;
+  deleteConfig(id: string, namespace: string, configKey: string, auditMessage?: 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>;
+  create(name: string, auditMessage?: string): Promise<any>;
+  addMaintainer(id: string, userId: string, auditMessage?: string): Promise<any>;
+  removeMaintainer(id: string, userId: string, auditMessage?: string): Promise<any>;
 }
 
 interface RelationsBundle {
-  setMetadata(relationId: string, body: any): Promise<any>;
-  deleteMetadata(relationId: string): Promise<any>;
-  patchMetadata(relationId: string, body: any): Promise<any>;
-  setTarget(relationId: string, spanId: string): Promise<any>;
+  setMetadata(relationId: string, body: any, auditMessage?: string): Promise<any>;
+  deleteMetadata(relationId: string, auditMessage?: string): Promise<any>;
+  patchMetadata(relationId: string, body: any, auditMessage?: string): Promise<any>;
+  setTarget(relationId: string, spanId: string, auditMessage?: 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>;
+  delete(relationId: string, auditMessage?: string): Promise<any>;
+  update(relationId: string, value: any, auditMessage?: string): Promise<any>;
+  setSource(relationId: string, spanId: string, auditMessage?: string): Promise<any>;
+  create(layerId: string, sourceId: string, targetId: string, value: any, metadata?: any, auditMessage?: string): Promise<any>;
+  bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
+  bulkDelete(body: any[], auditMessage?: string): Promise<void>;
 }
 
 interface SpanLayersBundle {
-  setConfig(spanLayerId: string, namespace: string, configKey: string, configValue: any): Promise<any>;
-  deleteConfig(spanLayerId: string, namespace: string, configKey: string): Promise<any>;
+  setConfig(spanLayerId: string, namespace: string, configKey: string, configValue: any, auditMessage?: string): Promise<any>;
+  deleteConfig(spanLayerId: string, namespace: string, configKey: string, auditMessage?: 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>;
+  delete(spanLayerId: string, auditMessage?: string): Promise<any>;
+  update(spanLayerId: string, name: string, auditMessage?: string): Promise<any>;
+  create(tokenLayerId: string, name: string, auditMessage?: string): Promise<any>;
+  shift(spanLayerId: string, direction: string, auditMessage?: string): Promise<any>;
 }
 
 interface SpansBundle {
-  setTokens(spanId: string, tokens: any[]): Promise<any>;
-  create(spanLayerId: string, tokens: any[], value: any, metadata?: any): Promise<any>;
+  setTokens(spanId: string, tokens: any[], auditMessage?: string): Promise<any>;
+  create(spanLayerId: string, tokens: any[], value: any, metadata?: any, auditMessage?: string): 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>;
-  patchMetadata(spanId: string, body: any): Promise<any>;
+  delete(spanId: string, auditMessage?: string): Promise<any>;
+  update(spanId: string, value: any, auditMessage?: string): Promise<any>;
+  bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
+  bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  setMetadata(spanId: string, body: any, auditMessage?: string): Promise<any>;
+  deleteMetadata(spanId: string, auditMessage?: string): Promise<any>;
+  patchMetadata(spanId: string, body: any, auditMessage?: string): Promise<any>;
 }
 
 interface BatchBundle {
-  submit(body: any[]): Promise<any>;
+  submit(body: any[], auditMessage?: string): Promise<any>;
 }
 
 interface TextsBundle {
-  setMetadata(textId: string, body: any): Promise<any>;
-  deleteMetadata(textId: string): Promise<any>;
-  patchMetadata(textId: string, body: any): Promise<any>;
-  create(textLayerId: string, documentId: string, body: string, metadata?: any): Promise<any>;
+  setMetadata(textId: string, body: any, auditMessage?: string): Promise<any>;
+  deleteMetadata(textId: string, auditMessage?: string): Promise<any>;
+  patchMetadata(textId: string, body: any, auditMessage?: string): Promise<any>;
+  create(textLayerId: string, documentId: string, body: string, metadata?: any, auditMessage?: string): Promise<any>;
   get(textId: string, asOf?: string): Promise<any>;
-  delete(textId: string): Promise<any>;
-  update(textId: string, body: any): Promise<any>;
+  delete(textId: string, auditMessage?: string): Promise<any>;
+  update(textId: string, body: any, auditMessage?: string): 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>;
+  create(username: string, password: string, isAdmin: boolean, auditMessage?: string): 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>;
+  delete(id: string, auditMessage?: string): Promise<any>;
+  activate(id: string, auditMessage?: string): Promise<any>;
+  update(id: string, password?: string, username?: string, isAdmin?: boolean, auditMessage?: string): 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>;
+  create(userId: string, name: string, auditMessage?: string): Promise<{ id: string; name: string; token: string }>;
+  revoke(userId: string, tokenId: string, auditMessage?: 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>;
+  shift(tokenLayerId: string, direction: string, auditMessage?: string): Promise<any>;
+  create(textLayerId: string, name: string, overlapMode?: string, parentTokenLayerId?: string, auditMessage?: string): Promise<any>;
+  setConfig(tokenLayerId: string, namespace: string, configKey: string, configValue: any, auditMessage?: string): Promise<any>;
+  deleteConfig(tokenLayerId: string, namespace: string, configKey: string, auditMessage?: string): Promise<any>;
   get(tokenLayerId: string, asOf?: string): Promise<any>;
-  delete(tokenLayerId: string): Promise<any>;
-  update(tokenLayerId: string, name: string): Promise<any>;
+  delete(tokenLayerId: string, auditMessage?: string): Promise<any>;
+  update(tokenLayerId: string, name: string, auditMessage?: string): Promise<any>;
 }
 
 interface DocumentsBundle {
   checkLock(documentId: string, asOf?: string): Promise<any>;
-  acquireLock(documentId: string): Promise<any>;
-  releaseLock(documentId: string): Promise<any>;
+  acquireLock(documentId: string, auditMessage?: string): Promise<any>;
+  releaseLock(documentId: string, auditMessage?: 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>;
-  patchMetadata(documentId: string, body: any): Promise<any>;
+  uploadMedia(documentId: string, file: File, auditMessage?: string): Promise<any>;
+  deleteMedia(documentId: string, auditMessage?: string): Promise<any>;
+  setMetadata(documentId: string, body: any, auditMessage?: string): Promise<any>;
+  deleteMetadata(documentId: string, auditMessage?: string): Promise<any>;
+  patchMetadata(documentId: string, body: any, auditMessage?: 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>;
+  delete(documentId: string, auditMessage?: string): Promise<any>;
+  update(documentId: string, name: string, auditMessage?: string): Promise<any>;
+  create(projectId: string, name: string, metadata?: any, auditMessage?: string): Promise<any>;
 }
 
 interface MessagesBundle {
-  sendMessage(projectId: string, data: any): Promise<any>;
+  sendMessage(projectId: string, data: any, auditMessage?: string): 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[]>;
+  /** Discover the services seen on a project: online ones plus previously-seen offline ones (check `online`). */
+  discoverServices(projectId: string): Promise<DiscoveredService[]>;
+  /** Forget a previously-seen (offline) service. Maintainer-only; 409 if currently connected. */
+  discardService(projectId: string, serviceId: string): Promise<void>;
   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>;
+  addWriter(id: string, userId: string, auditMessage?: string): Promise<any>;
+  removeWriter(id: string, userId: string, auditMessage?: string): Promise<any>;
+  addReader(id: string, userId: string, auditMessage?: string): Promise<any>;
+  removeReader(id: string, userId: string, auditMessage?: string): Promise<any>;
+  setConfig(id: string, namespace: string, configKey: string, configValue: any, auditMessage?: string): Promise<any>;
+  deleteConfig(id: string, namespace: string, configKey: string, auditMessage?: string): Promise<any>;
+  addMaintainer(id: string, userId: string, auditMessage?: string): Promise<any>;
+  removeMaintainer(id: string, userId: string, auditMessage?: 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>;
+  linkVocab(id: string, vocabId: string, auditMessage?: string): Promise<any>;
+  unlinkVocab(id: string, vocabId: string, auditMessage?: 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>;
+  delete(id: string, auditMessage?: string): Promise<any>;
+  update(id: string, name: string, auditMessage?: 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>;
+  create(name: string, auditMessage?: 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>;
+  setConfig(textLayerId: string, namespace: string, configKey: string, configValue: any, auditMessage?: string): Promise<any>;
+  deleteConfig(textLayerId: string, namespace: string, configKey: string, auditMessage?: 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>;
+  delete(textLayerId: string, auditMessage?: string): Promise<any>;
+  update(textLayerId: string, name: string, auditMessage?: string): Promise<any>;
+  shift(textLayerId: string, direction: string, auditMessage?: string): Promise<any>;
+  create(projectId: string, name: string, auditMessage?: string): Promise<any>;
 }
 
 interface VocabItemsBundle {
-  setMetadata(id: string, body: any): Promise<any>;
-  deleteMetadata(id: string): Promise<any>;
-  patchMetadata(id: string, body: any): Promise<any>;
-  create(vocabLayerId: string, form: string, metadata?: any): Promise<any>;
+  setMetadata(id: string, body: any, auditMessage?: string): Promise<any>;
+  deleteMetadata(id: string, auditMessage?: string): Promise<any>;
+  patchMetadata(id: string, body: any, auditMessage?: string): Promise<any>;
+  create(vocabLayerId: string, form: string, metadata?: any, auditMessage?: string): Promise<any>;
+  bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
+  bulkDelete(body: any[], auditMessage?: string): Promise<void>;
   get(id: string, asOf?: string): Promise<any>;
-  delete(id: string): Promise<any>;
-  update(id: string, form: string): Promise<any>;
+  delete(id: string, auditMessage?: string): Promise<any>;
+  update(id: string, form: string, auditMessage?: 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>;
+  shift(relationLayerId: string, direction: string, auditMessage?: string): Promise<any>;
+  create(spanLayerId: string, name: string, auditMessage?: string): Promise<any>;
+  setConfig(relationLayerId: string, namespace: string, configKey: string, configValue: any, auditMessage?: string): Promise<any>;
+  deleteConfig(relationLayerId: string, namespace: string, configKey: string, auditMessage?: string): Promise<any>;
   get(relationLayerId: string, asOf?: string): Promise<any>;
-  delete(relationLayerId: string): Promise<any>;
-  update(relationLayerId: string, name: string): Promise<any>;
+  delete(relationLayerId: string, auditMessage?: string): Promise<any>;
+  update(relationLayerId: string, name: string, auditMessage?: string): Promise<any>;
 }
 
 interface TokensBundle {
-  create(tokenLayerId: string, text: string, begin: number, end: number, precedence?: number | null, metadata?: any): Promise<any>;
+  create(tokenLayerId: string, text: string, begin: number, end: number, precedence?: number | null, metadata?: any, auditMessage?: string): 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>;
-  patchMetadata(tokenId: string, body: any): Promise<any>;
+  delete(tokenId: string, auditMessage?: string): Promise<any>;
+  update(tokenId: string, begin?: number, end?: number, precedence?: number | null, auditMessage?: string): Promise<any>;
+  bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
+  bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  split(tokenId: string, position: number, auditMessage?: string): Promise<any>;
+  merge(tokenId: string, otherTokenId: string, auditMessage?: string): Promise<any>;
+  shift(tokenId: string, begin?: number, end?: number, auditMessage?: string): Promise<any>;
+  setMetadata(tokenId: string, body: any, auditMessage?: string): Promise<any>;
+  deleteMetadata(tokenId: string, auditMessage?: string): Promise<any>;
+  patchMetadata(tokenId: string, body: any, auditMessage?: string): Promise<any>;
 }
 
 interface PlaidClientOptions {
   /** Per-request timeout in ms (default 30000; 0 or null disables it). */
   timeout?: number | null;
+  /**
+   * Fired once when a request returns HTTP 401 (missing/expired/invalid token).
+   * Use it to discard the stored token and route back to login. 403 (forbidden)
+   * does NOT trigger it.
+   */
+  onAuthError?: ((error: Error) => void) | 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;
+  /** Fired once on HTTP 401 (see PlaidClientOptions.onAuthError). */
+  onAuthError: ((error: Error) => void) | null;
 
   // Batch control methods
   beginBatch(): void;
   submitBatch(): Promise<any[]>;
   abortBatch(): void;
   isBatchMode(): boolean;
+  /** Run `fn` with a batch open, then submit atomically (or abort if `fn` throws). Resolves to the results array. */
+  batched(fn: () => void | Promise<void>): Promise<any[]>;
 
   // Strict mode methods
   enterStrictMode(documentId: string): void;
   exitStrictMode(): void;
 
+  // Custom audit-log message (overrides the auto-generated description; may
+  // template the endpoint's path/query/body params with {param} placeholders).
+  auditMessage: string | null;
+  setAuditMessage(message: string): this;
+  clearAuditMessage(): this;
+  withAuditMessage<T>(message: string, fn: () => Promise<T> | T): Promise<T>;
+
   // Query
-  query(body: any): Promise<any>;
+  query(body: any, auditMessage?: string): Promise<any>;
 
   vocabLinks: VocabLinksBundle;
   vocabLayers: VocabLayersBundle;
@@ -377,3 +405,46 @@ export function getServiceSummary(service: DiscoveredService): string;
 export function buildDefaultValues(schema: ServiceParam[]): Record<string, any>;
 /** Coerce/validate raw form values against the schema. */
 export function coerceParamValues(schema: ServiceParam[], raw: Record<string, any>): { values: Record<string, any>; errors: Record<string, string> };
+
+// --- Provenance ---------------------------------------------------------------
+// Cross-app convention for machine-provided vs human-labeled information,
+// expressed as flat metadata keys on annotation entities. Absent keys = human;
+// { prov: 'inferred', provSource } = machine-made, unverified;
+// + { provConfirmed: true } = machine-made, human-verified. Machine writers may
+// replace unverified machine material but must never touch human/verified
+// material without an explicit overwrite opt-in; any human edit verifies.
+// See the manual, "Provenance".
+type ProvState = 'human' | 'machine' | 'verified';
+export const PROV: {
+  readonly key: 'prov';
+  readonly sourceKey: 'provSource';
+  readonly confirmedKey: 'provConfirmed';
+  readonly probKey: 'provProb';
+  readonly detailKey: 'provDetail';
+  readonly INFERRED: 'inferred';
+};
+export const PROV_STATES: {
+  readonly HUMAN: 'human';
+  readonly MACHINE: 'machine';
+  readonly VERIFIED: 'verified';
+};
+/** Optional prediction extras: prob = a probability in [0,1] for the chosen value
+ * (flat + queryable; omit unless it honestly is one); detail = an open map of
+ * producer extras (top-k alternatives, model version, raw scores; keep it small).
+ * Both describe the ORIGINAL prediction — check provConfirmed before presenting
+ * provProb as confidence in the current value. */
+interface ProvExtras { prob?: number; detail?: Record<string, any> }
+/** The metadata fragment a machine writer merges into everything it creates. */
+export function stampInferred(source: string, extras?: ProvExtras):
+  { prov: 'inferred'; provSource: string; provProb?: number; provDetail?: Record<string, any> };
+/** stampInferred + provConfirmed — for machine material born verified (e.g. imports with upstream approval). */
+export function confirmedInferred(source: string, extras?: ProvExtras):
+  { prov: 'inferred'; provSource: string; provConfirmed: true; provProb?: number; provDetail?: Record<string, any> };
+/** Classify an entity's metadata into one of the three provenance states. */
+export function provState(metadata: object | null | undefined): ProvState;
+/** Whether a machine writer must leave this entity alone (human or verified). */
+export function isProtected(metadata: object | null | undefined): boolean;
+/** The fragment a HUMAN edit should merge in: { provConfirmed: true } iff machine-unverified, else null. */
+export function verifyOnEdit(metadata: object | null | undefined): { provConfirmed: true } | null;
+/** Canonical provSource for a service: 'service:<serviceId>'. */
+export function serviceSource(serviceId: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larc-iu/plaid-client",
-  "version": "0.1.0-alpha.9",
+  "version": "0.2.0-alpha.0",
   "description": "JavaScript client for the Plaid annotation API",
   "type": "module",
   "repository": {

package/src/http.js

@@ -94,6 +94,9 @@ export function timeoutSignal(timeout) {
  *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
  *   noAuth          - Skip Authorization header
  *   binaryResponse  - Return arrayBuffer instead of JSON/text
+ *   timeout         - Per-request timeout in ms overriding client.timeout
+ *                     for this call (0/null disables). Used for known-long
+ *                     ops like project delete.
  */
 export async function makeRequest(client, method, path, options = {}) {
   const {
@@ -105,6 +108,8 @@ export async function makeRequest(client, method, path, options = {}) {
     skipResponseTransform,
     noAuth,
     binaryResponse,
+    auditMessage,
+    timeout,
   } = options;
 
   // Build URL
@@ -135,16 +140,35 @@ export async function makeRequest(client, method, path, options = {}) {
     requestBody = transformRequest(body);
   }
 
-  // Strict mode: append document-version for non-GET requests
-  if (client.strictModeDocumentId && method !== 'GET') {
+  // Strict mode: append document-version for non-GET requests.
+  // Inside a batch, stamp ONLY the first write: batches run atomically
+  // server-side, so a version check on the first op gives whole-batch OCC
+  // semantics, while stamping every op would 409 the second op against the
+  // version bump the first op itself caused (every queued op captures the
+  // same pre-batch version).
+  if (client.strictModeDocumentId && method !== 'GET'
+      && !(client.isBatching && client.batchVersionStamped)) {
     const docId = client.strictModeDocumentId;
     if (client.documentVersions[docId]) {
       const docVersion = client.documentVersions[docId];
       const separator = url.includes('?') ? '&' : '?';
       url += `${separator}document-version=${encodeURIComponent(docVersion)}`;
+      if (client.isBatching) client.batchVersionStamped = true;
     }
   }
 
+  // Custom audit-log message (overrides the auto-generated description).
+  // Per-call `auditMessage` option wins, else the ambient `client.auditMessage`
+  // (see setAuditMessage/withAuditMessage). Unlike document-version this has no
+  // OCC self-conflict, so it is stamped on EVERY queued batch op, not just the
+  // first. The server templates `{param}` placeholders against the endpoint's
+  // own path/query/body params.
+  const effectiveAuditMessage = auditMessage !== undefined ? auditMessage : client.auditMessage;
+  if (effectiveAuditMessage && method !== 'GET') {
+    const separator = url.includes('?') ? '&' : '?';
+    url += `${separator}audit-message=${encodeURIComponent(effectiveAuditMessage)}`;
+  }
+
   // Batch mode
   if (client.isBatching) {
     if (noBatch) {
@@ -174,14 +198,22 @@ export async function makeRequest(client, method, path, options = {}) {
   if (requestBody !== undefined) {
     fetchOptions.body = formData ? requestBody : JSON.stringify(requestBody);
   }
-  const signal = timeoutSignal(client.timeout);
+  const signal = timeoutSignal(timeout !== undefined ? timeout : 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);
+      const error = makeHttpError(response, await parseErrorBody(response), url, method);
+      // 401 means the token is missing/expired/invalid. Fire the app's auth-error
+      // handler once (it discards the token and routes back to login). 403
+      // (forbidden — authenticated but not permitted) deliberately does NOT.
+      if (response.status === 401 && typeof client.onAuthError === 'function' && !client._authErrorFired) {
+        client._authErrorFired = true;
+        try { client.onAuthError(error); } catch (_) { /* handler must not mask the original error */ }
+      }
+      throw error;
     }
 
     // Binary response (getMedia)