@larc-iu/plaid-client 0.2.0-alpha.11 → 0.2.0-alpha.13

package/index.d.ts

@@ -25,6 +25,8 @@ interface ServiceParam {
   min?: number;
   max?: number;
   step?: number;
+  /** `number` only: render as a slider to drag rather than a box to type in. */
+  slider?: boolean;
   /** `string` only. */
   placeholder?: string;
   multiline?: boolean;
@@ -70,14 +72,41 @@ interface ServiceRegistration {
 }
 
 /** Connection-state transitions reported by a service registration. */
-type ServiceStatusEvent = 'registered' | 'reconnected' | 'disconnected';
+type ServiceStatusEvent = "registered" | "reconnected" | "disconnected";
 
 interface ResponseHelper {
-  progress(percent: number, message: string): void;
+  requestId: string;
+  requesterId: string | null;
+  /** True once the requester has asked this request to stop. */
+  readonly cancelled: boolean;
+  /**
+   * Report progress — and a cancellation CHECKPOINT: throws
+   * `ServiceCancelled` once a stop has been asked for, which is what makes a
+   * service that already reports progress cancellable for free.
+   */
+  progress(percent: number, message: string, extra?: Record<string, any>): void;
+  /** Stop here if the requester has asked the request to stop. */
+  raiseIfCancelled(): void;
+  /** Run `fn` as a stretch that must finish once begun, usually the writes. */
+  critical<T>(fn: () => T | Promise<T>): Promise<T>;
   complete(data: any): void;
+  /** End the request because it was asked to stop; result carries `stopped: true`. */
+  stopped(data?: any): void;
   error(error: string | Error): void;
 }
 
+/** Thrown inside a handler when the requester has asked it to stop. */
+export class ServiceCancelled extends Error {
+  constructor(message?: string);
+}
+
+/** The cancellation half of a responseHelper, on its own. */
+export function createCancelScope(isCancelled: () => boolean): {
+  readonly cancelled: boolean;
+  raiseIfCancelled(): void;
+  critical<T>(fn: () => T | Promise<T>): Promise<T>;
+};
+
 interface SSEConnection {
   close(): void;
   getStats(): any;
@@ -267,6 +296,7 @@ interface UsersBundle {
     endTime?: string,
     asOf?: string,
   ): Promise<any[]>;
+  auditPage(userId: string, opts?: AuditPageOptions): Promise<Page>;
   get(id: string, asOf?: string): Promise<any>;
   delete(id: string, auditMessage?: string): Promise<any>;
   activate(id: string, auditMessage?: string): Promise<any>;
@@ -313,12 +343,7 @@ interface CommentFilters {
 
 /** Entities that can carry a comment. */
 type CommentableType =
-  | "document"
-  | "text"
-  | "token"
-  | "span"
-  | "relation"
-  | "vocab-item";
+  "document" | "text" | "token" | "span" | "relation" | "vocab-item";
 
 interface Comment {
   id: string;
@@ -446,15 +471,182 @@ interface CreateInviteOptions {
   note?: string;
 }
 
+/** Server limits, as reported by /api/v1/info. An unset limit is absent. */
+interface ServerLimits {
+  mediaFileBytes?: number;
+  jsonBodyBytes?: number;
+  batchOperations?: number;
+  metadataDepth?: number;
+  metadataKeyCount?: number;
+  metadataStringLength?: number;
+  metadataTotalBytes?: number;
+  userDataValueBytes?: number;
+}
+
+interface ServerHealth {
+  ok: boolean;
+  version: string;
+  uptimeMs: number;
+  audit: { dbSizeMb?: number; auditRows?: number; error?: string };
+}
+
+interface DocumentLock {
+  documentId: string;
+  userId: string;
+  expiresAt: number;
+}
+
+interface RateLimitBucket {
+  ip: string;
+  userId?: string;
+  failures: number;
+  limit: number;
+  blocked: boolean;
+}
+
+interface RateLimitSnapshot {
+  windowMs: number;
+  logins: RateLimitBucket[];
+  ips: RateLimitBucket[];
+  invites: RateLimitBucket[];
+}
+
+interface BackupStatus {
+  enabled: boolean;
+  directory: string;
+  retention: number;
+  time: string;
+  backups: Array<{ name: string; bytes: number; modified: string }>;
+  ok?: boolean;
+}
+
+interface ServerReport {
+  version: string;
+  jvm: {
+    uptimeMs: number;
+    startedAt: string;
+    java: string;
+    heapUsed: number;
+    heapMax: number;
+  };
+  database: {
+    path: string | null;
+    bytes: number | null;
+    walBytes: number | null;
+    slowQueryThresholdMs?: number;
+    journalMode?: string;
+    maxPoolSize?: number;
+    tables: Record<string, number | null>;
+  };
+  media: {
+    directory: string;
+    files: number;
+    bytes: number;
+    orphans: number;
+    orphanBytes: number;
+  };
+  backup: BackupStatus;
+  settings: Record<string, any>;
+}
+
+/** Server-level facts. `info` is fetched at most once per client. */
+interface ServerBundle {
+  info(): Promise<{ limits: ServerLimits }>;
+  limits(): Promise<ServerLimits>;
+  health(): Promise<ServerHealth>;
+}
+
+/** Instance-wide operations. Every method requires a global admin. */
+interface AdminBundle {
+  server(): Promise<ServerReport>;
+  backup(): Promise<BackupStatus>;
+  locks(): Promise<{ entries: DocumentLock[] }>;
+  releaseLock(documentId: string): Promise<{ result: string }>;
+  rateLimits(): Promise<RateLimitSnapshot>;
+  clearRateLimits(opts?: {
+    ip?: string;
+    userId?: string;
+  }): Promise<{ result: string }>;
+  logs(opts?: {
+    lines?: number;
+  }): Promise<{ file: string | null; lines: string[]; error?: string }>;
+  userData(opts?: AdminUserDataOptions): Promise<AdminUserDataEntry[]>;
+  userDataPage(
+    opts?: AdminUserDataOptions & { limit?: number; cursor?: string },
+  ): Promise<Page<AdminUserDataEntry>>;
+}
+
+/** Narrowings for the cross-account private-data listing. */
+interface AdminUserDataOptions {
+  /** Only keys starting with this literal head. */
+  prefix?: string;
+  /** Only keys matching this GLOB (`*` any run, `?` one character). */
+  pattern?: string;
+  includeValues?: boolean;
+}
+
+type AdminUserDataEntry = UserDataEntry & { userId: string };
+
+/** Options for a single page of any audit log. */
+interface AuditPageOptions {
+  startTime?: string;
+  endTime?: string;
+  asOf?: string;
+  opTypes?: string[] | string;
+  /** "desc" pages newest-first; a cursor belongs to the direction that made it. */
+  order?: "asc" | "desc";
+  limit?: number;
+  cursor?: string;
+}
+
+/** One user's activity over a scope and window. */
+interface ActivityTallyRow {
+  user: { id: string; displayName?: string };
+  operations: number;
+  changes: number;
+  documents: number;
+  firstTs: string;
+  lastTs: string;
+  byDay?: Array<{ date: string; changes: number }>;
+}
+
+/** Instance-wide audit reads and the per-user aggregate. */
+interface AuditBundle {
+  /** Admin only. */
+  list(opts?: {
+    startTime?: string;
+    endTime?: string;
+    opTypes?: string[] | string;
+  }): Promise<any[]>;
+  /** Admin only. */
+  listPage(opts?: AuditPageOptions): Promise<Page>;
+  /** Admin only. */
+  iterPages(opts?: {
+    startTime?: string;
+    endTime?: string;
+    opTypes?: string[] | string;
+    pageSize?: number;
+  }): AsyncGenerator<any[]>;
+  /** With projectId, open to that project's maintainers; without one, admin only. */
+  tally(opts?: {
+    projectId?: string;
+    startTime?: string;
+    endTime?: string;
+    daily?: boolean;
+  }): Promise<ActivityTallyRow[]>;
+}
+
 interface InvitesBundle {
-  list(opts?: { projectId?: string }): Promise<Invite[]>;
+  list(opts?: { projectId?: string; all?: boolean }): Promise<Invite[]>;
   listPage(opts?: {
     projectId?: string;
+    all?: boolean;
     limit?: number;
     cursor?: string;
   }): Promise<Page>;
   iterPages(opts?: {
     projectId?: string;
+    all?: boolean;
     pageSize?: number;
   }): AsyncGenerator<Invite[]>;
   /** The `code` is returned ONCE and is not recoverable afterward. */
@@ -532,6 +724,7 @@ interface DocumentsBundle {
     endTime?: string,
     asOf?: string,
   ): Promise<any[]>;
+  auditPage(documentId: string, opts?: AuditPageOptions): Promise<Page>;
   get(documentId: string, includeBody?: boolean, asOf?: string): Promise<any>;
   delete(documentId: string, auditMessage?: string): Promise<any>;
   update(documentId: string, name: string, auditMessage?: string): Promise<any>;
@@ -541,6 +734,19 @@ interface DocumentsBundle {
     metadata?: any,
     auditMessage?: string,
   ): Promise<any>;
+  /** Copy a document and everything in it into a new document of the same project. */
+  copy(
+    documentId: string,
+    name: string,
+    options?: { includeMedia?: boolean },
+    auditMessage?: string,
+  ): Promise<{ id: string; mediaError?: string }>;
+  restore(
+    documentId: string,
+    asOf: string,
+    options?: { dryRun?: boolean },
+    auditMessage?: string,
+  ): Promise<any>;
 }
 
 interface MessagesBundle {
@@ -567,7 +773,11 @@ interface MessagesBundle {
     serviceInfo: ServiceInfo,
     onServiceRequest: (data: any, responseHelper: ResponseHelper) => void,
     extras?: any,
-    onStatus?: (event: ServiceStatusEvent, projectId: string, detail?: string) => void,
+    onStatus?: (
+      event: ServiceStatusEvent,
+      projectId: string,
+      detail?: string,
+    ) => void,
   ): ServiceRegistration;
   /**
    * Submit work to a service; streams progress to `onProgress`, resolves with
@@ -618,6 +828,7 @@ interface ProjectsBundle {
     endTime?: string,
     asOf?: string,
   ): Promise<any[]>;
+  auditPage(projectId: string, opts?: AuditPageOptions): Promise<Page>;
   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>;
@@ -852,6 +1063,9 @@ export declare class PlaidClient {
   apiTokens: ApiTokensBundle;
   userData: UserDataBundle;
   invites: InvitesBundle;
+  server: ServerBundle;
+  admin: AdminBundle;
+  audit: AuditBundle;
   comments: CommentsBundle;
   tokenLayers: TokenLayersBundle;
   documents: DocumentsBundle;
@@ -919,6 +1133,9 @@ export const TASKS: {
   readonly TRANSCRIBE: "transcribe";
   readonly LINK_VOCAB: "link-vocab";
   readonly ANALYZE: "analyze";
+  readonly TRANSLATE: "translate";
+  readonly ASSIST: "assist";
+  readonly DETECT_SPEECH: "detect-speech";
 };
 /** Whether a service serves a task (declared `extras.tasks`, legacy id-prefix fallback). */
 export function servesTask(service: DiscoveredService, task: string): boolean;

package/package.json

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