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

package/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * A config write's compare-and-set. With `expected` present (null or
+ * undefined for a key that was absent) the write is refused with a 409 when
+ * the stored value is no longer `expected`.
+ */
+interface ConfigWriteOptions {
+  expected?: any;
+}
+
 /** A single page of a cursor-paginated collection. */
 interface Page<T = any> {
   entries: T[];
@@ -150,6 +159,7 @@ interface VocabLinksBundle {
     tokens: any[],
     metadata?: any,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
@@ -184,6 +194,7 @@ interface VocabLayersBundle {
     endTime?: string,
     opTypes?: string[] | string,
     itemId?: string,
+    kinds?: OperationKind[] | string,
   ): Promise<any[]>;
   auditPage(id: string, opts?: AuditPageOptions & { itemId?: string }): Promise<Page>;
   /** Put one entry back as it was at `asOf`. Maintainers of the vocabulary only. */
@@ -202,17 +213,19 @@ interface VocabLayersBundle {
     configKey: string,
     configValue: any,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   deleteConfig(
     id: string,
     namespace: string,
     configKey: string,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   list(): Promise<any[]>;
   listPage(opts?: { limit?: number; cursor?: string }): Promise<Page>;
   iterPages(opts?: { pageSize?: number }): AsyncGenerator<any[]>;
-  create(name: string, auditMessage?: string): Promise<any>;
+  create(name: string, auditMessage?: string, opts?: { id?: string }): Promise<any>;
   addMaintainer(
     id: string,
     userId: string,
@@ -257,6 +270,7 @@ interface RelationsBundle {
     value: any,
     metadata?: any,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
@@ -270,12 +284,14 @@ interface SpanLayersBundle {
     configKey: string,
     configValue: any,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   deleteConfig(
     spanLayerId: string,
     namespace: string,
     configKey: string,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   get(spanLayerId: string): Promise<any>;
   delete(spanLayerId: string, auditMessage?: string): Promise<any>;
@@ -288,12 +304,41 @@ interface SpanLayersBundle {
     tokenLayerId: string,
     name: string,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   shift(
     spanLayerId: string,
     direction: string,
     auditMessage?: string,
   ): Promise<any>;
+  setConstraints(
+    layerId: string,
+    namespace: string,
+    constraints: LayerConstraint[],
+    auditMessage?: string,
+    options?: ConstraintWriteOptions,
+  ): Promise<{ constraints: Record<string, LayerConstraint[]> }>;
+  deleteConstraints(
+    layerId: string,
+    namespace: string,
+    auditMessage?: string,
+    options?: ConstraintWriteOptions,
+  ): Promise<any>;
+  checkConstraints(
+    layerId: string,
+    constraints: LayerConstraint[],
+  ): Promise<{ violations: ConstraintViolation[]; violationCount: number }>;
+  repairConstraints(
+    layerId: string,
+    constraints: LayerConstraint[],
+    auditMessage?: string,
+    options?: { document?: string },
+  ): Promise<{
+    repaired: { document: string; constraint: string; deleted: number; joined: number }[];
+    locked: { document: string; lockedBy: string }[];
+    violations: ConstraintViolation[];
+    violationCount: number;
+  }>;
 }
 
 interface SpansBundle {
@@ -304,6 +349,7 @@ interface SpansBundle {
     value: any,
     metadata?: any,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   get(spanId: string): Promise<any>;
   delete(spanId: string, auditMessage?: string): Promise<any>;
@@ -326,10 +372,14 @@ interface TextsBundle {
     body: string,
     metadata?: any,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   get(textId: string): Promise<any>;
   delete(textId: string, auditMessage?: string): Promise<any>;
-  update(textId: string, body: any, auditMessage?: string): Promise<any>;
+  /** With `base` (a text's `digest`) the update applies only to that body. */
+  update(textId: string, body: any, auditMessage?: string, opts?: { base?: string; versioned?: boolean }): Promise<any>;
+  /** Edits made at the caret; with `base` they apply only to that body. Answers the text with `digest` and `reshape`. */
+  edit(textId: string, edits: TextEditOp[], auditMessage?: string, opts?: { base?: string; versioned?: boolean }): Promise<any>;
 }
 
 interface UsersBundle {
@@ -349,6 +399,7 @@ interface UsersBundle {
     startTime?: string,
     endTime?: string,
     opTypes?: string[] | string,
+    kinds?: OperationKind[] | string,
   ): Promise<any[]>;
   auditPage(userId: string, opts?: AuditPageOptions): Promise<Page>;
   get(id: string): Promise<any>;
@@ -437,7 +488,7 @@ interface GuidelinesBundle {
   create(
     projectId: string,
     title: string,
-    opts?: { body?: string; pinned?: boolean },
+    opts?: { body?: string; pinned?: boolean; id?: string },
     auditMessage?: string,
   ): Promise<{ id: string }>;
   get(id: string): Promise<Guideline>;
@@ -555,7 +606,7 @@ interface CommentsBundle {
     entityType: CommentableType,
     entityId: string,
     body: string,
-    opts?: { anchorLabel?: string },
+    opts?: { anchorLabel?: string; id?: string },
   ): Promise<Comment>;
   get(id: string): Promise<Comment>;
   update(id: string, body: string): Promise<Comment>;
@@ -866,6 +917,8 @@ interface AuditPageOptions {
   startTime?: string;
   endTime?: string;
   opTypes?: string[] | string;
+  /** Only the entries of operations of these kinds, each whole. */
+  kinds?: OperationKind[] | string;
   /** "desc" pages newest-first; a cursor belongs to the direction that made it. */
   order?: "asc" | "desc";
   limit?: number;
@@ -890,6 +943,7 @@ interface AuditBundle {
     startTime?: string;
     endTime?: string;
     opTypes?: string[] | string;
+    kinds?: OperationKind[] | string;
   }): Promise<any[]>;
   /** Admin only. */
   listPage(opts?: AuditPageOptions): Promise<Page>;
@@ -898,6 +952,7 @@ interface AuditBundle {
     startTime?: string;
     endTime?: string;
     opTypes?: string[] | string;
+    kinds?: OperationKind[] | string;
     pageSize?: number;
   }): AsyncGenerator<any[]>;
   /** With projectId, open to that project's maintainers; without one, admin only. */
@@ -942,6 +997,7 @@ interface TokenLayersBundle {
     overlapMode?: string,
     parentTokenLayerId?: string,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   setConfig(
     tokenLayerId: string,
@@ -949,12 +1005,14 @@ interface TokenLayersBundle {
     configKey: string,
     configValue: any,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   deleteConfig(
     tokenLayerId: string,
     namespace: string,
     configKey: string,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   get(tokenLayerId: string): Promise<any>;
   delete(tokenLayerId: string, auditMessage?: string): Promise<any>;
@@ -963,6 +1021,34 @@ interface TokenLayersBundle {
     name: string,
     auditMessage?: string,
   ): Promise<any>;
+  setConstraints(
+    layerId: string,
+    namespace: string,
+    constraints: LayerConstraint[],
+    auditMessage?: string,
+    options?: ConstraintWriteOptions,
+  ): Promise<{ constraints: Record<string, LayerConstraint[]> }>;
+  deleteConstraints(
+    layerId: string,
+    namespace: string,
+    auditMessage?: string,
+    options?: ConstraintWriteOptions,
+  ): Promise<any>;
+  checkConstraints(
+    layerId: string,
+    constraints: LayerConstraint[],
+  ): Promise<{ violations: ConstraintViolation[]; violationCount: number }>;
+  repairConstraints(
+    layerId: string,
+    constraints: LayerConstraint[],
+    auditMessage?: string,
+    options?: { document?: string },
+  ): Promise<{
+    repaired: { document: string; constraint: string; deleted: number; joined: number }[];
+    locked: { document: string; lockedBy: string }[];
+    violations: ConstraintViolation[];
+    violationCount: number;
+  }>;
 }
 
 /** Handle passed to a `documents.locked()` block. */
@@ -988,8 +1074,16 @@ export const DOCUMENT_LOCK_TTL_MS: 60000;
 
 interface DocumentsBundle {
   checkLock(documentId: string): Promise<any>;
-  /** Take the lock as a new holder. The answer's `lockId` names it. */
-  acquireLock(documentId: string, auditMessage?: string): Promise<any>;
+  /**
+   * Take the lock as a new holder. The answer's `lockId` names it:
+   * `newLockId` when the client minted one, which makes a retried acquire
+   * idempotent and a lost answer releasable.
+   */
+  acquireLock(
+    documentId: string,
+    auditMessage?: string,
+    newLockId?: string,
+  ): Promise<any>;
   /** Renew `lockId`'s lock while it is live. 423 once it has lapsed. */
   renewLock(
     documentId: string,
@@ -1038,6 +1132,7 @@ interface DocumentsBundle {
     startTime?: string,
     endTime?: string,
     opTypes?: string[] | string,
+    kinds?: OperationKind[] | string,
   ): Promise<any[]>;
   auditPage(documentId: string, opts?: AuditPageOptions): Promise<Page>;
   /**
@@ -1057,12 +1152,13 @@ interface DocumentsBundle {
     name: string,
     metadata?: any,
     auditMessage?: string,
+    opts?: { id?: 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 },
+    options?: { includeMedia?: boolean; id?: string },
     auditMessage?: string,
   ): Promise<{ id: string; mediaError?: string }>;
   restore(
@@ -1154,12 +1250,14 @@ interface ProjectsBundle {
     configKey: string,
     configValue: any,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   deleteConfig(
     id: string,
     namespace: string,
     configKey: string,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   addMaintainer(
     id: string,
@@ -1176,6 +1274,7 @@ interface ProjectsBundle {
     startTime?: string,
     endTime?: string,
     opTypes?: string[] | string,
+    kinds?: OperationKind[] | string,
   ): Promise<any[]>;
   auditPage(projectId: string, opts?: AuditPageOptions): Promise<Page>;
   /**
@@ -1206,7 +1305,7 @@ interface ProjectsBundle {
   list(): Promise<any[]>;
   listPage(opts?: { limit?: number; cursor?: string }): Promise<Page>;
   iterPages(opts?: { pageSize?: number }): AsyncGenerator<any[]>;
-  create(name: string, auditMessage?: string): Promise<any>;
+  create(name: string, auditMessage?: string, opts?: { id?: string }): Promise<any>;
 }
 
 interface TextLayersBundle {
@@ -1216,12 +1315,14 @@ interface TextLayersBundle {
     configKey: string,
     configValue: any,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   deleteConfig(
     textLayerId: string,
     namespace: string,
     configKey: string,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   get(textLayerId: string): Promise<any>;
   delete(textLayerId: string, auditMessage?: string): Promise<any>;
@@ -1235,7 +1336,7 @@ interface TextLayersBundle {
     direction: string,
     auditMessage?: string,
   ): Promise<any>;
-  create(projectId: string, name: string, auditMessage?: string): Promise<any>;
+  create(projectId: string, name: string, auditMessage?: string, opts?: { id?: string }): Promise<any>;
 }
 
 interface VocabItemsBundle {
@@ -1247,12 +1348,22 @@ interface VocabItemsBundle {
     form: string,
     metadata?: any,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
   bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
   get(id: string): Promise<any>;
-  delete(id: string, auditMessage?: string): Promise<any>;
+  delete(
+    id: string,
+    auditMessage?: string,
+    options?: { expectedLinkCount?: number },
+  ): Promise<any>;
+  merge(
+    survivorId: string,
+    loserIds: string[],
+    auditMessage?: string,
+  ): Promise<{ moved: number; duplicates: number; removed: string[] }>;
   update(id: string, form: string, auditMessage?: string): Promise<any>;
 }
 
@@ -1266,6 +1377,7 @@ interface RelationLayersBundle {
     spanLayerId: string,
     name: string,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   setConfig(
     relationLayerId: string,
@@ -1273,12 +1385,14 @@ interface RelationLayersBundle {
     configKey: string,
     configValue: any,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   deleteConfig(
     relationLayerId: string,
     namespace: string,
     configKey: string,
     auditMessage?: string,
+    options?: ConfigWriteOptions,
   ): Promise<any>;
   get(relationLayerId: string): Promise<any>;
   delete(relationLayerId: string, auditMessage?: string): Promise<any>;
@@ -1287,6 +1401,34 @@ interface RelationLayersBundle {
     name: string,
     auditMessage?: string,
   ): Promise<any>;
+  setConstraints(
+    layerId: string,
+    namespace: string,
+    constraints: LayerConstraint[],
+    auditMessage?: string,
+    options?: ConstraintWriteOptions,
+  ): Promise<{ constraints: Record<string, LayerConstraint[]> }>;
+  deleteConstraints(
+    layerId: string,
+    namespace: string,
+    auditMessage?: string,
+    options?: ConstraintWriteOptions,
+  ): Promise<any>;
+  checkConstraints(
+    layerId: string,
+    constraints: LayerConstraint[],
+  ): Promise<{ violations: ConstraintViolation[]; violationCount: number }>;
+  repairConstraints(
+    layerId: string,
+    constraints: LayerConstraint[],
+    auditMessage?: string,
+    options?: { document?: string },
+  ): Promise<{
+    repaired: { document: string; constraint: string; deleted: number; joined: number }[];
+    locked: { document: string; lockedBy: string }[];
+    violations: ConstraintViolation[];
+    violationCount: number;
+  }>;
 }
 
 interface TokensBundle {
@@ -1298,6 +1440,7 @@ interface TokensBundle {
     precedence?: number | null,
     metadata?: any,
     auditMessage?: string,
+    opts?: { id?: string },
   ): Promise<any>;
   get(tokenId: string): Promise<any>;
   delete(tokenId: string, auditMessage?: string): Promise<any>;
@@ -1311,7 +1454,12 @@ interface TokensBundle {
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
   bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
-  split(tokenId: string, position: number, auditMessage?: string): Promise<any>;
+  split(
+    tokenId: string,
+    position: number,
+    auditMessage?: string,
+    options?: { id?: string },
+  ): Promise<any>;
   merge(
     tokenId: string,
     otherTokenId: string,
@@ -1342,6 +1490,11 @@ interface PlaidClientOptions {
    * write lock. Defaults to `timeout` when that is given and this is not.
    */
   batchTimeout?: number | null;
+  /**
+   * Delays in ms before sending a keyed write again when its answer was lost
+   * (no response, 502 or 504). Default [1000, 3000, 9000].
+   */
+  retryDelaysMs?: number[];
   /**
    * 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)
@@ -1357,7 +1510,8 @@ export type OperationKind =
   | 'import'
   | 'bulk-edit'
   | 'guess-adoption'
-  | 'repair';
+  | 'repair'
+  | 'review';
 
 export interface OperationGroupsBundle {
   get(id: string): Promise<any>;
@@ -1384,6 +1538,27 @@ export interface PlaidBatch extends PlaidClient {
   submit(): Promise<any[]>;
   /** Drop the queued operations without sending them. */
   abort(): void;
+  /**
+   * A stand-in for the id a queued operation will create, to put in a later
+   * operation's body on this batch, so a create and the write that uses it go
+   * in one transaction: op n's `id`, or with `index` the k-th of the `ids` a
+   * bulk create answers. `opIndex` counts from 0, or from the end when
+   * negative (-1, the default, is the op queued last). It goes only in the
+   * body of a later write on this batch, at any depth. Anywhere else (a path,
+   * another batch, a call made on the client) the client refuses it.
+   */
+  ref(opIndex?: number, index?: number): BatchRef;
+}
+
+/**
+ * See `PlaidBatch.ref`. A marker object, not data: the client takes it out of
+ * the body when its write is queued and sends where it was beside the body.
+ */
+export interface BatchRef {
+  /** The op, counted from 0 in the batch, whose id this stands for. */
+  readonly $ref: number;
+  /** For a bulk create, which of its ids. */
+  readonly index?: number;
 }
 
 export declare class PlaidClient {
@@ -1425,6 +1600,7 @@ export declare class PlaidClient {
   token: string;
   timeout: number | null;
   batchTimeout: number | null;
+  retryDelaysMs: number[] | undefined;
   /** The document strict mode is entered for, or null. */
   readonly strictModeDocumentId: string | null;
   /** The DocumentLockLost of the open `locked()` block whose lock lapsed, or null. Cleared when that block exits. */
@@ -1472,13 +1648,15 @@ export declare class PlaidClient {
   } | null;
   beginOperation(
     message: string,
-    opts?: { id?: string; kind?: OperationKind; ref?: string },
+    opts?: { id?: string; kind?: OperationKind; ref?: string; keys?: KeySeed; minted?: Set<string> },
   ): string;
+  /** A seed for the Idempotency-Keys of an operation that may be run again (see beginOperation's `keys`). */
+  keySeed(): KeySeed;
   endOperation(message?: string): Promise<void>;
   withOperation<T>(
     message: string,
     fn: (setMessage: (msg: string) => void) => Promise<T> | T,
-    opts?: { kind?: OperationKind; ref?: string },
+    opts?: { kind?: OperationKind; ref?: string; id?: string; keys?: KeySeed; minted?: Set<string> },
   ): Promise<T>;
   operationGroups: OperationGroupsBundle;
 
@@ -1529,6 +1707,25 @@ export function cpToUtf16(s: string, cp: number): number;
 /** Like indexOf, but the result and `fromCp` are code-point indices; -1 if absent. */
 export function cpIndexOf(s: string, sub: string, fromCp?: number): number;
 
+// --- Text edit operations (code points, running coordinates) ---------------
+/** One op as `PATCH /texts/:id` takes it; each index is in the body the ops before it left. */
+export type TextEditOp =
+  | { type: "insert"; index: number; value: string }
+  | { type: "delete"; index: number; value: number }
+  | { type: "replace"; index: number; length: number; value: string };
+/** Old-body code points [start, end) give way to `value`. */
+export interface TextGap {
+  start: number;
+  end: number;
+  value: string;
+}
+/** The net change of `ops` on `body` as gaps: sorted, never touching, no-op gaps dropped. Throws on a bad op. */
+export function composeTextEdits(body: string, ops: TextEditOp[]): TextGap[];
+/** Gaps as running ops: insert, delete or replace. */
+export function gapsToOps(gaps: TextGap[]): TextEditOp[];
+/** `body` with `ops` applied in turn. Throws on a bad op. */
+export function applyTextOps(body: string, ops: TextEditOp[]): string;
+
 // --- Shared layer-role vocabulary (cross-app interoperability) --------------
 // Substrate layers are tagged with a role at `config.plaid.role` (a scalar) so
 // that different apps can share a project. See the manual, "Layer Interoperability".
@@ -1538,6 +1735,10 @@ export const PLAID_NAMESPACE: "plaid";
 export const ROLE_KEY: "role";
 /** Layer config key naming the metadata keys a token born of a SPLIT inherits. */
 export const PRESERVE_ON_SPLIT_KEY: "preserveOnSplit";
+/** Layer config key asking Plaid to take a text edit plainly on the layer (see the manual's "Changing a text's body"). */
+export const PLAIN_EDITS_KEY: "plainEdits";
+/** Layer config key: a space typed inside a word of the text splits it (beside plainEdits). */
+export const SPLIT_ON_SPACE_KEY: "splitOnSpace";
 
 /** The server's cap on operations per batch request; a larger batch goes as consecutive requests. */
 export const MAX_BATCH_OPS: 1000;
@@ -1691,6 +1892,15 @@ export function mergeMetadata(
 
 // --- Create responses ---------------------------------------------------------
 /** The id a single create answered with, read off the call's response or its batch result (`{status, body}`). Undefined when it gave none. */
+/** Idempotency-Key seed for an operation run more than once (client.keySeed()). */
+export interface KeySeed {
+  seed: string;
+  stamps: Map<number, number | null>;
+}
+/** A fresh UUIDv7, for the id of something a client creates. */
+export function uuidv7(): string;
+/** Whether a write's answer was replayed from its Idempotency-Key's first send (`Idempotent-Replayed: true`), so it wrote nothing new. Marked on an object or list answer as a non-enumerable `replayed: true`. */
+export function wasReplayed(answer: unknown): boolean;
 export function createdId(result: any): string | undefined;
 /** The ids a bulk create answered with, in input order, read off the call's response or its batch result. Empty when it gave none. */
 export function createdIds(result: any): string[];
@@ -1764,3 +1974,41 @@ export function writerPolicy(contributorId?: string | null): {
   /** The same test over a provState. */
   readonly reviewableState: (state: string) => boolean;
 };
+
+// --- Layer constraints -------------------------------------------------------
+/** A constraint an app declares on a layer, e.g. {type: "value-set", values: ["N"]}. */
+export interface LayerConstraint {
+  type:
+    | "max-in-degree"
+    | "acyclic"
+    | "same-ancestor"
+    | "single-span"
+    | "value-set"
+    | "coextensive"
+    | "single-link";
+  [param: string]: any;
+}
+/** `expected`: the list read for the namespace, null when it was absent. */
+export interface ConstraintWriteOptions {
+  expected?: LayerConstraint[] | null;
+}
+/** One violation a 422 lists. */
+export interface ConstraintViolation {
+  constraint: string;
+  namespace: string | null;
+  layer: string;
+  layerName: string;
+  document: string | null;
+  at: string | null;
+  ids: string[];
+  value?: any;
+  parts?: string[];
+}
+/** The constraint types. */
+export const CONSTRAINT_TYPES: readonly string[];
+/** The camelCased violations of a write refused by a layer constraint, or null. */
+export function violationsOf(err: any): ConstraintViolation[] | null;
+export function valueSetAllows(
+  constraint: { values: string[]; delimiters?: string; parts?: "all" | "first" },
+  value: any,
+): boolean;

package/package.json

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