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

package/index.d.ts

@@ -469,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;

package/package.json

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

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 = {};
@@ -629,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
@@ -1005,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.
@@ -1119,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.
@@ -1595,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 },
         }),
 
       /**

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/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;