@larc-iu/plaid-client 0.2.0-alpha.3 → 0.2.0-alpha.32

package/src/serviceSchema.js

@@ -16,16 +16,26 @@
  *
  *   {
  *     schemaVersion: 1,
- *     tasks: ["tokenize"],              // controlled vocab; REPLACES tok:/asr: id prefixes
+ *     tasks: ["tokenize"],              // controlled vocab (TASKS)
  *     summary: "## markdown …",         // rich human description
  *     parameters: [                     // ordered; rendered into a form
  *       { key, label, type, description?, default?, required?,
  *         options?: [{value, label}],   // enum / multiselect
- *         min?, max?, step?,            // number
- *         placeholder?, multiline? }    // string
+ *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
+ *         placeholder?, multiline?,     // string
+ *         scope?, role? }               // field: 'Sentence' | 'Word' | 'Morpheme'
  *     ]
  *   }
  *
+ * A `field` parameter names one of the project's annotation fields at its
+ * `scope`. A UI that knows the project offers those fields to choose from; to
+ * everything here, and to a UI that does not, it is a string. Its optional
+ * `role` names a lexicon role ("gloss") or, at Sentence scope, a sentence
+ * field's role ("translation", "literalTranslation", "note"): a UI that knows
+ * the project fills the parameter with the one field at `scope` whose stored
+ * Lexicon field holds that role, or whose stored role it is. A field is never
+ * chosen by its name.
+ *
  * A parameter's `key` is a string VALUE, so it passes over the wire verbatim;
  * the UI sends `{ [param.key]: value }` in the request data. Declare each `key`
  * in your service's own convention (Python: snake_case; JS: camelCase) and read
@@ -43,45 +53,135 @@
  * without an explicit `overwrite` parameter. See the manual, "Provenance".
  */
 export const TASKS = Object.freeze({
-  TOKENIZE: 'tokenize',
-  PARSE: 'parse',
-  TRANSCRIBE: 'transcribe',
+  TOKENIZE: "tokenize",
+  PARSE: "parse",
+  TRANSCRIBE: "transcribe",
   /** Create vocab links for unlinked tokens. */
-  LINK_VOCAB: 'link-vocab',
+  LINK_VOCAB: "link-vocab",
   /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
-  ANALYZE: 'analyze',
+  ANALYZE: "analyze",
+  /**
+   * Draft a meaning representation graph over the sentences of a document,
+   * for correction by hand. The request names a `scope` ('document' or
+   * 'sentence'), a `sentence` number when the scope is one sentence, and
+   * `overwrite`. See plaid-umr's drafting services.
+   *
+   * Apart from `analyze` on purpose. A task is the CONTRACT a spot offers a
+   * service against, and these two share almost none of it: an analyze
+   * request names the three token layers plus the language and metalanguage,
+   * and writes morphemes and glosses. Both claimed `analyze` for
+   * a while, so every app offering an analyze spot offered the other app's
+   * services, which could not answer the request they would have been given.
+   */
+  DRAFT_GRAPH: "draft-graph",
+  /** Propose a free translation for each sentence. */
+  TRANSLATE: "translate",
+  /**
+   * Propose time-aligned speech regions for a recording.
+   *
+   * The odd one out: a detect-speech service RETURNS its regions and writes
+   * nothing, because a time-aligned segment is a stretch of the baseline and
+   * cannot exist without text. The response carries
+   * `{segments: [{timeBegin, timeEnd, speaker?}]}` (seconds), and the app
+   * holds them as proposals until a person types into one.
+   */
+  DETECT_SPEECH: "detect-speech",
+  /** A conversational assistant over a project (chat turns; see plaid-agent). */
+  ASSIST: "assist",
+  /**
+   * Score one document's annotation against another document's of the same
+   * text (two annotators' copies), writing a report on the scored document's
+   * metadata and never an annotation. The request names the other document
+   * as `against`. See plaid-umr's AnCast service.
+   */
+  COMPARE: "compare",
 });
 
 /**
- * Legacy id-prefix → task map, for services that have not yet migrated to a
- * declared `tasks` array. Drop once all services advertise `tasks`.
+ * One choice for an `enum` or `multiselect` service parameter.
+ * @typedef {{value: string, label: string}} ServiceParamOption
+ */
+
+/**
+ * A single user-controllable argument a service advertises.
+ * @typedef {object} ServiceParam
+ * @property {string} key Key the value is sent under in the request payload.
+ * @property {string} label
+ * @property {"string" | "number" | "boolean" | "enum" | "multiselect" | "field"} type
+ * @property {string} [description]
+ * @property {any} [default]
+ * @property {boolean} [required]
+ * @property {ServiceParamOption[]} [options] Required for `enum` and `multiselect`.
+ * @property {number} [min] `number` only.
+ * @property {number} [max] `number` only.
+ * @property {number} [step] `number` only.
+ * @property {boolean} [slider] `number` only: render as a slider to drag
+ *   rather than a box to type in.
+ * @property {string} [placeholder] `string` only.
+ * @property {boolean} [multiline] `string` only.
+ * @property {"Sentence" | "Word" | "Morpheme"} [scope] `field` only: the
+ *   scope of the project's annotation fields the value names one of. A
+ *   `field` value is a string everywhere else.
+ * @property {string} [role] `field` only: the lexicon role whose paired field,
+ *   or the sentence role whose field, fills the parameter when nothing else
+ *   does.
+ */
+
+/**
+ * A service's standardized self-description (lives in `extras`).
+ * @typedef {object} ServiceExtras
+ * @property {number} [schemaVersion]
+ * @property {string[]} [tasks] Tasks this service serves, from the TASKS vocabulary.
+ * @property {string} [summary] Rich human description (Markdown), beyond the
+ *   short `description`.
+ * @property {ServiceParam[]} [parameters] Ordered parameter schema, rendered
+ *   into a form by the UI.
+ */
+
+/**
+ * What a service says about itself when it registers.
+ * @typedef {object} ServiceInfo
+ * @property {string} serviceId
+ * @property {string} serviceName
+ * @property {string} description
+ * @property {ServiceExtras & Record<string, any>} [extras]
+ */
+
+/**
+ * A service as `messages.discoverServices` lists it.
+ * @typedef {object} DiscoveredService
+ * @property {string} serviceId
+ * @property {string} serviceName
+ * @property {string} description
+ * @property {ServiceExtras & Record<string, any>} extras
+ * @property {boolean} online True while the service holds an open request
+ *   channel, false for a previously seen offline service.
+ * @property {string | null} [lastSeenAt] ISO-8601 stamp of when the service
+ *   was last seen alive, or null when never stored.
+ * @property {string} [runnerName] Online services only: the display name of
+ *   the account that runs the service.
+ * @property {boolean} [runByYou] Online services only: the caller runs it.
+ * @property {boolean} [servesYou] Online services only: 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.
  */
