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

package/src/services.d.ts

@@ -0,0 +1,302 @@
+/**
+ * One line about a failure that is safe to show the person who asked.
+ *
+ * Strips absolute URLs (so an internal host never reaches a requester's screen)
+ * and any `secrets` given (a model provider's API key can come back inside its
+ * own error text). The whole error still goes to the operator's console: this
+ * is the requester's half only. The Python twin is `requester_message`.
+ *
+ * Only a connection that never opened is "could not be reached". A write whose
+ * answer never came (a reset, a timeout) may have been saved, and says so
+ * (`UNKNOWN_OUTCOME`).
+ *
+ * @param {any} error
+ * @param {string[]} [secrets]
+ * @returns {string}
+ */
+export function requesterMessage(error: any, secrets?: string[]): string;
+/**
+ * What the requester is told when a request fails, named by the service.
+ *
+ * Every path that reports a failed request goes through here, so a raw message
+ * cannot reach a requester from one of them. (Python's twin additionally lets a
+ * `ValueError` through unprefixed, as an authored refusal; JS has no
+ * distinguished refusal type, so every failure is named by the service.)
+ *
+ * @param {any} error
+ * @param {string} [serviceName]
+ * @param {string[]} [secrets]
+ * @returns {string}
+ */
+export function serviceErrorMessage(error: any, serviceName?: string, secrets?: string[]): string;
+/**
+ * Discover the services seen on a project — a synchronous GET. Returns every
+ * service ever registered on the project: currently connected ones carry
+ * `online: true`; previously-seen offline ones carry `online: false` plus a
+ * `lastSeenAt` stamp. Callers that need a service they can actually submit
+ * work to should filter on `online`. A connected service also names who runs
+ * it, as the caller sees it: `runnerName` (the runner's display name),
+ * `runByYou`, and `servesYou`, whether it would take the caller's requests on
+ * this project. A delegating service serves members other than its runner
+ * only where the runner is a maintainer or an admin. Goes over the wire even
+ * while a batch is open on the client.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt, runnerName, runByYou, servesYou}]
+ */
+export function discoverServices(client: any, projectId: string): Promise<any[]>;
+/**
+ * Forget a previously-seen (offline) service: removes its row from the
+ * project's persistent registry. Maintainer-only; 409 if the service is
+ * currently connected (it would just re-register).
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} serviceId - Service ID to forget
+ * @returns {Promise<void>}
+ */
+export function discardService(client: any, projectId: string, serviceId: string): Promise<void>;
+/**
+ * POST a progress, result or error event for an in-flight request; the server
+ * relays it to the waiting requester. The Python twin is `_report_event`.
+ *
+ * outOfBand: these are signals to whoever is waiting, not writes to the
+ * project (see the note at the top of http.js). A service may report them on
+ * the batch it is filling, where queueing them would hold every one back until
+ * submit, deliver none at all if the batch aborts, and take slots in the
+ * batch's results. The requester would hear nothing and wait out its idle
+ * timeout on work that had already finished.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} requestId - The request id
+ * @param {Object} body - The event payload
+ * @returns {Promise<any>}
+ */
+export function reportRequestEvent(client: any, projectId: string, requestId: string, body: any): Promise<any>;
+/**
+ * The cancellation half of a responseHelper, on its own.
+ * @typedef {object} CancelScope
+ * @property {boolean} cancelled True once the requester has asked this request
+ *   to stop.
+ * @property {() => void} raiseIfCancelled Stop here if the requester has asked
+ *   the request to stop.
+ * @property {<T>(fn: () => T | Promise<T>) => Promise<T>} critical Run `fn` as
+ *   a stretch that must finish once begun, usually the writes.
+ */
+/**
+ * What a `serve` handler gets for each request.
+ * @typedef {CancelScope & {
+ *   requestId: string,
+ *   requesterId: string | null,
+ *   progress(percent: number, message: string, extra?: Record<string, any>): void,
+ *   complete(data: any): void,
+ *   stopped(data?: any): void,
+ *   error(error: string | Error): void,
+ * }} ResponseHelper `progress` is also a cancellation checkpoint: it throws
+ *   `ServiceCancelled` once a stop has been asked for. `stopped` ends the
+ *   request because it was asked to stop, and its result carries `stopped: true`.
+ */
+/**
+ * A connection-state transition of a service registration. "stopped": the
+ * server refused the channel for a reason retrying cannot fix (a revoked
+ * token, no write access, no such project), which ends the registration.
+ * @typedef {"registered" | "reconnected" | "disconnected" | "stopped"} ServiceStatusEvent
+ */
+/**
+ * What `serve` returns.
+ * @typedef {object} ServiceRegistration
+ * @property {() => void} stop
+ * @property {() => boolean} isRunning Still serving, including while retrying
+ *   a channel through a server restart.
+ * @property {() => boolean} isConnected Channel open right now, so the server
+ *   sees this service as online.
+ * @property {import("./serviceSchema.js").ServiceInfo & {extras: any}} serviceInfo
+ */
+/**
+ * Register a service and handle incoming work requests.
+ *
+ * Opens the service's dedicated request channel — which registers it for
+ * discovery (presence = open channel) — and handles work on it. For each
+ * request, runs `onServiceRequest(data, responseHelper)` where `responseHelper`
+ * has `progress(percent, msg)` / `complete(data)` / `error(err)`.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {import("./serviceSchema.js").ServiceInfo} serviceInfo - {serviceId, serviceName, description}
+ * @param {(data: any, responseHelper: ResponseHelper) => void} onServiceRequest - Handler callback (data, responseHelper)
+ * @param {Object} [extras] - Optional additional metadata
+ * @param {((event: ServiceStatusEvent, projectId: string, detail?: string) => void) | null} [onStatus] - Optional callback (event, projectId, detail) for
+ *   connection-state transitions: 'registered', 'reconnected', 'disconnected',
+ *   and 'stopped' when the server refuses the channel for a reason retrying
+ *   cannot fix (see PERMANENT_STATUSES), which ends the registration.
+ *   Called once per transition, not once per retry.
+ * @returns {ServiceRegistration}
+ */
+export function serve(client: any, projectId: string, serviceInfo: import("./serviceSchema.js").ServiceInfo, onServiceRequest: (data: any, responseHelper: ResponseHelper) => void, extras?: any, onStatus?: ((event: ServiceStatusEvent, projectId: string, detail?: string) => void) | null): ServiceRegistration;
+/**
+ * Submit work to a service and await its result.
+ *
+ * Streams the service's progress + result back over a single server-mediated
+ * response (no broadcast). Rejects if no service is connected (503), if the
+ * service reports an error, or after `timeout` of SILENCE.
+ *
+ * The request outlives this call: after a timeout, an abort, or a dropped
+ * connection the service goes on, and `attachServiceRequest` collects the
+ * result given the request id, which `opts.onAccepted` receives as soon as
+ * the server has taken the request. Pass `opts.requestId` (a UUID you mint)
+ * to know the id before submitting; submitting an id that names a request
+ * you already made rejoins it instead of starting another.
+ *
+ * Errors that leave the request alive carry `pending: true`: a timeout, a
+ * stop, a dropped connection, a proxy's 502 or 504. An error without it is
+ * the end of the request. With `opts.requestId`, a request whose answer went
+ * missing (a dropped connection, a 502 or 504) is rejoined by that id a few
+ * times before the error is given.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} serviceId - Service ID to request
+ * @param {any} data - Request payload
+ * @param {number} [timeout=10000] - How long the service may say NOTHING, in ms.
+ *   Every event it sends starts the clock again, so this does not cap a long run.
+ *   0, a negative number or null: no limit (wait until `signal` stops it)
+ * @param {function} [onProgress] - Called with each progress payload {percent, message}
+ * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
+ * @param {Object} [opts]
+ * @param {string} [opts.requestId] - A client-minted request id (UUID)
+ * @param {function} [opts.onAccepted] - Called with the request id once the server has it
+ * @param {string[]} [opts.projectIds] - Other projects the request is about, beside
+ *   `projectId`. A delegating service's token is scoped to `projectId` and to those of
+ *   these the requester can read, and reaches nothing else
+ * @param {boolean} [opts.noOperation] - Carry no open operation: the service's writes
+ *   are a group of their own, not part of whatever operation this client has open
+ * @returns {Promise<any>} The service's result
+ */
+export function requestService(client: any, projectId: string, serviceId: string, data: any, timeout?: number, onProgress?: Function, signal?: AbortSignal, opts?: {
+    requestId?: string;
+    onAccepted?: Function;
+    projectIds?: string[];
+    noOperation?: boolean;
+}): Promise<any>;
+/**
+ * Rejoin a service request made earlier (by this user) and await its result:
+ * the latest progress is replayed, then the result comes, or at once if the
+ * request already finished. Rejects with an error whose `status` is 404 when
+ * the request is unknown or expired (the server keeps a finished request's
+ * result for a while, not forever). As with `requestService`, `timeout` is
+ * how long the service may be silent, and an error carrying `pending: true`
+ * means the request is still there to rejoin again.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} requestId - The request id (from `onAccepted` or your own)
+ * @param {number} [timeout=10000] - How long the service may say NOTHING, in ms
+ *   (0, a negative number or null: no limit)
+ * @param {function} [onProgress] - Called with each progress payload {percent, message}
+ * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
+ * @returns {Promise<any>} The service's result
+ */
+export function attachServiceRequest(client: any, projectId: string, requestId: string, timeout?: number, onProgress?: Function, signal?: AbortSignal): Promise<any>;
+/**
+ * The cancellation half of a responseHelper: a flag, a depth counter, and one
+ * rule about when a checkpoint may raise. Split from the transport so it can
+ * be reasoned about on its own. Mirrors `CancelScope` in the Python client.
+ * @param {() => boolean} isCancelled
+ * @returns {CancelScope}
+ */
+export function createCancelScope(isCancelled: () => boolean): CancelScope;
+/**
+ * Ask the service to stop a request made earlier (by this user). The request
+ * still ends with whatever the service then reports, on the stream of whoever
+ * is awaiting it. Rejects with 404 if unknown or expired, 409 once finished.
+ *
+ * outOfBand: a DELETE, but not a write. It signals a running service and
+ * changes no project data (see the note at the top of http.js).
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} requestId - The request id
+ * @returns {Promise<void>}
+ */
+export function cancelServiceRequest(client: any, projectId: string, requestId: string): Promise<void>;
+/**
+ * What a requester is told when an error carries no message of its own.
+ * Naming the JS class instead would say nothing they can act on.
+ */
+export const UNKNOWN_FAILURE: "The service could not finish this request.";
+/** A write sent to the server whose answer never came back. */
+export const UNKNOWN_OUTCOME: "The Plaid server did not answer. This change may or may not have been saved.";
+/** The server was never reached, so nothing was sent. */
+export const UNREACHABLE: "The Plaid server could not be reached.";
+/**
+ * Thrown inside a handler when the requester has asked it to stop.
+ *
+ * Cooperative cancellation: nothing interrupts a handler, so the request ends
+ * at the next point the handler looks. `responseHelper.progress` is that
+ * point, which is why a long service that already reports progress needs no
+ * changes at all. `serve` catches this and ends the request as STOPPED rather
+ * than failed.
+ */
+export class ServiceCancelled extends Error {
+    constructor(message?: string);
+}
+/**
+ * The cancellation half of a responseHelper, on its own.
+ */
+export type CancelScope = {
+    /**
+     * True once the requester has asked this request
+     * to stop.
+     */
+    cancelled: boolean;
+    /**
+     * Stop here if the requester has asked
+     * the request to stop.
+     */
+    raiseIfCancelled: () => void;
+    /**
+     * Run `fn` as
+     * a stretch that must finish once begun, usually the writes.
+     */
+    critical: <T>(fn: () => T | Promise<T>) => Promise<T>;
+};
+/**
+ * `progress` is also a cancellation checkpoint: it throws
+ *   `ServiceCancelled` once a stop has been asked for. `stopped` ends the
+ *   request because it was asked to stop, and its result carries `stopped: true`.
+ */
+export type ResponseHelper = CancelScope & {
+    requestId: string;
+    requesterId: string | null;
+    progress(percent: number, message: string, extra?: Record<string, any>): void;
+    complete(data: any): void;
+    stopped(data?: any): void;
+    error(error: string | Error): void;
+};
+/**
+ * A connection-state transition of a service registration. "stopped": the
+ * server refused the channel for a reason retrying cannot fix (a revoked
+ * token, no write access, no such project), which ends the registration.
+ */
+export type ServiceStatusEvent = "registered" | "reconnected" | "disconnected" | "stopped";
+/**
+ * What `serve` returns.
+ */
+export type ServiceRegistration = {
+    stop: () => void;
+    /**
+     * Still serving, including while retrying
+     * a channel through a server restart.
+     */
+    isRunning: () => boolean;
+    /**
+     * Channel open right now, so the server
+     * sees this service as online.
+     */
+    isConnected: () => boolean;
+    serviceInfo: import("./serviceSchema.js").ServiceInfo & {
+        extras: any;
+    };
+};

