@larc-iu/plaid-client 0.2.0-alpha.4 → 0.2.0-alpha.6

package/index.d.ts

@@ -305,6 +305,54 @@ interface UserDataBundle {
   delete(userId: string, key: string): Promise<any>;
 }
 
+interface CommentFilters {
+  documentId?: string;
+  entityType?: CommentableType;
+  entityId?: string;
+}
+
+/** Entities that can carry a comment. */
+type CommentableType = "document" | "text" | "token" | "span" | "relation";
+
+interface Comment {
+  id: string;
+  projectId: string;
+  documentId: string;
+  entityType: CommentableType;
+  entityId: string;
+  authorId: string;
+  body: string;
+  createdAt: string;
+  updatedAt: string;
+  /** True once the body has been rewritten since it was posted. */
+  edited: boolean;
+}
+
+interface CommentsBundle {
+  create(
+    entityType: CommentableType,
+    entityId: string,
+    body: string,
+  ): Promise<Comment>;
+  get(id: string): Promise<Comment>;
+  update(id: string, body: string): Promise<Comment>;
+  delete(id: string): Promise<any>;
+  list(projectId: string, filters?: CommentFilters): Promise<Comment[]>;
+  listPage(
+    projectId: string,
+    opts?: CommentFilters & { limit?: number; cursor?: string },
+  ): Promise<Page<Comment>>;
+  iterPages(
+    projectId: string,
+    opts?: CommentFilters & { pageSize?: number },
+  ): AsyncGenerator<Comment[]>;
+  /** `{entityId: count}`; keys are raw entity ids, never key-transformed. */
+  counts(
+    projectId: string,
+    filters?: CommentFilters,
+  ): Promise<Record<string, number>>;
+}
+
 interface ApiTokensBundle {
   list(userId: string): Promise<any[]>;
   listPage(
@@ -769,6 +817,7 @@ export declare class PlaidClient {
   apiTokens: ApiTokensBundle;
   userData: UserDataBundle;
   invites: InvitesBundle;
+  comments: CommentsBundle;
   tokenLayers: TokenLayersBundle;
   documents: DocumentsBundle;
   messages: MessagesBundle;

package/package.json

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

package/src/http.js

@@ -132,6 +132,13 @@ export function timeoutSignal(timeout) {
  *   formData        - If true, body is FormData; skip Content-Type header
  *   queryParams     - Object of query param key/values to append
  *   noBatch         - If true, throw when in batch mode
+ *   bypassBatch     - If true, go over the wire even while a batch is open.
+ *                     For READS only: a batch is a write transaction, its
+ *                     ops return no value to their caller until submit, and
+ *                     the sub-request runs against the tx Connection rather
+ *                     than the pool. A read swallowed by an ambient batch is
+ *                     therefore useless to the caller AND can fail the whole
+ *                     batch (see `query`).
  *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
  *   noAuth          - Skip Authorization header
  *   binaryResponse  - Return arrayBuffer instead of JSON/text
@@ -146,6 +153,7 @@ export async function makeRequest(client, method, path, options = {}) {
     formData,
     queryParams,
     noBatch,
+    bypassBatch,
     skipResponseTransform,
     noAuth,
     binaryResponse,
@@ -219,8 +227,11 @@ export async function makeRequest(client, method, path, options = {}) {
     group.written = true;
   }
 
-  // Batch mode
-  if (client.isBatching) {
+  // Batch mode. A `bypassBatch` read is deliberately NOT queued: it belongs to
+  // whoever called it, not to whatever batch happens to be open on this shared
+  // client (a document reconcile, an import), and it reads the pre-batch state
+  // exactly as it would have if the batch were not running.
+  if (client.isBatching && !bypassBatch) {
     if (noBatch) {
       throw new Error(`This endpoint cannot be used in batch mode: ${path}`);
     }

package/src/index.js

@@ -2149,8 +2149,14 @@ class PlaidClient {
      *   For 'count': {return: 'count', count}. Entity cells are full entity objects
      *   (same shape as the GET endpoints).
      */
+    // bypassBatch: a query is a read. `client.batched()` flips one flag on the
+    // whole client, so a query issued by unrelated code while a batch is open
+    // (the IGT island fetching precedent while a document reconciles) used to
+    // be queued into it: the caller got `{batched: true}` instead of results,
+    // and the server ran the query against the batch's tx Connection, which
+    // 500s and rolls back every write in that batch.
     this.query = (body, auditMessage) =>
-      this._request("POST", "/api/v1/query", { auditMessage, body });
+      this._request("POST", "/api/v1/query", { auditMessage, body, bypassBatch: true });
 
     // Logical-operation groups (audit-log grouping). There is no create: a
     // group row is made lazily by the first write carrying `?group-id=`
@@ -2171,6 +2177,120 @@ class PlaidClient {
           body: { message },
         }),
     };
+
+    this.comments = {
+      /**
+       * Post a comment on an entity. Requires write access to the entity's
+       * project; the author is the authenticated caller. Comments are not
+       * audited and do not bump the document version.
+       * @param {'document'|'text'|'token'|'span'|'relation'} entityType - What kind of thing is being commented on
+       * @param {string} entityId - The commented entity's id
+       * @param {string} body - The comment text (1..10000 characters)
+       */
+      create: (entityType, entityId, body) =>
+        this._request("POST", "/api/v1/comments", {
+          body: bodyOf({ "entity-type": entityType, "entity-id": entityId, body }),
+        }),
+      /**
+       * Read one comment.
+       * @param {string} id - The comment id
+       */
+      get: (id) => this._request("GET", `/api/v1/comments/${id}`),
+      /**
+       * Edit a comment's body. Only the comment's AUTHOR may do this - not
+       * maintainers, not admins. Sets `edited` on the comment.
+       * @param {string} id - The comment id
+       * @param {string} body - The replacement text
+       */
+      update: (id, body) =>
+        this._request("PATCH", `/api/v1/comments/${id}`, { body: { body } }),
+      /**
+       * Delete a comment. The author may delete their own; a project
+       * maintainer (or admin) may delete any.
+       * @param {string} id - The comment id
+       */
+      delete: (id) => this._request("DELETE", `/api/v1/comments/${id}`),
+      /**
+       * List comments in a project, oldest first. 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 {string} projectId - The project to read
+       * @param {object} [filters] - Narrow the scope
+       * @param {string} [filters.documentId] - Every comment anywhere in one document
+       * @param {string} [filters.entityType] - With entityId, one entity's thread
+       * @param {string} [filters.entityId] - With entityType, one entity's thread
+       */
+      list: (projectId, { documentId, entityType, entityId } = {}) =>
+        listAll(this, `/api/v1/projects/${projectId}/comments`, {
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Fetch a single page of a project's comments.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @param {string} [opts.documentId] - Every comment anywhere in one document
+       * @param {string} [opts.entityType] - With entityId, one entity's thread
+       * @param {string} [opts.entityId] - With entityType, one entity's thread
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: (projectId, { limit, cursor, documentId, entityType, entityId } = {}) =>
+        listPage(this, `/api/v1/projects/${projectId}/comments`, {
+          limit,
+          cursor,
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Async-iterate a project's comments page by page; yields each page's entries array.
+       * 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.
+       * @param {string} projectId - The project to read
+       * @param {object} [opts]
+       * @param {number} [opts.pageSize] - Per-request page size
+       * @param {string} [opts.documentId] - Every comment anywhere in one document
+       * @param {string} [opts.entityType] - With entityId, one entity's thread
+       * @param {string} [opts.entityId] - With entityType, one entity's thread
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: (projectId, { pageSize, documentId, entityType, entityId } = {}) =>
+        iterPages(this, `/api/v1/projects/${projectId}/comments`, {
+          pageSize,
+          query: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+        }),
+      /**
+       * Comment counts per entity, as an `{entityId: n}` map, over the same
+       * scope and filters as `list`. One cheap request paints a comment
+       * indicator on every annotated item in a document without paging
+       * through the bodies.
+       *
+       * The response is NOT key-transformed: its keys are entity ids, and
+       * camelCasing would mangle the hyphens in a UUID.
+       * @param {string} projectId - The project to read
+       * @param {object} [filters] - Same filters as list()
+       * @returns {Promise<Object<string, number>>}
+       */
+      counts: (projectId, { documentId, entityType, entityId } = {}) =>
+        this._request("GET", `/api/v1/projects/${projectId}/comments/counts`, {
+          queryParams: {
+            "document-id": documentId,
+            "entity-type": entityType,
+            "entity-id": entityId,
+          },
+          skipResponseTransform: true,
+        }),
+    };
   }
 
   // --- Core methods ---