-const LEGACY_TASK_PREFIXES = Object.freeze({
-  [TASKS.TOKENIZE]: 'tok:',
-  [TASKS.TRANSCRIBE]: 'asr:',
-});
 
 /**
- * Does `service` serve `task`? Prefers the declared `extras.tasks` array; falls
- * back to the legacy id-prefix convention for un-migrated services.
+ * Does `service` serve `task`, as its declared `extras.tasks` says?
  * @param {{serviceId?: string, extras?: {tasks?: string[]}}} service
  * @param {string} task one of TASKS
  * @returns {boolean}
  */
 export function servesTask(service, task) {
   const declared = service?.extras?.tasks;
-  if (Array.isArray(declared) && declared.length) {
-    return declared.includes(task);
-  }
-  const prefix = LEGACY_TASK_PREFIXES[task];
-  return !!prefix && typeof service?.serviceId === 'string' && service.serviceId.startsWith(prefix);
+  return Array.isArray(declared) && declared.includes(task);
 }
 
 /**
  * The discovered services that serve `task`.
- * @param {Array} services result of client.messages.discoverServices()
+ * @param {DiscoveredService[] | undefined} services result of client.messages.discoverServices()
  * @param {string} task one of TASKS
- * @returns {Array}
+ * @returns {DiscoveredService[]}
  */
 export function filterServicesByTask(services, task) {
   return (services || []).filter((s) => servesTask(s, task));
@@ -89,8 +189,8 @@ export function filterServicesByTask(services, task) {
 
 /**
  * The parameter schema a service declares (ordered array), or [].
- * @param {{extras?: {parameters?: Array}}} service
- * @returns {Array}
+ * @param {{extras?: {parameters?: ServiceParam[]}}} service
+ * @returns {ServiceParam[]}
  */
 export function getParamSchema(service) {
   const params = service?.extras?.parameters;
@@ -104,7 +204,7 @@ export function getParamSchema(service) {
  * @returns {string}
  */
 export function getServiceSummary(service) {
-  return service?.extras?.summary || service?.description || '';
+  return service?.extras?.summary || service?.description || "";
 }
 
 /** Valid option values for an enum/multiselect param. */
@@ -119,27 +219,32 @@ function optionValues(param) {
  */
 function defaultForParam(param) {
   const opts = optionValues(param);
-  if (param.type === 'enum') {
-    if (param.default != null && opts.includes(param.default)) return param.default;
-    return opts[0] ?? '';
+  if (param.type === "enum") {
+    if (param.default != null && opts.includes(param.default))
+      return param.default;
+    return opts[0] ?? "";
   }
-  if (param.type === 'multiselect') {
+  if (param.type === "multiselect") {
     const arr = Array.isArray(param.default) ? param.default : [];
     return opts.length ? arr.filter((x) => opts.includes(x)) : arr;
   }
-  if (param.default !== undefined && param.default !== null) return param.default;
+  if (param.default !== undefined && param.default !== null)
+    return param.default;
   switch (param.type) {
-    case 'number': return typeof param.min === 'number' ? param.min : 0;
-    case 'boolean': return false;
-    case 'string':
-    default: return '';
+    case "number":
+      return typeof param.min === "number" ? param.min : 0;
+    case "boolean":
+      return false;
+    case "string":
+    default:
+      return "";
   }
 }
 
 /**
  * Default values keyed by param key — the initial form state.
- * @param {Array} schema getParamSchema(service)
- * @returns {Object} { [key]: defaultValue }
+ * @param {ServiceParam[]} schema getParamSchema(service)
+ * @returns {Record<string, any>} { [key]: defaultValue }
  */
 export function buildDefaultValues(schema) {
   const out = {};
@@ -154,10 +259,24 @@ export function buildDefaultValues(schema) {
  * Coerce/validate raw form values against the schema. Returns the cleaned
  * values (keyed by param key, ready to merge into the request payload) plus any
  * validation errors keyed by param key. Unknown keys in `raw` are dropped.
- * @param {Array} schema getParamSchema(service)
- * @param {Object} raw current form values
- * @returns {{values: Object, errors: Object}}
+ * @param {ServiceParam[]} schema getParamSchema(service)
+ * @param {Record<string, any>} raw current form values
+ * @returns {{values: Record<string, any>, errors: Record<string, string>}}
  */
+// A decimal number as a person types one: an optional sign, digits with an
+// optional fraction (or a bare fraction), an optional exponent, with spaces
+// around it allowed. ASCII whitespace only, as in Python (each language's \s
+// holds characters the other's lacks).
+const DECIMAL = /^[ \t\n\v\f\r]*[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?[ \t\n\v\f\r]*$/;
+
+/** `v` as a finite number when it is one or a decimal string, else null. */
+function numberOf(v) {
+  let n = null;
+  if (typeof v === "number") n = v;
+  else if (typeof v === "string" && DECIMAL.test(v)) n = Number(v);
+  return n !== null && Number.isFinite(n) ? n : null;
+}
+
 export function coerceParamValues(schema, raw) {
   const values = {};
   const errors = {};
@@ -169,43 +288,41 @@ export function coerceParamValues(schema, raw) {
     if (v === undefined) v = defaultForParam(param);
 
     switch (param.type) {
-      case 'number': {
-        // Blank / nullish counts as "missing" → the param's default (matches the
-        // Python client, where float('') raises and falls back to the default).
-        let n;
-        if (v === '' || v == null || (typeof v === 'string' && v.trim() === '')) {
-          n = defaultForParam(param);
-        } else {
-          n = typeof v === 'number' ? v : Number(v);
-          if (Number.isNaN(n)) n = defaultForParam(param);
-        }
-        if (typeof param.min === 'number') n = Math.max(param.min, n);
-        if (typeof param.max === 'number') n = Math.min(param.max, n);
+      case "number": {
+        // A finite number, or a string holding a decimal one; anything else
+        // (blank, a boolean, a list, hex, an underscore, Infinity, a value too
+        // large to be finite) is the param's default. The Python client's
+        // `coerce` reads the same rule.
+        let n = numberOf(v);
+        if (n === null) n = defaultForParam(param);
+        if (typeof param.min === "number") n = Math.max(param.min, n);
+        if (typeof param.max === "number") n = Math.min(param.max, n);
         v = n;
         break;
       }
-      case 'boolean':
-        v = v === true || v === 'true';
+      case "boolean":
+        v = v === true || v === "true";
         break;
-      case 'enum': {
+      case "enum": {
         const opts = optionValues(param);
         if (opts.length && !opts.includes(v)) v = defaultForParam(param);
         break;
       }
-      case 'multiselect': {
+      case "multiselect": {
         const opts = optionValues(param);
-        const arr = Array.isArray(v) ? v : (v == null || v === '' ? [] : [v]);
+        const arr = Array.isArray(v) ? v : v == null || v === "" ? [] : [v];
         v = opts.length ? arr.filter((x) => opts.includes(x)) : arr;
         break;
       }
-      case 'string':
+      case "string":
       default:
-        v = v == null ? '' : String(v);
+        v = v == null ? "" : String(v);
         break;
     }
 
     if (param.required) {
-      const empty = v === '' || v == null || (Array.isArray(v) && v.length === 0);
+      const empty =
+        v === "" || v == null || (Array.isArray(v) && v.length === 0);
       if (empty) errors[k] = `${param.label || k} is required`;
     }
     values[k] = v;

package/src/services.d.ts

@@ -0,0 +1,319 @@
+/**
+ * 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. Every entry whose id an
+ * account holds gives its display name in `claimedByName`. An admin also gets
+ * the account in `claimedBy` (see `releaseService`), and an entry with
+ * `seen: false` for each held id whose registration was forgotten. 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, claimedByName, claimedBy, seen}]
+ */
+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>;
+/**
+ * Release a service id from the account that first registered it on the
+ * project. A service id belongs to that account, and the server refuses any
+ * other account's registration (403) until an admin releases it. The next
+ * account to register it then claims it. Deactivating the account releases
+ * every id it holds. Admin-only; 409 while the service is connected, 404 when
+ * no account holds it.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} serviceId - Service ID to release
+ * @returns {Promise<void>}
+ */
+export function releaseService(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;
+    };
+};