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

package/index.d.ts

@@ -164,6 +164,11 @@ interface UsersBundle {
   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>;
+  /** URL for a user's profile picture, usable as an <img> src. Null when avatarHash is explicitly null. */
+  avatarUrl(id: string, avatarHash?: string | null): string | null;
+  getAvatar(id: string): Promise<any>;
+  setAvatar(id: string, file: File | Blob, auditMessage?: string): Promise<any>;
+  deleteAvatar(id: string, auditMessage?: string): Promise<any>;
 }
 
 interface ApiTokensBundle {
@@ -174,6 +179,59 @@ interface ApiTokensBundle {
   revoke(userId: string, tokenId: string, auditMessage?: string): Promise<any>;
 }
 
+interface Invite {
+  id: string;
+  /** "signup" | "password-reset" */
+  kind: string;
+  /** "active" | "used" | "expired" | "revoked" */
+  status: string;
+  createdBy: string;
+  createdAt: string;
+  expiresAt: string;
+  maxUses: number;
+  uses: number;
+  revokedAt: string | null;
+  note: string | null;
+  targetUserId: string | null;
+  grantAdmin: boolean;
+  projectId: string | null;
+  projectRole: string | null;
+}
+
+interface InvitePreview {
+  /** "signup" | "password-reset" */
+  kind: string;
+  /** "active" | "used" | "expired" | "revoked" */
+  status: string;
+  expiresAt: string;
+  grantAdmin: boolean;
+  projectName?: string;
+  projectRole?: string;
+  /** Present only for a password reset: whose account the link belongs to. */
+  username?: string;
+}
+
+interface CreateInviteOptions {
+  projectId?: string;
+  /** "reader" | "writer" | "maintainer" */
+  projectRole?: string;
+  grantAdmin?: boolean;
+  /** Makes this a password reset for that user (admin only). */
+  targetUserId?: string;
+  maxUses?: number;
+  ttlDays?: number;
+  note?: string;
+}
+
+interface InvitesBundle {
+  list(opts?: { projectId?: string }): Promise<Invite[]>;
+  listPage(opts?: { projectId?: string; limit?: number; cursor?: string }): Promise<Page>;
+  iterPages(opts?: { projectId?: string; pageSize?: number }): AsyncGenerator<Invite[]>;
+  /** The `code` is returned ONCE and is not recoverable afterward. */
+  create(opts?: CreateInviteOptions, auditMessage?: string): Promise<Invite & { code: string }>;
+  revoke(id: string, auditMessage?: string): Promise<any>;
+}
+
 interface TokenLayersBundle {
   shift(tokenLayerId: string, direction: string, auditMessage?: string): Promise<any>;
   create(textLayerId: string, name: string, overlapMode?: string, parentTokenLayerId?: string, auditMessage?: string): Promise<any>;
@@ -295,9 +353,25 @@ interface PlaidClientOptions {
   onAuthError?: ((error: Error) => void) | null;
 }
 
+export interface OperationGroupsBundle {
+  get(id: string): Promise<any>;
+  update(id: string, message: string | null): Promise<any>;
+}
+
 export declare class PlaidClient {
   constructor(baseUrl: string, token: string, options?: PlaidClientOptions);
   static login(baseUrl: string, userId: string, password: string, options?: PlaidClientOptions): Promise<PlaidClient>;
+  /** Build the link to hand someone for an invite code. */
+  static inviteUrl(appUrl: string, code: string): string;
+  /** Describe an invite code with no authentication (for a signup page). */
+  static lookupInvite(baseUrl: string, code: string, options?: PlaidClientOptions): Promise<InvitePreview>;
+  /** Redeem an invite code with no authentication; resolves to a logged-in client. */
+  static redeemInvite(
+    baseUrl: string,
+    code: string,
+    credentials: { username?: string; password: string },
+    options?: PlaidClientOptions,
+  ): Promise<{ client: PlaidClient; userId: string; kind: string }>;
   timeout: number | null;
   /** Fired once on HTTP 401 (see PlaidClientOptions.onAuthError). */
   onAuthError: ((error: Error) => void) | null;
@@ -314,12 +388,14 @@ export declare class PlaidClient {
   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>;
+  // Logical operations (audit-log grouping). While one is open every write is
+  // stamped with its group id so the audit log folds them into one entry.
+  // Not atomic; nesting flattens into the outer operation.
+  operationGroup: { id: string; message: string | null } | null;
+  beginOperation(message: string, opts?: { id?: string }): string;
+  endOperation(message?: string): Promise<void>;
+  withOperation<T>(message: string, fn: (setMessage: (msg: string) => void) => Promise<T> | T): Promise<T>;
+  operationGroups: OperationGroupsBundle;
 
   // Query
   query(body: any, auditMessage?: string): Promise<any>;
@@ -333,6 +409,7 @@ export declare class PlaidClient {
   texts: TextsBundle;
   users: UsersBundle;
   apiTokens: ApiTokensBundle;
+  invites: InvitesBundle;
   tokenLayers: TokenLayersBundle;
   documents: DocumentsBundle;
   messages: MessagesBundle;
@@ -392,6 +469,7 @@ export const TASKS: {
   readonly PARSE: 'parse';
   readonly TRANSCRIBE: 'transcribe';
   readonly LINK_VOCAB: 'link-vocab';
+  readonly ANALYZE: 'analyze';
 };
 /** Whether a service serves a task (declared `extras.tasks`, legacy id-prefix fallback). */
 export function servesTask(service: DiscoveredService, task: string): boolean;
@@ -442,9 +520,13 @@ 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). */
+/** 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: { provConfirmed: true } iff machine-unverified, else null. */
-export function verifyOnEdit(metadata: object | null | undefined): { provConfirmed: true } | null;
+/** 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;

package/package.json

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

package/src/http.js

@@ -157,16 +157,25 @@ export async function makeRequest(client, method, path, options = {}) {
     }
   }
 
-  // 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
+  // Per-call custom audit-log message (overrides the auto-generated
+  // description of THIS write). 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') {
+  if (auditMessage && method !== 'GET') {
     const separator = url.includes('?') ? '&' : '?';
-    url += `${separator}audit-message=${encodeURIComponent(effectiveAuditMessage)}`;
+    url += `${separator}audit-message=${encodeURIComponent(auditMessage)}`;
+  }
+
+  // Logical-operation group (see client.beginOperation): stamp every write
+  // with the group id; the message rides along too so the server can label
+  // the group lazily on whichever tagged write lands first.
+  if (client.operationGroup && method !== 'GET') {
+    const group = client.operationGroup;
+    const separator = url.includes('?') ? '&' : '?';
+    url += `${separator}group-id=${encodeURIComponent(group.id)}`;
+    if (group.message) url += `&group-message=${encodeURIComponent(group.message)}`;
+    group.written = true;
   }
 
   // Batch mode

package/src/index.js

@@ -16,6 +16,24 @@ import {
   requestService,
 } from './services.js';
 
+// Helper: normalize a document-read `layers` filter to the wire's
+// comma-separated form. Accepts an array of layer ids or a ready-made string;
+// anything empty becomes undefined so no `?layers=` is sent at all.
+function layersParam(layers) {
+  if (layers === undefined || layers === null) return undefined;
+  const joined = Array.isArray(layers) ? layers.join(',') : String(layers);
+  return joined.length > 0 ? joined : undefined;
+}
+
+// Helper: normalize an audit `opTypes` filter to the wire's comma-separated
+// form. Accepts an array of op types or a ready-made string; anything empty
+// becomes undefined so no `?op-types=` is sent at all.
+function opTypesParam(opTypes) {
+  if (opTypes === undefined || opTypes === null) return undefined;
+  const joined = Array.isArray(opTypes) ? opTypes.join(',') : String(opTypes);
+  return joined.length > 0 ? joined : undefined;
+}
+
 // Helper: build body object, filtering out undefined values
 function bodyOf(obj) {
   const result = {};
@@ -25,6 +43,32 @@ function bodyOf(obj) {
   return result;
 }
 
+// POST to an endpoint that takes no Authorization header (login, invite lookup
+// and redemption). Deliberately does not go through PlaidClient._request: these
+// are called before any client exists, which is the whole point.
+async function anonymousPost(baseUrl, path, body, options = {}) {
+  const base = baseUrl.replace(/\/$/, '');
+  const url = `${base}${path}`;
+  try {
+    const fetchOptions = {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    };
+    const signal = timeoutSignal(options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS);
+    if (signal) fetchOptions.signal = signal;
+
+    const response = await fetch(url, fetchOptions);
+    if (!response.ok) {
+      throw makeHttpError(response, await parseErrorBody(response), url, 'POST');
+    }
+    return transformResponse(await response.json());
+  } catch (error) {
+    if (error.status) throw error;
+    throw makeNetworkError(error, url, 'POST');
+  }
+}
+
 class PlaidClient {
   /**
    * Create a new PlaidClient instance
@@ -41,9 +85,11 @@ class PlaidClient {
     this.batchOperations = [];
     this.documentVersions = {};
     this.strictModeDocumentId = null;
-    // Ambient custom audit-log message applied to write requests; null = use
-    // the server's auto-generated description. See setAuditMessage / withAuditMessage.
-    this.auditMessage = null;
+    // The open logical operation (audit-log group), or null. While set, every
+    // write is stamped with `?group-id=` (+ `group-message`) so the audit log
+    // folds them into ONE expandable entry. See beginOperation / withOperation.
+    // Shape: { id, message, depth, written, refined }.
+    this.operationGroup = null;
     // Optional callback fired once (per client) when any request returns HTTP
     // 401 — i.e. the token is missing/expired/invalid. Apps use it to discard
     // the stored token and route back to login. See makeRequest in http.js.
@@ -601,10 +647,19 @@ class PlaidClient {
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
        * @param {string} [asOf] - Temporal query timestamp
+       * @param {string[]|string} [opTypes] - Only return operations of these
+       *   types, spelled as in an entry's `op/type` (e.g.
+       *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
+       *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (userId, startTime, endTime, asOf) =>
+      audit: (userId, startTime, endTime, asOf, opTypes) =>
         listAll(this, `/api/v1/users/${userId}/audit`, {
-          query: { 'start-time': startTime, 'end-time': endTime, 'as-of': asOf },
+          query: {
+            'start-time': startTime,
+            'end-time': endTime,
+            'as-of': asOf,
+            'op-types': opTypesParam(opTypes),
+          },
         }),
       /**
        * Get a user by ID
@@ -646,6 +701,60 @@ class PlaidClient {
         this._request('PATCH', `/api/v1/users/${id}`, { auditMessage,
           body: bodyOf({ password, username, 'is-admin': isAdmin }),
         }),
+      /**
+       * Build a URL for a user's profile picture, suitable for use directly as
+       * an `<img>` src. An image element cannot send an Authorization header,
+       * so the session token rides in the query string, the same way document
+       * media does.
+       *
+       * Pass the user record's `avatarHash` as the second argument whenever you
+       * have it: the URL then addresses that exact picture, so the browser can
+       * cache it indefinitely and still pick up a replacement the moment the
+       * user changes it. Returns null when the user has no picture, so callers
+       * can fall back to initials without a wasted request.
+       * @param {string} id - The user ID
+       * @param {string} [avatarHash] - The user record's `avatarHash`
+       * @returns {string|null}
+       */
+      avatarUrl: (id, avatarHash) => {
+        if (avatarHash === null) return null;
+        const params = new URLSearchParams({ token: this.token });
+        if (avatarHash) params.set('v', avatarHash);
+        return `${this.baseUrl}/api/v1/users/${id}/avatar?${params}`;
+      },
+      /**
+       * Fetch a user's profile picture as raw bytes. Most callers want
+       * avatarUrl() instead. This one is for non-browser consumers.
+       * @param {string} id - The user ID
+       */
+      getAvatar: (id) =>
+        this._request('GET', `/api/v1/users/${id}/avatar`, {
+          noBatch: true,
+          binaryResponse: true,
+        }),
+      /**
+       * Upload a profile picture. Your own, or anyone's if you are an admin.
+       * The server center-crops to a square, scales to the configured edge
+       * length, and re-encodes, so no client-side resizing is needed. Accepts
+       * PNG, JPEG, WebP, and GIF. Resolves to the updated user record.
+       * @param {string} id - The user ID
+       * @param {File} file - The image to upload
+       */
+      setAvatar: (id, file, auditMessage) => {
+        const fd = new FormData();
+        fd.append('file', file);
+        return this._request('PUT', `/api/v1/users/${id}/avatar`, { auditMessage,
+          body: fd, formData: true, noBatch: true,
+        });
+      },
+      /**
+       * Remove a profile picture. Your own, or anyone's if you are an admin.
+       * @param {string} id - The user ID
+       */
+      deleteAvatar: (id, auditMessage) =>
+        this._request('DELETE', `/api/v1/users/${id}/avatar`, { auditMessage,
+          noBatch: true,
+        }),
     };
 
     this.apiTokens = {
@@ -700,6 +809,74 @@ class PlaidClient {
         this._request('DELETE', `/api/v1/users/${userId}/tokens/${tokenId}`, { auditMessage }),
     };
 
+    this.invites = {
+      /**
+       * List invites you minted, oldest first. With `projectId`, lists that
+       * project's invites instead (including co-maintainers'), which requires
+       * maintainer or admin on it. Never includes invite codes — the code is
+       * returned once, by create(), and is not recoverable afterward.
+       * Transparently follows pagination cursors and returns the full flat array.
+       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - List this project's invites instead of your own
+       */
+      list: ({ projectId } = {}) =>
+        listAll(this, '/api/v1/invites', { query: { 'project-id': projectId } }),
+      /**
+       * Fetch a single page of invites.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: ({ projectId, limit, cursor } = {}) =>
+        listPage(this, '/api/v1/invites', { limit, cursor, query: { 'project-id': projectId } }),
+      /**
+       * Async-iterate invites page by page; yields each page's entries array.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {number} [opts.pageSize] - Per-request page size
+       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: ({ projectId, pageSize } = {}) =>
+        iterPages(this, '/api/v1/invites', { pageSize, query: { 'project-id': projectId } }),
+      /**
+       * Mint an invite. The returned `code` is shown ONLY here — it is never
+       * stored and cannot be recovered, so build and hand off the link now.
+       * Use PlaidClient.inviteUrl() to turn it into one.
+       *
+       * Admins may mint anything. A project maintainer may mint role grants on
+       * projects they maintain, and nothing else: no admin grant, no grantless
+       * invite, no password resets.
+       * @param {object} opts
+       * @param {string} [opts.projectId] - Project the redeemer joins (with projectRole)
+       * @param {string} [opts.projectRole] - "reader" | "writer" | "maintainer"
+       * @param {boolean} [opts.grantAdmin] - Make the new account a global admin (admin only)
+       * @param {string} [opts.targetUserId] - Make this a password reset for that user (admin only)
+       * @param {number} [opts.maxUses] - How many accounts this link may create (default 1)
+       * @param {number} [opts.ttlDays] - Days until it expires (default 14, max 365)
+       * @param {string} [opts.note] - Human label shown in your invite list
+       * @returns {Promise<{id: string, code: string, kind: string, status: string}>}
+       */
+      create: ({ projectId, projectRole, grantAdmin, targetUserId, maxUses, ttlDays, note } = {}, auditMessage) =>
+        this._request('POST', '/api/v1/invites', { auditMessage,
+          body: bodyOf({
+            'project-id': projectId, 'project-role': projectRole,
+            'grant-admin': grantAdmin, 'target-user-id': targetUserId,
+            'max-uses': maxUses, 'ttl-days': ttlDays, note,
+          }),
+        }),
+      /**
+       * Revoke an invite, killing the link immediately. Idempotent. Allowed for
+       * the creator, an admin, or a maintainer of the invite's project.
+       * @param {string} id - The invite ID
+       */
+      revoke: (id, auditMessage) =>
+        this._request('DELETE', `/api/v1/invites/${id}`, { auditMessage }),
+    };
+
     this.tokenLayers = {
       /**
        * Shift a token layer's display order.
@@ -855,20 +1032,42 @@ class PlaidClient {
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
        * @param {string} [asOf] - Temporal query timestamp
+       * @param {string[]|string} [opTypes] - Only return operations of these
+       *   types, spelled as in an entry's `op/type` (e.g.
+       *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
+       *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (documentId, startTime, endTime, asOf) =>
+      audit: (documentId, startTime, endTime, asOf, opTypes) =>
         listAll(this, `/api/v1/documents/${documentId}/audit`, {
-          query: { 'start-time': startTime, 'end-time': endTime, 'as-of': asOf },
+          query: {
+            'start-time': startTime,
+            'end-time': endTime,
+            'as-of': asOf,
+            'op-types': opTypesParam(opTypes),
+          },
         }),
       /**
        * Get a document. Set `includeBody` to true to include all data.
+       *
+       * `layers` narrows a body read to the layers you name (ids of any kind:
+       * text, token, span, or relation). A layer comes back when it is named
+       * or is an ancestor of a named layer, and carries its own
+       * texts/tokens/spans/relations/vocabs only when it is itself named — so
+       * name the text layer too if you also want the text body. An id that is
+       * not a layer of this document's project is an error, not a quietly
+       * smaller response. Requires `includeBody`.
        * @param {string} documentId - The document ID
        * @param {boolean} [includeBody] - Include document body data
        * @param {string} [asOf] - Temporal query timestamp
+       * @param {string[]|string} [layers] - Layer ids to restrict a body read to
        */
-      get: (documentId, includeBody, asOf) =>
+      get: (documentId, includeBody, asOf, layers) =>
         this._request('GET', `/api/v1/documents/${documentId}`, {
-          queryParams: { 'include-body': includeBody, 'as-of': asOf },
+          queryParams: {
+            'include-body': includeBody,
+            'as-of': asOf,
+            layers: layersParam(layers),
+          },
         }),
       /**
        * Delete a document and all data contained.
@@ -969,10 +1168,19 @@ class PlaidClient {
        * @param {string} [startTime] - Start of time range
        * @param {string} [endTime] - End of time range
        * @param {string} [asOf] - Temporal query timestamp
+       * @param {string[]|string} [opTypes] - Only return operations of these
+       *   types, spelled as in an entry's `op/type` (e.g.
+       *   `['span-layer/create', 'span-layer/delete']`). An entry appears when
+       *   one of its operations matches, carrying only the ones that did.
        */
-      audit: (projectId, startTime, endTime, asOf) =>
+      audit: (projectId, startTime, endTime, asOf, opTypes) =>
         listAll(this, `/api/v1/projects/${projectId}/audit`, {
-          query: { 'start-time': startTime, 'end-time': endTime, 'as-of': asOf },
+          query: {
+            'start-time': startTime,
+            'end-time': endTime,
+            'as-of': asOf,
+            'op-types': opTypesParam(opTypes),
+          },
         }),
       /**
        * Link a vocabulary to a project.
@@ -1445,14 +1653,21 @@ class PlaidClient {
         createSSEConnection(this, projectId, onEvent, path),
 
       /**
-       * Send a message to project listeners
+       * Send a message to project listeners.
+       *
+       * `data` may be any JSON value and is sent VERBATIM (`rawBody`): a
+       * message payload is opaque application data, like `metadata` and
+       * `config`, so its keys must not be re-cased on the way out. Without
+       * this a key such as `case-marker` would reach listeners as
+       * `caseMarker` in JS and `case_marker` in Python. `listen` restores it
+       * verbatim on the way in.
        * @param {string} projectId - The UUID of the project to send to
        * @param {any} data - The message data to send
        * @returns {Promise<any>} Response from the send operation
        */
       sendMessage: (projectId, data, auditMessage) =>
         this._request('POST', `/api/v1/projects/${projectId}/message`, { auditMessage,
-          body: { body: data },
+          rawBody: { body: data },
         }),
 
       /**
@@ -1536,6 +1751,25 @@ class PlaidClient {
      */
     this.query = (body, auditMessage) =>
       this._request('POST', '/api/v1/query', { auditMessage, body });
+
+    // Logical-operation groups (audit-log grouping). There is no create: a
+    // group row is made lazily by the first write carrying `?group-id=`
+    // (see beginOperation). Not an audited write, so no auditMessage arg.
+    this.operationGroups = {
+      /**
+       * Get a logical-operation group (its label + creator).
+       * @param {string} id - The group id
+       */
+      get: (id) =>
+        this._request('GET', `/api/v1/operation-groups/${id}`),
+      /**
+       * Relabel a logical-operation group after the fact. Owner or admin only.
+       * @param {string} id - The group id
+       * @param {string|null} message - The new label
+       */
+      update: (id, message) =>
+        this._request('PATCH', `/api/v1/operation-groups/${id}`, { body: { message } }),
+    };
   }
 
   // --- Core methods ---
@@ -1559,51 +1793,94 @@ class PlaidClient {
   }
 
   /**
-   * Set a custom audit-log message applied to every subsequent write request,
-   * OVERRIDING the server's auto-generated description (e.g. "Patch metadata
-   * on span X"). The message may template the endpoint's own path/query/body
-   * params with `{param}` placeholders, resolved server-side — e.g.
-   * `"Approve span {spanId}"`. Placeholder names are case/separator-insensitive
-   * (`{spanId}` == `{span-id}` == `{span_id}`), so use the camelCase names this
-   * client uses. Applies to GET-less requests
-   * only, including every operation queued in a batch.
-   * @param {string} message - The custom message (template).
+   * Begin a LOGICAL OPERATION: a user-meaningful action ("Merge morphemes",
+   * "Re-transcribe") implemented as many low-level writes, possibly across
+   * several batches and even a service round-trip. Until `endOperation()`,
+   * every write is stamped with a client-minted `?group-id=` (and the message)
+   * so the audit log shows the whole run as ONE expandable entry labeled
+   * `message`, with each write's own description underneath.
+   *
+   * Grouping is orthogonal to batches: a batch is a transaction boundary, an
+   * operation is an intent boundary. An operation is NOT atomic — if write 3
+   * of 5 fails, writes 1–2 stay committed (and logged under the group). Use a
+   * batch inside the operation for any step that must be all-or-nothing.
+   *
+   * Nesting flattens: a `beginOperation` while one is open is a no-op that
+   * joins the outer operation (the outer label wins), and the matching
+   * `endOperation` is likewise a no-op. The label is recorded on the FIRST
+   * write, so an operation that is never ended (crash, closed tab) is still
+   * labeled in the log.
+   *
+   * @param {string} message - Human label for the operation.
+   * @param {object} [opts] - Optional `{ id }`: adopt an existing group id instead of minting one (a service joining the requester's operation; `requestService` propagates an open operation to the service automatically).
+   * @returns {string} The operation's group id.
    */
-  setAuditMessage(message) {
-    this.auditMessage = message;
-    return this;
+  beginOperation(message, { id } = {}) {
+    if (this.operationGroup) {
+      this.operationGroup.depth += 1;
+      return this.operationGroup.id;
+    }
+    this.operationGroup = {
+      id: id || crypto.randomUUID(),
+      message: message == null ? null : String(message),
+      depth: 1,
+      written: false,
+      refined: undefined,
+    };
+    return this.operationGroup.id;
   }
 
-  /** Clear the ambient custom audit-log message (revert to auto-generated). */
-  clearAuditMessage() {
-    this.auditMessage = null;
-    return this;
+  /**
+   * End the current logical operation. With no argument this is purely local
+   * (no request). Pass a refined `message` to relabel the group now that the
+   * outcome is known (e.g. `endOperation('Merged 3 morphemes')`) — that sends
+   * one PATCH, skipped if the operation never wrote anything. A refine from a
+   * nested (flattened) `endOperation` is ignored; the outer label wins.
+   * @param {string} [message] - Optional refined label.
+   * @returns {Promise<void>}
+   */
+  async endOperation(message) {
+    const group = this.operationGroup;
+    if (!group) return;
+    if (group.depth > 1) {
+      group.depth -= 1;
+      return;
+    }
+    this.operationGroup = null;
+    const refined = message !== undefined ? message : group.refined;
+    if (refined !== undefined && group.written) {
+      try {
+        await this.operationGroups.update(group.id, refined);
+      } catch (e) {
+        // 404: the group never materialized server-side (every tagged write
+        // failed or a batch was aborted). Nothing to relabel — not an error.
+        if (e.status !== 404) throw e;
+      }
+    }
   }
 
   /**
-   * Run `fn` with a custom audit-log message in effect, restoring the previous
-   * message afterward (supports nesting). Use it to scope ONE call (per-call
-   * precision) or MANY (a logical unit):
-   *
-   *   await client.withAuditMessage('Approve span {spanId}', () =>
-   *     client.spans.update(spanId, ...));
+   * Run `fn` as one logical operation (see beginOperation), ending it when
+   * `fn` settles — including on throw. `fn` receives a `setMessage(msg)`
+   * callback to refine the label once the outcome is known.
    *
-   *   await client.withAuditMessage('Import sentence', async () => {
-   *     await client.tokens.create(...);
-   *     await client.spans.create(...);
+   *   await client.withOperation('Merge morphemes', async (setMessage) => {
+   *     await client.batched(() => { ... });
+   *     setMessage(`Merged ${n} morphemes`);
    *   });
    *
-   * @param {string} message - The custom message (template).
-   * @param {() => (Promise<any>|any)} fn - The work to run with the message set.
+   * @param {string} message - Human label for the operation.
+   * @param {function} fn - The work to run; receives `setMessage(msg)` to refine the label once the outcome is known.
    * @returns {Promise<any>} Whatever `fn` resolves to.
    */
-  async withAuditMessage(message, fn) {
-    const prev = this.auditMessage;
-    this.auditMessage = message;
+  async withOperation(message, fn) {
+    this.beginOperation(message);
+    const group = this.operationGroup;
+    const setMessage = (msg) => { if (group.depth === 1) group.refined = msg; };
     try {
-      return await fn();
+      return await fn(setMessage);
     } finally {
-      this.auditMessage = prev;
+      await this.endOperation();
     }
   }
 
@@ -1739,6 +2016,64 @@ class PlaidClient {
    * @param {object} [options] - Client options forwarded to the constructor (e.g. { timeout })
    * @returns {Promise<PlaidClient>} - Authenticated client instance
    */
+  /**
+   * Build the link to hand someone for an invite code. The server never sees
+   * an app URL, so the app that minted the invite is the one that names it.
+   * Both SPAs use HashRouter, so the code rides in the fragment — which also
+   * keeps it out of server access logs.
+   * @param {string} appUrl - Where the SPA lives, e.g. "https://plaid.example.org/igt/"
+   * @param {string} code - The code returned by invites.create()
+   * @returns {string}
+   */
+  static inviteUrl(appUrl, code) {
+    return `${appUrl.replace(/#.*$/, '').replace(/\/$/, '')}/#/invite/${encodeURIComponent(code)}`;
+  }
+
+  /**
+   * Describe an invite code, with NO authentication — this is what a signup
+   * page calls before the redeemer has an account. Returns the kind of link
+   * ("signup" or "password-reset"), its status ("active", "used", "expired",
+   * "revoked"), and the project it grants access to, if any.
+   *
+   * Throws a 404-shaped error if the code is unknown. A known-but-dead code
+   * resolves normally with a non-"active" status, so the page can say why.
+   * @param {string} baseUrl - The API base URL
+   * @param {string} code - The invite code
+   * @param {object} [options]
+   * @returns {Promise<{kind: string, status: string, expiresAt: string, projectName?: string, projectRole?: string, username?: string, grantAdmin: boolean}>}
+   */
+  static async lookupInvite(baseUrl, code, options = {}) {
+    return anonymousPost(baseUrl, '/api/v1/invite-codes/lookup', { code }, options);
+  }
+
+  /**
+   * Redeem an invite code, with NO authentication.
+   *
+   * For a signup invite, pass `username` and `password` to create the account;
+   * the invite's grants are applied in the same transaction. For a password
+   * reset link, pass `password` only. Resolves to a logged-in client, exactly
+   * like login() — the redeemer just chose these credentials, so there is no
+   * reason to send them to a login form to retype them.
+   * @param {string} baseUrl - The API base URL
+   * @param {string} code - The invite code
+   * @param {object} credentials
+   * @param {string} [credentials.username] - Desired username (signup only)
+   * @param {string} credentials.password - Desired password (min 8 characters)
+   * @param {object} [options]
+   * @returns {Promise<{client: PlaidClient, userId: string, kind: string}>}
+   */
+  static async redeemInvite(baseUrl, code, { username, password } = {}, options = {}) {
+    const data = await anonymousPost(
+      baseUrl, '/api/v1/invite-codes/redeem',
+      bodyOf({ code, username, password }), options,
+    );
+    return {
+      client: new PlaidClient(baseUrl.replace(/\/$/, ''), data.token || '', options),
+      userId: data.userId,
+      kind: data.kind,
+    };
+  }
+
   static async login(baseUrl, userId, password, options = {}) {
     baseUrl = baseUrl.replace(/\/$/, '');
     const url = `${baseUrl}/api/v1/login`;
@@ -1792,9 +2127,11 @@ export {
 export {
   PROV,
   PROV_STATES,
+  PROV_CONFIRMED,
   stampInferred,
   confirmedInferred,
   provState,
+  isMachine,
   isProtected,
   verifyOnEdit,
   serviceSource,

package/src/provenance.js

@@ -95,6 +95,16 @@ export const confirmedInferred = (source, extras = {}) => ({
   [PROV.confirmedKey]: true,
 });
 
+/**
+ * The metadata fragment that verifies machine-made material:
+ * { provConfirmed: true }. Merge (PATCH) it over existing metadata so
+ * prov/provSource/provProb/provDetail survive. This is what verifyOnEdit
+ * returns for machine-unverified material; use it directly for explicit
+ * confirmation gestures (a "confirm" button, confirm-on-touch) where the
+ * caller has already checked isMachine.
+ */
+export const PROV_CONFIRMED = Object.freeze({ [PROV.confirmedKey]: true });
+
 /**
  * Classify an entity's metadata into one of PROV_STATES.
  * @param {Object|null|undefined} metadata
@@ -105,19 +115,25 @@ export const provState = (metadata) => {
   return metadata[PROV.confirmedKey] ? PROV_STATES.VERIFIED : PROV_STATES.MACHINE;
 };
 
+/**
+ * Whether this entity is machine-made and not yet human-verified — the
+ * material that still needs review, that machine writers may replace, and
+ * that a human confirmation gesture acts on. Complement of isProtected.
+ */
+export const isMachine = (metadata) => provState(metadata) === PROV_STATES.MACHINE;
+
 /**
  * Whether a machine writer must leave this entity alone (write-contract
  * rule 2): true for human-made and human-verified material.
  */
-export const isProtected = (metadata) => provState(metadata) !== PROV_STATES.MACHINE;
+export const isProtected = (metadata) => !isMachine(metadata);
 
 /**
  * The metadata fragment a HUMAN edit of this entity should merge in
- * (write-contract rule 3): { provConfirmed: true } when the entity is
- * machine-made and unverified, else null (nothing to do).
+ * (write-contract rule 3): PROV_CONFIRMED when the entity is machine-made
+ * and unverified, else null (nothing to do).
  */
-export const verifyOnEdit = (metadata) =>
-  (provState(metadata) === PROV_STATES.MACHINE ? { [PROV.confirmedKey]: true } : null);
+export const verifyOnEdit = (metadata) => (isMachine(metadata) ? PROV_CONFIRMED : null);
 
 /** Canonical provSource for a service: 'service:<serviceId>'. */
 export const serviceSource = (serviceId) => `service:${serviceId}`;

package/src/serviceSchema.js

@@ -48,6 +48,8 @@ export const TASKS = Object.freeze({
   TRANSCRIBE: 'transcribe',
   /** Create vocab links for unlinked tokens. */
   LINK_VOCAB: 'link-vocab',
+  /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
+  ANALYZE: 'analyze',
 });
 
 /**

package/src/services.js

@@ -147,6 +147,16 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * @returns {Promise<any>} The service's result
  */
 export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress) {
+  // Propagate an open logical operation (client.beginOperation) to the
+  // service: its writes then fold under the requester's audit-log entry
+  // (the Python BaseService adopts the id around process_request). Only for a
+  // plain-object payload — that's the only shape the service param schema
+  // delivers anyway.
+  const group = client.operationGroup;
+  const payload =
+    group && data && typeof data === 'object' && !Array.isArray(data)
+      ? { ...data, operationGroup: { id: group.id, message: group.message } }
+      : data;
   return new Promise((resolve, reject) => {
     const abortController = new AbortController();
     let settled = false;
@@ -174,7 +184,7 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
               'Content-Type': 'application/json',
               'Accept': 'text/event-stream',
             },
-            body: JSON.stringify(data === undefined ? null : transformRequest(data)),
+            body: JSON.stringify(payload === undefined ? null : transformRequest(payload)),
             signal: abortController.signal,
           },
         );

package/src/sse.js

@@ -1,5 +1,24 @@
 import { transformResponse } from './transforms.js';
 
+/**
+ * Project a parsed SSE `data:` object onto what a listener callback sees.
+ *
+ * The envelope is API surface and gets the usual `transformResponse` recasing.
+ * A `message` event's `data` is NOT: it is opaque application data (whatever
+ * `sendMessage` was handed), so its keys must survive verbatim, exactly as
+ * `metadata` and `config` do elsewhere. Without this, a key written
+ * `case-marker` reaches a JavaScript listener as `caseMarker` and a Python
+ * listener as `case_marker`, so the same broadcast reads differently depending
+ * on the reader's language.
+ */
+export function eventPayload(eventType, parsed) {
+  const payload = transformResponse(parsed);
+  if (eventType === 'message' && parsed && typeof parsed === 'object' && 'data' in parsed) {
+    payload.data = parsed.data;
+  }
+  return payload;
+}
+
 /**
  * Create an SSE connection to the listen endpoint using fetch-based streaming.
  * Automatically handles heartbeat confirmations and event parsing.
@@ -124,7 +143,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
                 sendHeartbeatConfirmation();
               } else {
                 const parsedData = JSON.parse(data);
-                const shouldStop = onEvent(eventType, transformResponse(parsedData));
+                const shouldStop = onEvent(eventType, eventPayload(eventType, parsedData));
                 if (shouldStop === true) {
                   sseConnection.close();
                   return;