package/src/services.js

@@ -132,12 +132,16 @@ export function serviceErrorMessage(error, serviceName = '', secrets = []) {
  * service ever registered on the project: currently connected ones carry
  * `online: true`; previously-seen offline ones carry `online: false` plus a
  * `lastSeenAt` stamp. Callers that need a service they can actually submit
- * work to should filter on `online`. Goes over the wire even while a batch is
- * open on the client.
+ * work to should filter on `online`. A connected service also names who runs
+ * it, as the caller sees it: `runnerName` (the runner's display name),
+ * `runByYou`, and `servesYou`, whether it would take the caller's requests on
+ * this project. A delegating service serves members other than its runner
+ * only where the runner is a maintainer or an admin. Goes over the wire even
+ * while a batch is open on the client.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
- * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt}]
+ * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt, runnerName, runByYou, servesYou}]
  */
 export function discoverServices(client, projectId) {
   return client._request('GET', `/api/v1/projects/${projectId}/services`);
@@ -193,6 +197,49 @@ export function reportRequestEvent(client, projectId, requestId, body) {
  */
 const PERMANENT_STATUSES = new Set([400, 401, 403, 404, 405, 422]);
 
+/**
+ * The cancellation half of a responseHelper, on its own.
+ * @typedef {object} CancelScope
+ * @property {boolean} cancelled True once the requester has asked this request
+ *   to stop.
+ * @property {() => void} raiseIfCancelled Stop here if the requester has asked
+ *   the request to stop.
+ * @property {<T>(fn: () => T | Promise<T>) => Promise<T>} critical Run `fn` as
+ *   a stretch that must finish once begun, usually the writes.
+ */
+
+/**
+ * What a `serve` handler gets for each request.
+ * @typedef {CancelScope & {
+ *   requestId: string,
+ *   requesterId: string | null,
+ *   progress(percent: number, message: string, extra?: Record<string, any>): void,
+ *   complete(data: any): void,
+ *   stopped(data?: any): void,
+ *   error(error: string | Error): void,
+ * }} ResponseHelper `progress` is also a cancellation checkpoint: it throws
+ *   `ServiceCancelled` once a stop has been asked for. `stopped` ends the
+ *   request because it was asked to stop, and its result carries `stopped: true`.
+ */
+
+/**
+ * A connection-state transition of a service registration. "stopped": the
+ * server refused the channel for a reason retrying cannot fix (a revoked
+ * token, no write access, no such project), which ends the registration.
+ * @typedef {"registered" | "reconnected" | "disconnected" | "stopped"} ServiceStatusEvent
+ */
+
+/**
+ * What `serve` returns.
+ * @typedef {object} ServiceRegistration
+ * @property {() => void} stop
+ * @property {() => boolean} isRunning Still serving, including while retrying
+ *   a channel through a server restart.
+ * @property {() => boolean} isConnected Channel open right now, so the server
+ *   sees this service as online.
+ * @property {import("./serviceSchema.js").ServiceInfo & {extras: any}} serviceInfo
+ */
+
 /**
  * Register a service and handle incoming work requests.
  *
@@ -203,16 +250,15 @@ const PERMANENT_STATUSES = new Set([400, 401, 403, 404, 405, 422]);
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
- * @param {Object} serviceInfo - {serviceId, serviceName, description}
- * @param {function} onServiceRequest - Handler callback (data, responseHelper)
- * @param {Object} extras - Optional additional metadata
- * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
+ * @param {import("./serviceSchema.js").ServiceInfo} serviceInfo - {serviceId, serviceName, description}
+ * @param {(data: any, responseHelper: ResponseHelper) => void} onServiceRequest - Handler callback (data, responseHelper)
+ * @param {Object} [extras] - Optional additional metadata
+ * @param {((event: ServiceStatusEvent, projectId: string, detail?: string) => void) | null} [onStatus] - Optional callback (event, projectId, detail) for
  *   connection-state transitions: 'registered', 'reconnected', 'disconnected',
  *   and 'stopped' when the server refuses the channel for a reason retrying
  *   cannot fix (see PERMANENT_STATUSES), which ends the registration.
  *   Called once per transition, not once per retry.
- * @returns {Object} ServiceRegistration with .stop(), .isRunning(), .isConnected(),
- *   .serviceInfo
+ * @returns {ServiceRegistration}
  */
 export function serve(client, projectId, serviceInfo, onServiceRequest, extras = {}, onStatus = null) {
   const { serviceId, serviceName, description = '' } = serviceInfo;
@@ -327,11 +373,25 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
       // requester has stopped the request, so a service that reports progress
       // through its work is cancellable without doing anything else. Use
       // `critical()` around writes to hold it off.
+      //
+      // A request the server answers 404 for is one it no longer knows (it
+      // ended, or the server restarted and forgot it), so nobody is waiting
+      // for the work: it counts as a stop, and the next checkpoint throws.
+      // Any other failure to send is only logged.
       progress: (percent, msg, extra) => {
         scope.raiseIfCancelled();
-        return reportEvent(requestId, {
+        return reportRequestEvent(client, projectId, requestId, {
           status: 'progress',
           progress: { percent, message: msg, ...extra },
+        }).catch((error) => {
+          if (error?.status === 404) {
+            if (cancelled.get(requestId) === false) {
+              console.warn(`The server no longer knows request ${requestId}, so it is stopped`);
+              cancelled.set(requestId, true);
+            }
+            return;
+          }
+          console.warn('Failed to report request event:', error.message || error);
         });
       },
       complete: (data) => {
@@ -573,6 +633,8 @@ export class ServiceCancelled extends Error {
  * The cancellation half of a responseHelper: a flag, a depth counter, and one
  * rule about when a checkpoint may raise. Split from the transport so it can
  * be reasoned about on its own. Mirrors `CancelScope` in the Python client.
+ * @param {() => boolean} isCancelled
+ * @returns {CancelScope}
  */
 export function createCancelScope(isCancelled) {
   // Depth of nested `critical()` blocks; while non-zero, a checkpoint will
@@ -767,8 +829,17 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
         return;
       }
       if (!response.ok) {
-        const err = new Error(`${what} failed: HTTP ${response.status} ${response.statusText}`);
+        // A refusal says why in its body (`{error}`), as on every other route.
+        let said = null;
+        try {
+          said = await response.json();
+        } catch {
+          said = null;
+        }
+        const why = typeof said?.error === 'string' ? `: ${said.error}` : '';
+        const err = new Error(`${what} failed: HTTP ${response.status} ${response.statusText}${why}`);
         err.status = response.status;
+        if (said && typeof said === 'object') err.responseData = said;
         // A proxy's 502 or 504 is no answer from the server: the request may
         // have been taken, and the service may be running it.
         finish(reject, response.status === 502 || response.status === 504 ? lostAnswer(err) : err);

package/src/sse.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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: any, parsed: any): any;
+/**
+ * Create an SSE connection to the listen endpoint using fetch-based streaming.
+ * Automatically handles heartbeat confirmations and event parsing.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {function} onEvent - Callback (eventType, data). Return true to stop.
+ * @param {string} [path] - Stream path under baseUrl. Defaults to the project
+ *   /listen bus; service request channels pass their own. Only /listen emits
+ *   `heartbeat` events needing a POST confirmation — other streams keep
+ *   themselves alive with ignored SSE comments.
+ * @returns {Object} SSE connection with .close(), .getStats(), .readyState,
+ *   and .error: once CLOSED, why (null when this side closed it). A refused
+ *   stream's error carries the HTTP `status`, and a stream the server ended
+ *   carries an error named `StreamClosed`.
+ */
+export function createSSEConnection(client: any, projectId: string, onEvent: Function, path?: string): any;
+export const SSE_IDLE_TIMEOUT_MS: 60000;

package/src/sse.js

@@ -36,6 +36,12 @@ export function eventPayload(eventType, parsed) {
   return payload;
 }
 
+// Tell the client a stream of its own dropped or opened (a stand-in client in
+// a test may not listen).
+function tell(client, hook) {
+  try { client[hook]?.(); } catch (_) { /* the stream must not die of it */ }
+}
+
 /**
  * Create an SSE connection to the listen endpoint using fetch-based streaming.
  * Automatically handles heartbeat confirmations and event parsing.
@@ -147,6 +153,8 @@ export function createSSEConnection(client, projectId, onEvent, path) {
       isConnected = true;
       sseConnection.readyState = 1; // OPEN
       lastWarning.delete(url);
+      // After a drop the server may have restarted with other limits.
+      tell(client, '_noteStreamOpened');
 
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
@@ -219,10 +227,13 @@ export function createSSEConnection(client, projectId, onEvent, path) {
         }
       }
     } finally {
+      // Ended without a close() of this side's own: a drop.
+      const dropped = !isClosed;
       clearIdleTimer();
       isConnected = false;
       isClosed = true;
       sseConnection.readyState = 2; // CLOSED
+      if (dropped) tell(client, '_noteStreamDropped');
     }
   })();
 

package/src/textEdits.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The code points of `body`, as a frozen array shared with other callers.
+ * @param {string} body
+ * @returns {readonly string[]}
+ */
+export function bodyCodePoints(body: string): readonly string[];
+/**
+ * The net change of `ops` applied in turn to `body`, as gaps in the old
+ * body's code points: sorted, and never touching (at least one old code point
+ * is kept between two gaps). Old text deleted and typed back is typed text,
+ * and a gap whose value is the old text it removes is dropped. Throws on a
+ * malformed or out-of-bounds op.
+ * @param {string} body
+ * @param {TextEditOp[]} ops
+ * @returns {TextGap[]}
+ */
+export function composeTextEdits(body: string, ops: TextEditOp[]): TextGap[];
+/**
+ * Gaps (old-body coordinates, sorted, not overlapping) as running ops: an
+ * insert where a gap removes nothing, a delete where it types nothing, and a
+ * replace otherwise.
+ * @param {TextGap[]} gaps
+ * @returns {TextEditOp[]}
+ */
+export function gapsToOps(gaps: TextGap[]): TextEditOp[];
+/**
+ * `body` with `ops` applied in turn (running coordinates, code points).
+ * Throws on a malformed or out-of-bounds op.
+ * @param {string} body
+ * @param {TextEditOp[]} ops
+ * @returns {string}
+ */
+export function applyTextOps(body: string, ops: TextEditOp[]): string;
+/**
+ * One op as `PATCH /texts/:id` takes it. Each index is in the body the ops
+ * before it left.
+ */
+export type TextEditOp = {
+    type: "insert";
+    index: number;
+    value: string;
+} | {
+    type: "delete";
+    index: number;
+    value: number;
+} | {
+    type: "replace";
+    index: number;
+    length: number;
+    value: string;
+};
+/**
+ * Old-body code points [start, end) give way to `value`.
+ */
+export type TextGap = {
+    start: number;
+    end: number;
+    value: string;
+};

package/src/textEdits.js

@@ -18,6 +18,19 @@
  * `plaid_client.text_edits` is the twin of this module.
  */
 
+/**
+ * One op as `PATCH /texts/:id` takes it. Each index is in the body the ops
+ * before it left.
+ * @typedef {{type: "insert", index: number, value: string}
+ *   | {type: "delete", index: number, value: number}
+ *   | {type: "replace", index: number, length: number, value: string}} TextEditOp
+ */
+
+/**
+ * Old-body code points [start, end) give way to `value`.
+ * @typedef {{start: number, end: number, value: string}} TextGap
+ */
+
 const codePoints = (s) => [...s];
 
 // The last body split into code points, kept: an edit log composes the same
@@ -27,7 +40,11 @@ const codePoints = (s) => [...s];
 let lastBody = null;
 let lastPoints = Object.freeze([]);
 
-/** The code points of `body`, as a frozen array shared with other callers. */
+/**
+ * The code points of `body`, as a frozen array shared with other callers.
+ * @param {string} body
+ * @returns {readonly string[]}
+ */
 export function bodyCodePoints(body) {
   if (body !== lastBody) {
     lastPoints = Object.freeze(codePoints(body));
@@ -36,9 +53,8 @@ export function bodyCodePoints(body) {
   return lastPoints;
 }
 
-function opName(op) {
-  return JSON.stringify(op);
-}
+// The op as a refusal names it.
+const opJson = (op) => String(JSON.stringify(op) ?? 'null');
 
 /**
  * The op's type after checking its shape and bounds against a body of `len`
@@ -54,11 +70,14 @@ function checkOp(op, len) {
     (type === 'replace' && int(index) && int(length) && typeof value === 'string');
   if (!wellFormed) {
     throw new Error(
-      `Malformed text edit operation: ${opName(op)}. Expected {type: "insert", index: int, ` +
+      `Malformed text edit operation: ${opJson(op)}. Expected {type: "insert", index: int, ` +
         `value: string}, {type: "delete", index: int, value: int} or {type: "replace", ` +
         `index: int, length: int, value: string}`,
     );
   }
+  if (!(op.side == null || op.side === 'before' || op.side === 'after')) {
+    throw new Error(`A text edit's side is "before" or "after": ${opJson(op)}`);
+  }
   const inBounds =
     type === 'insert'
       ? index >= 0 && index <= len
@@ -67,7 +86,7 @@ function checkOp(op, len) {
         : index >= 0 && length >= 0 && index + length <= len;
   if (!inBounds) {
     throw new Error(
-      `Text edit operation out of bounds: ${opName(op)} (text length is ${len} code points)`,
+      `Text edit operation out of bounds: ${opJson(op)} (text length is ${len} code points)`,
     );
   }
   return type;
@@ -112,6 +131,9 @@ function cutAt(segs, at) {
  * is kept between two gaps). Old text deleted and typed back is typed text,
  * and a gap whose value is the old text it removes is dropped. Throws on a
  * malformed or out-of-bounds op.
+ * @param {string} body
+ * @param {TextEditOp[]} ops
+ * @returns {TextGap[]}
  */
 export function composeTextEdits(body, ops) {
   const old = bodyCodePoints(body);
@@ -171,6 +193,8 @@ function mergeTyped(segs) {
  * Gaps (old-body coordinates, sorted, not overlapping) as running ops: an
  * insert where a gap removes nothing, a delete where it types nothing, and a
  * replace otherwise.
+ * @param {TextGap[]} gaps
+ * @returns {TextEditOp[]}
  */
 export function gapsToOps(gaps) {
   const ops = [];
@@ -193,6 +217,9 @@ export function gapsToOps(gaps) {
 /**
  * `body` with `ops` applied in turn (running coordinates, code points).
  * Throws on a malformed or out-of-bounds op.
+ * @param {string} body
+ * @param {TextEditOp[]} ops
+ * @returns {string}
  */
 export function applyTextOps(body, ops) {
   let chars = codePoints(body);