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

package/index.d.ts

@@ -667,7 +667,7 @@ interface Invite {
   id: string;
   /** "signup" | "password-reset" */
   kind: string;
-  /** "active" | "used" | "expired" | "revoked" */
+  /** "active" | "used" | "expired" | "revoked" | "inactive" */
   status: string;
   createdBy: string;
   createdAt: string;
@@ -685,7 +685,7 @@ interface Invite {
 interface InvitePreview {
   /** "signup" | "password-reset" */
   kind: string;
-  /** "active" | "used" | "expired" | "revoked" */
+  /** "active" | "used" | "expired" | "revoked" | "inactive" */
   status: string;
   expiresAt: string;
   grantAdmin: boolean;
@@ -923,6 +923,10 @@ interface AuditPageOptions {
   order?: "asc" | "desc";
   limit?: number;
   cursor?: string;
+  /** Keep only each entry's oldest N operations in `ops` (1..1000). Every entry has `opCount`. */
+  opsLimit?: number;
+  /** Read only this entry rather than a page. */
+  entryId?: string;
 }
 
 /** One user's activity over a scope and window. */
@@ -977,7 +981,10 @@ interface InvitesBundle {
     all?: boolean;
     pageSize?: number;
   }): AsyncGenerator<Invite[]>;
-  /** The `code` is returned ONCE and is not recoverable afterward. */
+  /**
+   * The `code` is returned ONCE and is not recoverable afterward. Needs a
+   * signed-in session: a named API token cannot mint any invite (403).
+   */
   create(
     opts?: CreateInviteOptions,
     auditMessage?: string,
@@ -1069,9 +1076,6 @@ export declare class DocumentLockLost extends Error {
   readonly cause?: unknown;
 }
 
-/** The server's default document-lock window, in ms. */
-export const DOCUMENT_LOCK_TTL_MS: 60000;
-
 interface DocumentsBundle {
   checkLock(documentId: string): Promise<any>;
   /**
@@ -1115,7 +1119,14 @@ interface DocumentsBundle {
       onProgress?: (progress: { loaded: number; total: number | null }) => void;
     },
   ): Promise<any>;
-  deleteMedia(documentId: string, auditMessage?: string): Promise<any>;
+  deleteMedia(
+    documentId: string,
+    auditMessage?: string,
+    options?: {
+      /** The recording meant, the `?v=` of the document's `mediaUrl`. A 409 when the stored one is another. */
+      mediaVersion?: string;
+    },
+  ): Promise<any>;
   setMetadata(
     documentId: string,
     body: any,
@@ -1458,7 +1469,7 @@ interface TokensBundle {
     tokenId: string,
     position: number,
     auditMessage?: string,
-    options?: { id?: string },
+    options?: { id?: string; keep?: "left" | "right" },
   ): Promise<any>;
   merge(
     tokenId: string,
@@ -1615,6 +1626,10 @@ export declare class PlaidClient {
   serverClockOffsetMs: number | null;
   /** The server's time now, from its last response's Date header (to the second), else this machine's. Judge a time the server stamped, such as an audit entry's `ts`, against this rather than `Date.now()`. */
   serverNow(): Date;
+  /** Hear every time a request is sent again: after a 503, or for a keyed write after its answer was lost (no response, 502, 504). Called before the wait. Returns the unsubscribe. */
+  onRetry(
+    listener: (info: { attempt: number; retries: number; delay: number; error: Error }) => void,
+  ): () => void;
 
   // Batches.
   //
@@ -1648,7 +1663,7 @@ export declare class PlaidClient {
   } | null;
   beginOperation(
     message: string,
-    opts?: { id?: string; kind?: OperationKind; ref?: string; keys?: KeySeed; minted?: Set<string> },
+    opts?: { groupId?: 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;
@@ -1656,7 +1671,7 @@ export declare class PlaidClient {
   withOperation<T>(
     message: string,
     fn: (setMessage: (msg: string) => void) => Promise<T> | T,
-    opts?: { kind?: OperationKind; ref?: string; id?: string; keys?: KeySeed; minted?: Set<string> },
+    opts?: { kind?: OperationKind; ref?: string; groupId?: string; keys?: KeySeed; minted?: Set<string> },
   ): Promise<T>;
   operationGroups: OperationGroupsBundle;
 
@@ -1702,8 +1717,6 @@ export function cpSlice(s: string, begin: number, end?: number): string;
 export function cpSlicer(s: string): (begin: number, end?: number) => string;
 /** UTF-16 index -> code-point index in `s`. */
 export function utf16ToCp(s: string, u: number): number;
-/** Code-point index -> UTF-16 index in `s` (clamps past the end). */
-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;
 
@@ -1735,13 +1748,13 @@ 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). */
+/** Layer config key: a space typed inside a word of the text splits it (see the manual's "Changing a text's body"). */
 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;
+/** How long `admin.backup()` waits for the server to finish writing a backup, in ms. */
+export const BACKUP_TIMEOUT_MS: number;
 /** The fixed role inventory; only these values are interoperable across apps. */
 export const ROLES: {
   readonly BASELINE: "baseline";
@@ -1854,20 +1867,12 @@ export function confirmedInferred(
 };
 /** Classify an entity's metadata into one of the three provenance states. */
 export function provState(metadata: object | null | undefined): ProvState;
-/** The verifying fragment, { provConfirmed: true }: PATCH it over existing metadata. */
-export const PROV_CONFIRMED: { readonly provConfirmed: true };
 /** Machine-made and not yet human-verified (needs review, replaceable, confirmable). */
 export function isMachine(metadata: object | null | undefined): boolean;
 /** Whether a machine writer must leave this entity alone (human or verified). !isMachine. */
 export function isProtected(metadata: object | null | undefined): boolean;
-/** The fragment a HUMAN edit should merge in: PROV_CONFIRMED iff machine-unverified, else null. */
-export function verifyOnEdit(
-  metadata: object | null | undefined,
-): { readonly provConfirmed: true } | null;
 /** Canonical provSource for a service: 'service:<serviceId>'. */
 export function serviceSource(serviceId: string): string;
-/** Canonical provSource for a contributor: 'user:<userId>'. */
-export function userSource(userId: string): string;
 /** The metadata fragment a contributor's work carries. */
 export function stampContributed(userId: string): {
   prov: "contributed";
@@ -1925,8 +1930,6 @@ export function isReservedMetadataKey(key: string): boolean;
 // --- Review: whose work is reviewed (a project-config norm) -------------------
 /** The config key, under the `plaid` namespace, holding the review lists. */
 export const REVIEW_KEY: "review";
-/** The project roles a review list may name. */
-export const PROJECT_ROLES: readonly ["reader", "writer", "maintainer"];
 /** A project's review lists, normalized. */
 export function readReview(config?: object | null): {
   users: string[];
@@ -2004,8 +2007,6 @@ export interface ConstraintViolation {
   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(

package/package.json

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

package/src/constraints.js

@@ -7,17 +7,6 @@
 
 import { transformResponse } from "./transforms.js";
 
-/** The constraint types, by the layer kind that may carry them. */
-export const CONSTRAINT_TYPES = Object.freeze([
-  "max-in-degree",
-  "acyclic",
-  "same-ancestor",
-  "single-span",
-  "value-set",
-  "coextensive",
-  "single-link",
-]);
-
 /**
  * The violations of a write refused by a layer constraint, camelCased
  * ({constraint, namespace, layer, layerName, document, at, ids, value?,

package/src/documentLock.js

@@ -1,3 +1,5 @@
+import { isUnknownOutcome, retryUnknown } from "./http.js";
+
 /**
  * Keeping a document lock alive for as long as a `locked()` block runs.
  *
@@ -27,21 +29,6 @@
  * that is missing somewhere.
  */
 
-/**
- * How long plaid-core holds a document lock before it expires, in ms.
- * `plaid.server.locks/default-lock-expiration-ms`. An operator can change it
- * with `:plaid.server.locks/config :expiration-ms`, and a server publishes what
- * it enforces as `lockExpirationMs` in `GET /info`. This is the last resort:
- * what a live lock is renewed against is the `expiresAt` on the acquire
- * response, which names the moment rather than the window.
- */
-export const DOCUMENT_LOCK_TTL_MS = 60000;
-
-// Widest lock lifetime we will believe from a server response. Past this the
-// number is a clock skew between this machine and the server rather than a
-// configured window, and the documented default is the better guess.
-const MAX_BELIEVABLE_TTL_MS = 3600000;
-
 /**
  * The lock a `documents.locked()` block was holding is no longer held.
  *
@@ -62,25 +49,31 @@ export class DocumentLockLost extends Error {
 /**
  * How long a freshly taken lock lasts, from the server's own answer.
  *
- * `expiresAt` is the epoch-millisecond stamp the lock endpoints return.
- * Comparing it against this machine's clock is the only way to learn a window
- * an operator has retuned, and it is also the one place a clock skew can get
- * in, so an answer outside a believable band falls back to the documented
- * default rather than to a beat that never fires or fires constantly.
+ * `expiresAt` is the epoch-millisecond moment the lock endpoints return, on
+ * the server's clock, so it is read against the server's clock too
+ * (`client.serverNow()`): this machine's clock being off cannot stretch or
+ * shrink the window. It is how a window an operator has retuned
+ * (`:plaid.server.locks/config :expiration-ms`) reaches the keeper.
  *
- * @param {number|undefined} expiresAt
- * @param {number} nowMs
- * @param {number} [fallback]
+ * An answer that cannot be a window (none, already over, past an hour) is
+ * core's default, 60 s.
+ *
+ * @param {number} expiresAt
+ * @param {number} serverNowMs
  * @returns {number}
  */
-export function lockTtlMs(expiresAt, nowMs, fallback = DOCUMENT_LOCK_TTL_MS) {
-  if (typeof expiresAt === "number" && Number.isFinite(expiresAt)) {
-    const ttl = expiresAt - nowMs;
-    if (ttl > 0 && ttl <= MAX_BELIEVABLE_TTL_MS) return ttl;
-  }
-  return fallback;
+export function lockTtlMs(expiresAt, serverNowMs) {
+  const ttl = expiresAt - serverNowMs;
+  // No answer at all, or one past an hour or already over: this machine's
+  // clock stood in for the server's (a page that cannot read its Date
+  // header) and is far off. Core's default window is the better guess.
+  return Number.isFinite(ttl) && ttl > 0 && ttl <= MAX_TTL_MS ? ttl : DEFAULT_TTL_MS;
 }
 
+// Core's default lock window, and the longest one believed.
+const DEFAULT_TTL_MS = 60000;
+const MAX_TTL_MS = 3600000;
+
 /**
  * Renews one document's lock until the block holding it exits.
  *
@@ -100,9 +93,7 @@ export class LockKeeper {
   ) {
     this._refresh = refresh;
     this._documentId = documentId;
-    // A window under two seconds leaves no room for a retry; treat it as a
-    // misconfiguration and beat at the documented rate instead.
-    this._ttlMs = ttlMs >= 2000 ? ttlMs : DOCUMENT_LOCK_TTL_MS;
+    this._ttlMs = ttlMs;
     this._onLost = onLost;
     this._clock = clock;
     this._sleep = sleep || ((ms) => this._defaultSleep(ms));
@@ -219,16 +210,11 @@ export class DocumentLock {
 }
 
 /**
- * Tries a `locked()` block makes at an acquire whose outcome is unknown, and the
- * pause before the next, which grows by this much each time.
+ * The pause before sending again an acquire whose outcome is unknown, which
+ * grows by this much each time (three sends in all).
  */
-export const LOCK_ACQUIRE_ATTEMPTS = 3;
 export const LOCK_ACQUIRE_RETRY_MS = 500;
 
-// The HTTP status of a request that may or may not have reached the server: no
-// answer at all (0), or a proxy's 502 or 504.
-const UNKNOWN_OUTCOME_STATUSES = new Set([0, 502, 504]);
-
 function mintLockId() {
   return globalThis.crypto.randomUUID();
 }
@@ -237,45 +223,42 @@ function mintLockId() {
  * The acquire of a `locked()` block, under the holder id it minted.
  *
  * An acquire whose outcome is unknown (no answer, a timeout, a 502 or a 504)
- * may have taken the lock. It is sent again under the same id, which the server
- * answers 200 while that holder has it. When every attempt is unknown, the lock
- * it may hold is released on the way out, so it does not stand in everyone's
- * way until it expires.
+ * may have taken the lock. It is sent again under the same id as any write is
+ * (`retryUnknown`), which the server answers 200 while that holder has it.
+ * When every send is unknown (or the network went), the lock it may hold is
+ * released on the way out, so it does not stand in everyone's way until it
+ * expires.
  */
 async function takeLock(client, documentId, lockId, retryMs) {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      return await client.documents.acquireLock(documentId, undefined, lockId);
-    } catch (error) {
-      if (error?.status === 423) {
-        // The error body is raw JSON off the wire, so it is still kebab-cased.
-        const body = error.responseData || {};
-        const holder = body.userId || body["user-id"] || "another user";
-        const readable = new Error(
-          `This document is being edited by ${holder}. Try again once they're done.`,
-        );
-        readable.status = 423;
-        readable.statusText = error.statusText;
-        readable.url = error.url;
-        readable.method = error.method;
-        readable.responseData = error.responseData;
-        readable.cause = error;
-        throw readable;
-      }
-      if (!UNKNOWN_OUTCOME_STATUSES.has(error?.status)) throw error;
-      if (attempt + 1 < LOCK_ACQUIRE_ATTEMPTS) {
-        await new Promise((resolve) =>
-          setTimeout(resolve, retryMs * (attempt + 1)),
-        );
-        continue;
-      }
+  try {
+    return await retryUnknown(
+      () => client.documents.acquireLock(documentId, undefined, lockId),
+      { delaysMs: [retryMs, 2 * retryMs] },
+    );
+  } catch (error) {
+    if (error?.status === 423) {
+      // The error body is raw JSON off the wire, so it is still kebab-cased.
+      const body = error.responseData || {};
+      const holder = body.userId || body["user-id"] || "another user";
+      const readable = new Error(
+        `This document is being edited by ${holder}. Try again once they're done.`,
+      );
+      readable.status = 423;
+      readable.statusText = error.statusText;
+      readable.url = error.url;
+      readable.method = error.method;
+      readable.responseData = error.responseData;
+      readable.cause = error;
+      throw readable;
+    }
+    if (isUnknownOutcome(error)) {
       try {
         await client.documents.releaseLock(documentId, lockId);
       } catch {
         /* the lock expires on its own */
       }
-      throw error;
     }
+    throw error;
   }
 }
 
@@ -300,7 +283,7 @@ export async function withDocumentLock(
   const lockId = info?.lockId ?? minted;
   let keeper = null;
   if (keepAlive) {
-    const ttlMs = lockTtlMs(info?.expiresAt, Date.now());
+    const ttlMs = lockTtlMs(info.expiresAt, client.serverNow().getTime());
     client.documentLockLost = null;
     keeper = new LockKeeper(
       (id) => client.documents.renewLock(id, lockId),

package/src/http.js

@@ -46,9 +46,11 @@ import { uuidv7 } from "./ids.js";
 // does not 409 the next. A batch split past MAX_BATCH_OPS restamps each later
 // request with the version the one before it left (see submitBatch).
 //
-// `noBatch` is not part of that judgment. It marks the four calls the batch
-// transport cannot carry at all (the multipart media and avatar uploads, the
-// user-data store's put and delete) and raises so the caller finds out. A
+// `noBatch` is not part of that judgment. It marks the calls a batch cannot
+// carry at all (the multipart media and avatar uploads, the user-data store's
+// put and delete, and minting an API token or an invite, whose answer is a
+// secret the server refuses to keep with a keyed batch's answer) and raises
+// so the caller finds out. A
 // batch inside a batch is refused by the batch itself. Never put it on a read: it turns a swallowed read into a
 // thrown one, which is what the chrome hit when an unrelated import was
 // running. A blobless DELETE beside an upload is not one of them: it carries
@@ -67,6 +69,23 @@ export const DEFAULT_TIMEOUT_MS = 30000;
 // nothing and costs a retry stacked on a write that is still running.
 export const DEFAULT_BATCH_TIMEOUT_MS = 180000;
 
+// A query may run for core's own query limit (30 s, `*query-timeout-ms*` in
+// plaid.sql.query.exec), and core then answers 408. The client waits a little
+// longer than that, so the caller gets core's 408 for a query too broad and
+// not a timeout of its own that reads like a lost connection.
+export const DEFAULT_QUERY_TIMEOUT_MS = 35000;
+
+/**
+ * The timeout for a query: the client's own, raised to
+ * DEFAULT_QUERY_TIMEOUT_MS when it is shorter. A disabled timeout (0, null)
+ * stays disabled.
+ */
+export function queryTimeout(client) {
+  const t = client.timeout;
+  if (!t || t <= 0) return t;
+  return Math.max(t, DEFAULT_QUERY_TIMEOUT_MS);
+}
+
 /**
  * Note how far the server's clock is from this machine's, from a response's
  * Date header, for `client.serverNow()`. A time the server stamped (an audit
@@ -240,10 +259,10 @@ export async function retryWhileBusy(
 // ---------------------------------------------------------------------------
 // The Idempotency-Key.
 //
-// Every write that is not a signal (`outOfBand`), an upload (`noBatch`) or a
-// call that mints a secret (`noIdempotency`) goes out with an
-// `Idempotency-Key` header, and so does every batch request (a queued op has
-// none: its batch request carries one). The server keeps the answer to a
+// Every write that is not a signal (`outOfBand`) or a call a batch cannot
+// carry (`noBatch`: an upload, user data, a call that mints a secret) goes out
+// with an `Idempotency-Key` header, and so does every batch request (a queued
+// op has none: its batch request carries one). The server keeps the answer to a
 // keyed write for a day, and the same key sent again for the same request is
 // answered from it with `Idempotent-Replayed: true`, writing nothing. So a
 // write whose answer was lost (no response, 502, 504) can be sent again
@@ -274,6 +293,22 @@ export function isUnknownOutcome(error) {
   return status === 0 || status === 502 || status === 504;
 }
 
+/**
+ * Whether a create refused with `status` and body `data` was made by an
+ * earlier send of the same work: `409 id-taken` for an id in `minted` (a Set
+ * of the ids the work minted for its creates), and not for a row deleted
+ * since (there is nothing to go on with). The one rule for a lost answer's
+ * create. The Python twin is `minted_taken`.
+ */
+export function mintedTaken(status, data, minted) {
+  return (
+    status === 409 &&
+    data?.error === "id-taken" &&
+    !data.deleted &&
+    !!minted?.has(data.id)
+  );
+}
+
 /**
  * Run `attempt`, sending it again after each delay in `delaysMs` while it
  * fails with an unknown outcome. Only for a keyed write, whose resend is
@@ -588,8 +623,7 @@ export function takesIdempotencyKey(method, options = {}) {
   return (
     method !== "GET" &&
     !options.outOfBand &&
-    !options.noBatch &&
-    !options.noIdempotency
+    !options.noBatch
   );
 }
 
@@ -705,8 +739,8 @@ export async function queueRequest(batch, method, path, options = {}) {
  *   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 made on a batch. Only for calls the
- *                     batch transport cannot carry at all (see the note at the
+ *   noBatch         - If true, throw when made on a batch. Only for calls a
+ *                     batch cannot carry at all (see the note at the
  *                     top of this file); never for a read.
  *   outOfBand       - If true, the call is a signal rather than a write of
  *                     project data: made on a batch it still goes over the
@@ -721,6 +755,10 @@ export async function queueRequest(batch, method, path, options = {}) {
  *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
  *   noAuth          - Skip Authorization header
  *   binaryResponse  - Return arrayBuffer instead of JSON/text
+ *   noBusyRetry     - If true, a 503 is not retried. For a query: core
+ *                     answers 503 when its queue of large queries stays full
+ *                     until the query's deadline, and asking again at once
+ *                     only joins the same queue.
  *   timeout         - Per-request timeout in ms overriding client.timeout
  *                     for this call (0/null disables). Used for known-long
  *                     ops like project delete.
@@ -739,6 +777,7 @@ export async function makeRequest(client, method, path, options = {}) {
     timeout,
     onUploadProgress,
     learningOmittedVersion,
+    noBusyRetry,
   } = options;
   if (method !== "GET" && omittedStrictDocument(client)) {
     await learnOmittedVersion(client);
@@ -807,22 +846,23 @@ export async function makeRequest(client, method, path, options = {}) {
   };
 
   try {
+    const onRetry = (info) => client._noteRetry?.(info);
+    const busy = noBusyRetry ? { onRetry, retries: 0 } : { onRetry };
     const response = keyed
-      ? await retryUnknown(() => retryWhileBusy(attempt), {
+      ? await retryUnknown(() => retryWhileBusy(attempt, busy), {
           delaysMs: client.retryDelaysMs,
+          onRetry,
         })
-      : await retryWhileBusy(attempt);
+      : await retryWhileBusy(attempt, busy);
     noteServerClock(client, response.headers);
 
     if (!response.ok) {
       const errorData = await parseErrorBody(response);
-      // Only a single create: a bulk refused whole made none of its rows.
-      // Never a deleted row: there is nothing to open.
+      // Answered as made only for a single create, the one whose answer is
+      // the id alone. A bulk or a batch taken so is made whole (it is one
+      // transaction), and a caller that sends one decides what it answers.
       if (
-        response.status === 409 &&
-        errorData?.error === "id-taken" &&
-        !errorData.deleted &&
-        minted?.has(errorData.id) &&
+        mintedTaken(response.status, errorData, minted) &&
         requestBody?.id === errorData.id
       ) {
         if (stampedGroup) stampedGroup.written = true;