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

package/src/roles.js

@@ -65,9 +65,10 @@ export function readRole(config) {
  * The first layer in `layers` carrying the given role, or null. The single
  * "find a layer by its role" primitive — apps build their named finders
  * (findWordTokenLayer, etc.) on top of this.
- * @param {Array<{config?: object}>} [layers]
+ * @template {{config?: object}} T
+ * @param {T[] | undefined} layers
  * @param {string} role
- * @returns {object|null}
+ * @returns {T | null}
  */
 export function findByRole(layers, role) {
   return (layers || []).find(l => readRole(l?.config) === role) || null;

package/src/serviceSchema.d.ts

@@ -0,0 +1,331 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+/**
+ * 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: {
+    serviceId?: string;
+    extras?: {
+        tasks?: string[];
+    };
+}, task: string): boolean;
+/**
+ * The discovered services that serve `task`.
+ * @param {DiscoveredService[] | undefined} services result of client.messages.discoverServices()
+ * @param {string} task one of TASKS
+ * @returns {DiscoveredService[]}
+ */
+export function filterServicesByTask(services: DiscoveredService[] | undefined, task: string): DiscoveredService[];
+/**
+ * The parameter schema a service declares (ordered array), or [].
+ * @param {{extras?: {parameters?: ServiceParam[]}}} service
+ * @returns {ServiceParam[]}
+ */
+export function getParamSchema(service: {
+    extras?: {
+        parameters?: ServiceParam[];
+    };
+}): ServiceParam[];
+/**
+ * A service's human summary: the rich `extras.summary`, else the short
+ * `description`, else ''.
+ * @param {{description?: string, extras?: {summary?: string}}} service
+ * @returns {string}
+ */
+export function getServiceSummary(service: {
+    description?: string;
+    extras?: {
+        summary?: string;
+    };
+}): string;
+/**
+ * Default values keyed by param key — the initial form state.
+ * @param {ServiceParam[]} schema getParamSchema(service)
+ * @returns {Record<string, any>} { [key]: defaultValue }
+ */
+export function buildDefaultValues(schema: ServiceParam[]): Record<string, any>;
+/**
+ * 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 {ServiceParam[]} schema getParamSchema(service)
+ * @param {Record<string, any>} raw current form values
+ * @returns {{values: Record<string, any>, errors: Record<string, string>}}
+ */
+export function coerceParamValues(schema: ServiceParam[], raw: Record<string, any>): {
+    values: Record<string, any>;
+    errors: Record<string, string>;
+};
+/**
+ * Service self-description: tasks, summary, and a parameter schema.
+ *
+ * The service framework's transport carries an opaque `extras` JSON map on every
+ * registered service (see services.js). This module standardizes what a service
+ * advertises in that map so apps can, at a fixed integration point (a "task"
+ * like tokenize / parse / transcribe):
+ *
+ *   1. SELECT one of several services that serve the task,
+ *   2. let the user SPECIFY arguments the service declares, and
+ *   3. show the user a service-provided SUMMARY.
+ *
+ * Shape of a service's `extras` (camelCase here; Python services author the
+ * snake_case equivalent and the client transform converts it — see the Plaid
+ * manual, "Describing a service"):
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     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?, slider?,   // number (slider: drag, don't type)
+ *         placeholder?, multiline?,     // string
+ *         scope? }                      // 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.
+ *
+ * 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
+ * it back under that same key — request data is recased symmetrically, so a
+ * snake_case key round-trips unchanged to a JS UI and back.
+ */
+/**
+ * The controlled task vocabulary — the fixed integration-point goals.
+ *
+ * Whatever the task, a service should stamp everything it creates with the
+ * provenance convention (see ./provenance.js: stampInferred(serviceSource(id)))
+ * so UIs can distinguish machine output until a human verifies it, and should
+ * honor the write contract: never destroy human-made or verified material
+ * without an explicit `overwrite` parameter. See the manual, "Provenance".
+ */
+export const TASKS: Readonly<{
+    TOKENIZE: "tokenize";
+    PARSE: "parse";
+    TRANSCRIBE: "transcribe";
+    /** Create vocab links for unlinked tokens. */
+    LINK_VOCAB: "link-vocab";
+    /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
+    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";
+}>;
+/**
+ * One choice for an `enum` or `multiselect` service parameter.
+ */
+export type ServiceParamOption = {
+    value: string;
+    label: string;
+};
+/**
+ * A single user-controllable argument a service advertises.
+ */
+export type ServiceParam = {
+    /**
+     * Key the value is sent under in the request payload.
+     */
+    key: string;
+    label: string;
+    type: "string" | "number" | "boolean" | "enum" | "multiselect" | "field";
+    description?: string;
+    default?: any;
+    required?: boolean;
+    /**
+     * Required for `enum` and `multiselect`.
+     */
+    options?: ServiceParamOption[];
+    /**
+     * `number` only.
+     */
+    min?: number;
+    /**
+     * `number` only.
+     */
+    max?: number;
+    /**
+     * `number` only.
+     */
+    step?: number;
+    /**
+     * `number` only: render as a slider to drag
+     * rather than a box to type in.
+     */
+    slider?: boolean;
+    /**
+     * `string` only.
+     */
+    placeholder?: string;
+    /**
+     * `string` only.
+     */
+    multiline?: boolean;
+    /**
+     * `field` only: the
+     * scope of the project's annotation fields the value names one of. A
+     * `field` value is a string everywhere else.
+     */
+    scope?: "Sentence" | "Word" | "Morpheme";
+};
+/**
+ * A service's standardized self-description (lives in `extras`).
+ */
+export type ServiceExtras = {
+    schemaVersion?: number;
+    /**
+     * Tasks this service serves, from the TASKS vocabulary.
+     */
+    tasks?: string[];
+    /**
+     * Rich human description (Markdown), beyond the
+     * short `description`.
+     */
+    summary?: string;
+    /**
+     * Ordered parameter schema, rendered
+     * into a form by the UI.
+     */
+    parameters?: ServiceParam[];
+};
+/**
+ * What a service says about itself when it registers.
+ */
+export type ServiceInfo = {
+    serviceId: string;
+    serviceName: string;
+    description: string;
+    extras?: ServiceExtras & Record<string, any>;
+};
+/**
+ * A service as `messages.discoverServices` lists it.
+ */
+export type DiscoveredService = {
+    serviceId: string;
+    serviceName: string;
+    description: string;
+    extras: ServiceExtras & Record<string, any>;
+    /**
+     * True while the service holds an open request
+     * channel, false for a previously seen offline service.
+     */
+    online: boolean;
+    /**
+     * ISO-8601 stamp of when the service
+     * was last seen alive, or null when never stored.
+     */
+    lastSeenAt?: string | null;
+    /**
+     * Online services only: the display name of
+     * the account that runs the service.
+     */
+    runnerName?: string;
+    /**
+     * Online services only: the caller runs it.
+     */
+    runByYou?: boolean;
+    /**
+     * 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.
+     */
+    servesYou?: boolean;
+};

package/src/serviceSchema.js

@@ -92,6 +92,72 @@ export const TASKS = Object.freeze({
   COMPARE: "compare",
 });
 
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
 /**
  * Does `service` serve `task`, as its declared `extras.tasks` says?
  * @param {{serviceId?: string, extras?: {tasks?: string[]}}} service
@@ -105,9 +171,9 @@ export function servesTask(service, 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));
@@ -115,8 +181,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;
@@ -169,8 +235,8 @@ function defaultForParam(param) {
 
 /**
  * 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 = {};
@@ -185,9 +251,9 @@ 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>}}
  */
 export function coerceParamValues(schema, raw) {
   const values = {};