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

package/README.md

@@ -0,0 +1,35 @@
+# @larc-iu/plaid-client
+
+The JavaScript client for the [Plaid](https://larc-iu.github.io/plaid/) annotation API.
+It has no dependencies and runs in browsers and in Node.
+
+## From npm
+
+```sh
+npm install @larc-iu/plaid-client@alpha
+```
+
+```js
+import { PlaidClient } from "@larc-iu/plaid-client";
+
+const client = await PlaidClient.login("http://localhost:8080", "user@example.com", "password");
+console.log(await client.projects.list());
+```
+
+## From a Plaid server
+
+Every Plaid server serves the client that matches its own version at `/client/plaid-client.js`, with its type declarations at `/client/plaid-client.d.ts`.
+A page served by Plaid, for example from the folder set as `static_resources_path` in its `config.toml`, can import it without bundling a copy:
+
+```html
+<script type="module">
+  import { PlaidClient } from "/client/plaid-client.js";
+  const client = await PlaidClient.login(location.origin, "user@example.com", "password");
+  console.log(await client.projects.list());
+</script>
+```
+
+## Documentation
+
+- [Manual](https://larc-iu.github.io/plaid/manual.html), which covers the API and its concepts.
+- [API reference](https://larc-iu.github.io/plaid/api-js.html) for this client.

package/index.d.ts

@@ -422,6 +422,8 @@ interface UsersBundle {
 interface UserDataEntry {
   key: string;
   updatedAt: string;
+  /** Raised by one on every write of the entry. A new entry is 1. */
+  version: number;
   value?: any;
 }
 
@@ -446,11 +448,18 @@ interface UserDataBundle {
     opts?: UserDataOptions & { pageSize?: number },
   ): AsyncGenerator<UserDataEntry[]>;
   get(userId: string, key: string): Promise<UserDataEntry & { value: any }>;
+  /**
+   * `version`: write only when the entry is still at this version (0: only
+   * when there is none). Refused with 409, `error: "version-mismatch"` and the
+   * stored `version` and `updatedAt` on the error's `responseData`, when
+   * another write landed since.
+   */
   put(
     userId: string,
     key: string,
     value: any,
-  ): Promise<{ key: string; updatedAt: string }>;
+    opts?: { version?: number },
+  ): Promise<{ key: string; updatedAt: string; version: number }>;
   delete(userId: string, key: string): Promise<any>;
 }
 
@@ -1904,6 +1913,8 @@ export interface KeySeed {
 }
 /** A fresh UUIDv7, for the id of something a client creates. */
 export function uuidv7(): string;
+/** A fresh random UUID (version 4), from crypto.getRandomValues, so it works on any page. */
+export function uuidv4(): 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;

package/package.json

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

package/src/documentLock.js

@@ -1,4 +1,5 @@
 import { isUnknownOutcome, retryUnknown } from "./http.js";
+import { uuidv4 } from "./ids.js";
 
 /**
  * Keeping a document lock alive for as long as a `locked()` block runs.
@@ -216,7 +217,7 @@ export class DocumentLock {
 export const LOCK_ACQUIRE_RETRY_MS = 500;
 
 function mintLockId() {
-  return globalThis.crypto.randomUUID();
+  return uuidv4();
 }
 
 /**

package/src/ids.js

@@ -52,3 +52,23 @@ export function uuidv7() {
   }
   return s;
 }
+
+/**
+ * A random UUIDv4, for ids that need no order (an operation group, a lock
+ * holder). Built on `crypto.getRandomValues`, since `crypto.randomUUID`
+ * exists only in a secure context and a page served over plain HTTP from
+ * another host than localhost is not one.
+ * @returns {string}
+ */
+export function uuidv4() {
+  const b = new Uint8Array(16);
+  crypto.getRandomValues(b);
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  let s = "";
+  for (let i = 0; i < 16; i++) {
+    s += hex[b[i]];
+    if (i === 3 || i === 5 || i === 7 || i === 9) s += "-";
+  }
+  return s;
+}

package/src/index.js

@@ -22,7 +22,7 @@ import {
   DEFAULT_BATCH_TIMEOUT_MS,
   queryTimeout,
 } from "./http.js";
-import { uuidv7 } from "./ids.js";
+import { uuidv4, uuidv7 } from "./ids.js";
 import { constraintsBody } from "./constraints.js";
 import { listAll, listPage, iterPages } from "./pagination.js";
 import { recorderFor } from "./events.js";
@@ -1474,7 +1474,7 @@ class PlaidClient {
           query: { prefix, pattern, "include-values": includeValues },
         }),
       /**
-       * Read one private data entry ({key, updatedAt, value}); 404 if absent.
+       * Read one private data entry ({key, updatedAt, version, value}); 404 if absent.
        * @param {string} userId
        * @param {string} key
        */
@@ -1492,17 +1492,28 @@ class PlaidClient {
        * value whose keys are camelCase round-trips unchanged while one keyed
        * by arbitrary strings does not. Put such a map under a `metadata` key,
        * which both clients pass through untouched.
+       *
+       * Every write raises the entry's `version` by one, and reads answer it.
+       * With `version`, the write lands only when the entry is still at that
+       * version (0: only when there is no entry), and is otherwise refused with
+       * 409, `error: "version-mismatch"`, and the stored `version` and
+       * `updatedAt` on the error's `responseData`: read it again and make the
+       * change on what is there.
        * @param {string} userId
        * @param {string} key
        * @param {*} value
+       * @param {object} [opts]
+       * @param {number} [opts.version] - The version this write was made from
+       * @returns {Promise<{key: string, updatedAt: string, version: number}>}
        */
-      put: (userId, key, value) =>
+      put: (userId, key, value, { version } = {}) =>
         this._request(
           "PUT",
           `/api/v1/users/${userId}/data/${encodeURIComponent(key)}`,
           {
             body: value,
             noBatch: true,
+            queryParams: { version },
           },
         ),
       /**
@@ -2148,9 +2159,9 @@ class PlaidClient {
        * Upload a media file for a document. Uses Apache Tika for content validation.
        * A document that already has a recording refuses it with a 409
        * (`media-exists`, and the current `media-url`): delete that one first.
-       * A WAV whose samples are not PCM or float (IMA or MS ADPCM, GSM, A-law
-       * and the rest), which browsers cannot play, is refused with a 415
-       * whose `error` names its coding.
+       * A WAV whose samples are not PCM, 32-bit float, A-law or mu-law (IMA or
+       * MS ADPCM, GSM, 64-bit float and the rest), which browsers cannot play,
+       * is refused with a 415 whose `error` names its coding.
        * @param {string} documentId - The document ID
        * @param {File} file - The file to upload
        * @param {string} [auditMessage] - Custom audit-log message for this write
@@ -2216,7 +2227,10 @@ class PlaidClient {
         }),
       /**
        * Get audit log for a document. Transparently follows pagination cursors
-       * and returns the full flat array.
+       * and returns the full flat array. Each entry, and each of its `ops`,
+       * says what kind of credential made it as `credential`: `login`,
+       * `named-token`, `service` or `delegated` (absent on older operations),
+       * beside `apiToken` (the named token's id and name) when there was one.
        * @param {string} documentId - The document ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -2452,7 +2466,10 @@ class PlaidClient {
         ),
       /**
        * Get audit log for a project. Transparently follows pagination cursors
-       * and returns the full flat array.
+       * and returns the full flat array. Each entry, and each of its `ops`,
+       * says what kind of credential made it as `credential`: `login`,
+       * `named-token`, `service` or `delegated` (absent on older operations),
+       * beside `apiToken` (the named token's id and name) when there was one.
        * @param {string} projectId - The project ID
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
@@ -3809,7 +3826,7 @@ class PlaidClient {
       return open.id;
     }
     this.operationGroup = {
-      id: groupId ? String(groupId) : crypto.randomUUID(),
+      id: groupId ? String(groupId) : uuidv4(),
       message: message == null ? null : String(message),
       kind: kind == null ? null : String(kind),
       ref: ref == null ? null : String(ref),
@@ -4412,7 +4429,8 @@ export {
 // result. See ./created.js.
 export { createdId, createdIds } from "./created.js";
 // UUIDv7 ids for what a client creates. See ./ids.js and the manual,
-// "Retrying a write".
-export { uuidv7 } from "./ids.js";
+// "Retrying a write". uuidv4 works where crypto.randomUUID does not (a page
+// served over plain HTTP from any host but localhost).
+export { uuidv4, uuidv7 } from "./ids.js";
 export { wasReplayed } from "./replayed.js";
 export { MAX_BATCH_OPS };