initiative-plugin-sdk 7.2.0 → 8.0.0

package/dist/contract.d.ts

@@ -54,6 +54,10 @@ export type FieldKind = "text" | "number" | "date" | "datetime" | "link" | "badg
 export declare const FIELD_KINDS: readonly FieldKind[];
 export type Tone = "accent" | "positive" | "negative" | "warning" | "neutral" | "muted";
 export declare const TONES: readonly Tone[];
+export type SettingType = "string";
+export declare const SETTING_TYPES: readonly SettingType[];
+export type SettingAssignment = "community_name";
+export declare const SETTING_ASSIGNMENTS: readonly SettingAssignment[];
 export type ListingKind = "plugin" | "dashboard";
 export declare const LISTING_KINDS: readonly ListingKind[];
 export type HttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
@@ -91,6 +95,8 @@ export declare const CAPS: {
     readonly actions: 16;
     readonly partNodes: 50;
     readonly partDepth: 4;
+    readonly facetsPerField: 4;
+    readonly valuesPerFacet: 12;
     readonly metadataKeyLength: 64;
     readonly metadataValueBytes: 8192;
     readonly metadataLookupLength: 255;
@@ -98,7 +104,11 @@ export declare const CAPS: {
     readonly metadataBytesPerObject: 65536;
     readonly installMetadataKeys: 256;
     readonly installMetadataBytes: 1048576;
+    readonly writeTargets: 100;
     readonly partsPlacedPerItem: 3;
+    readonly settings: 16;
+    readonly uniqueSettingValueLength: 16;
+    readonly helpLength: 2000;
     readonly bundledDashboards: 8;
     readonly dashboardWidgets: 50;
     readonly dashboardGridColumns: 12;
@@ -167,6 +177,7 @@ export declare const CHARSETS: {
     readonly artwork: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/._-";
     readonly queryName: "-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ[]_abcdefghijklmnopqrstuvwxyz~";
     readonly metadataKey: "._0123456789abcdefghijklmnopqrstuvwxyz";
+    readonly uniqueSettingValue: "0123456789abcdefghijklmnopqrstuvwxyz";
 };
 /**
  * Every field the contract declares, by the object that owns it.
@@ -186,15 +197,17 @@ export declare const FIELDS: {
     readonly endpointReturn: readonly ["key", "type", "label", "list", "of"];
     readonly connection: readonly ["id", "scope", "label", "fields", "flow", "token", "access_hint", "health"];
     readonly connectionFlow: readonly ["type", "authorize_url", "token_url", "client_id", "client_secret", "scopes", "pkce", "authorize_params", "install_url", "after_connect", "revoke", "revoke_url"];
-    readonly connectionToken: readonly ["type", "exchange_url", "iss", "key", "alg", "lifetime"];
+    readonly connectionToken: readonly ["type", "exchange_url", "exchange_body", "iss", "key", "alg", "lifetime"];
     readonly webhooks: readonly ["verify", "dedup", "route", "events", "status"];
     readonly webhookVerify: readonly ["scheme", "header", "prefix", "encoding", "secret"];
     readonly webhookRoute: readonly ["path", "header", "connection", "field"];
-    readonly schedule: readonly ["id", "every"];
+    readonly schedule: readonly ["id", "every", "endpoint", "params", "write"];
     readonly endpoint: readonly ["id", "label", "description", "returns", "group", "needs_subject", "direction", "params", "actors", "admin_only", "public", "requires", "cache_ttl_seconds", "identity", "unavailable", "request", "steps", "map", "errors"];
     readonly widget: readonly ["id", "meta", "module_source", "endpoints", "sample_data", "requires"];
     readonly page: readonly ["id", "path", "name", "scopes", "admin_only", "capabilities", "requires"];
-    readonly field: readonly ["key", "name", "kind", "on", "description", "tone", "requires"];
+    readonly field: readonly ["key", "name", "kind", "list", "on", "description", "tone", "states", "actions", "requires"];
+    readonly stateFacet: readonly ["name", "values"];
+    readonly stateValue: readonly ["label", "tone"];
     readonly sectionNode: readonly ["type", "props", "children"];
     readonly stackNode: readonly ["type", "props", "children"];
     readonly fieldNode: readonly ["type", "props"];
@@ -202,13 +215,18 @@ export declare const FIELDS: {
     readonly textNode: readonly ["type", "props"];
     readonly buttonNode: readonly ["type", "props"];
     readonly part: readonly ["id", "name", "on", "tree", "description", "requires"];
-    readonly action: readonly ["id", "name", "endpoint", "on", "confirm", "menu", "requires"];
+    readonly action: readonly ["id", "name", "endpoint", "params", "write", "on", "confirm", "menu", "admin_only", "requires"];
+    readonly change: readonly ["set", "upsert", "remove"];
+    readonly targetedChange: readonly ["target", "set", "upsert", "remove"];
+    readonly listElement: readonly ["ref", "value", "url", "text", "tone", "max", "state"];
+    readonly setting: readonly ["key", "type", "label", "description", "unique", "assigned"];
     readonly bundledDashboard: readonly ["uid", "public_id", "name", "description", "layout", "widgets"];
     readonly bundledDashboardWidget: readonly ["id", "type", "title", "grid", "binding"];
     readonly endpointIdentity: readonly ["kind", "key"];
     readonly vendorAuth: readonly ["header", "prefix"];
     readonly vendorRequest: readonly ["method", "url", "query", "headers", "body", "graphql", "connection", "paging"];
     readonly graphqlRequest: readonly ["query", "variables"];
+    readonly actorConnections: readonly ["member", "installation"];
     readonly requestStep: readonly ["name", "request"];
     readonly pageNumberPaging: readonly ["kind", "page_param", "per_page_param", "per_page", "items", "max_pages", "on_limit"];
     readonly linkHeaderPaging: readonly ["kind", "items", "max_pages", "on_limit"];
@@ -217,9 +235,9 @@ export declare const FIELDS: {
     readonly afterConnect: readonly ["request", "steps", "map", "refuse_when", "code"];
     readonly connectionHealth: readonly ["request", "every", "states"];
     readonly healthState: readonly ["status", "when", "state"];
-    readonly webhookEvent: readonly ["when", "emit", "map"];
+    readonly webhookEvent: readonly ["when", "emit", "map", "write"];
     readonly webhookStatus: readonly ["when", "connection", "state"];
-    readonly manifest: readonly ["plugin_kind", "service", "features", "default_name", "minimum_age", "min_plugin_api", "hosts", "auth", "vendor", "connections", "webhooks", "schedules", "endpoints", "community_summary", "widgets", "pages", "dashboards", "fields", "parts", "actions"];
+    readonly manifest: readonly ["plugin_kind", "service", "features", "default_name", "minimum_age", "min_plugin_api", "hosts", "auth", "scopes", "vendor", "connections", "webhooks", "schedules", "endpoints", "community_summary", "widgets", "pages", "dashboards", "fields", "parts", "actions", "settings", "help"];
 };
 export type Identifier = string;
 /**
@@ -564,6 +582,18 @@ export interface ConnectionToken {
      * '{<key>}'.
      */
     exchange_url: string;
+    /**
+     * A JSON body posted with the signed JWT, such as the narrower permissions a
+     * token is asked for. Absent: none. A string anywhere in it may name a vendor
+     * value as '{vendor.<key>}' and one of this connection's own fields as
+     * '{<key>}'. Or an expression answering the body, which reads only
+     * 'connection': this connection's own non-secret fields by key, its managed
+     * values included, as 'after_connect' stored them. A body that names a vendor
+     * value is written as an object. An answer that is not an object fails the
+     * token request, so the connection cannot be used until the expression
+     * answers one.
+     */
+    exchange_body?: Record<string, unknown> | Expression;
     /**
      * The JWT's issuer, normally '{vendor.app_id}'. May name a vendor value as
      * '{vendor.<key>}' and one of this connection's own fields as '{<key>}'.
@@ -599,9 +629,10 @@ export interface Webhooks {
     dedup: string;
     route: WebhookRoute;
     /**
-     * Declarative plug-ins: how a delivery becomes one of this plug-in's events.
-     * The first row whose 'when' holds emits; a delivery no row matches is
-     * dropped.
+     * Declarative plug-ins: what a delivery does: emit one of this plug-in's
+     * events, change the plug-in's values, or both. The first row whose 'when'
+     * holds applies, its 'emit' and its 'write' both; a delivery no row matches
+     * is dropped.
      */
     events?: WebhookEvent[];
     /**
@@ -660,12 +691,18 @@ export interface WebhookRoute {
     field: Identifier;
 }
 /**
- * An interval at which Initiative calls the plug-in's schedule hook, once for
- * each community that installed it, with when the call last succeeded there.
+ * Something Initiative runs on an interval, once for each community that
+ * installed the plug-in, with when it last succeeded there as 'since'. A
+ * container plug-in's schedule calls its schedule hook, and names nothing more.
+ * A declarative plug-in's makes one of its read endpoints' calls as the
+ * installation and changes the plug-in's values from the answer: it names the
+ * 'endpoint' and the 'write', and 'params' when the endpoint takes any.
  */
 export interface Schedule {
     /**
-     * Unique within the manifest. The hook is told which schedule is due by it.
+     * Unique within the manifest. A container's hook is told which schedule is
+     * due by it. A declarative plug-in's differs from every connection's id:
+     * Initiative keys connection health checks by connection id.
      */
     id: Identifier;
     /**
@@ -673,6 +710,27 @@ export interface Schedule {
      * minutes and at most 1440 minutes.
      */
     every: string;
+    /**
+     * Declarative plug-ins: a read endpoint this manifest declares, whose
+     * 'actors' include 'installation': no person is present when a schedule runs.
+     */
+    endpoint?: NamespacedId;
+    /**
+     * Declarative plug-ins: the endpoint's params, as one expression answering an
+     * object. It reads 'since', when the schedule last succeeded in the community
+     * (ISO 8601), or null the first time; 'now'; 'connection', the non-secret
+     * fields of the connection the endpoint's first request names; 'settings' and
+     * 'aliases'. Absent: none.
+     */
+    params?: Expression;
+    /**
+     * Declarative plug-ins: the changes Initiative makes to the plug-in's values
+     * from the endpoint's answer, as the install: a list of at most 100 targeted
+     * changes ('targetedChange'). It reads 'result', the endpoint's mapped
+     * answer, 'since', 'now', 'settings' and 'aliases'. Answering nothing changes
+     * nothing.
+     */
+    write?: Expression;
 }
 /**
  * Namespaced under the plug-in's own service id — 'plugin.<public_id>.<name>'.
@@ -681,11 +739,12 @@ export interface Schedule {
 export type NamespacedId = string;
 /**
  * 'plugins:<public_id>': permission to call another plug-in's public endpoints
- * through the deployment, as this community or as one of its members. Not one
- * of the fixed scopes: the family is open, one per plug-in, and the public id
- * after the prefix is the plug-in being called. The deployment never lets a
- * plug-in address another directly; the call goes through it, and the plug-in
- * called is handed its own references for whoever the call is for.
+ * through the deployment, as this community or as one of its members, and to
+ * read the values that plug-in shows on items this one can read. Not one of the
+ * fixed scopes: the family is open, one per plug-in, and the public id after
+ * the prefix is the plug-in being called. The deployment never lets a plug-in
+ * address another directly; the call goes through it, and the plug-in called is
+ * handed its own references for whoever the call is for.
  */
 export type PluginScope = `plugins:${string}`;
 export interface Endpoint {
@@ -849,14 +908,17 @@ export interface Page {
 export type MetadataKey = string;
 /**
  * How one of the plug-in's metadata keys is shown on Initiative's items. The
- * plug-in keeps the value in Initiative, through its installation token;
- * Initiative draws it with its own component for `kind` and computes its plain
- * text itself, so a field filters, sorts and exports with no call to the
- * plug-in. Which views show it is chosen by the community's managers, never by
- * the plug-in. Initiative holds what is kept, and these caps are enforced there
- * rather than here: a value of at most 8192 bytes as JSON, with a string of at
- * most 255 characters to be found by; at most 32 keys and 65536 bytes on one
- * item, and 256 keys and 1048576 bytes on the install.
+ * value is kept in Initiative: a container plug-in writes it with its
+ * installation token, and for a declarative plug-in Initiative writes it from
+ * the plug-in's expressions. Initiative draws it with its own component for
+ * `kind` and computes its plain text itself, so a field filters, sorts and
+ * exports with no call to the plug-in. Which views show it is chosen by the
+ * community's managers, never by the plug-in. Initiative holds what is kept,
+ * and these caps are enforced there rather than here: a value of at most 8192
+ * bytes as JSON, with a string of at most 255 characters to be found by, and
+ * each element of a list a value of its own, found by its 'ref'; at most 32
+ * keys and 65536 bytes on one item, and 256 keys and 1048576 bytes on the
+ * install.
  */
 export interface Field {
     /**
@@ -875,6 +937,14 @@ export interface Field {
      * max}; 'checkbox' a boolean.
      */
     kind: FieldKind;
+    /**
+     * Several values rather than one: the value is a list of elements, each one
+     * value of 'kind' with a 'ref' that tells it from the others ('listElement').
+     * A change gives the whole list in 'set', or adds, replaces and removes
+     * elements by 'ref' with 'upsert' and 'remove'. Absent: one value, which a
+     * change sets.
+     */
+    list?: boolean;
     /**
      * The item kinds it is offered on.
      */
@@ -887,8 +957,46 @@ export interface Field {
      * A badge's tone when its value names none.
      */
     tone?: Tone;
+    /**
+     * What state the value is in, as facets by id, at most 4, each with keys of
+     * its own. The value names a key of each facet it is in as 'state',
+     * {"<facet>": "<key>"}, and Initiative draws each as a badge, labelled in the
+     * reader's language. A list element, and a link, badge or progress value,
+     * carries 'state' beside its other properties; a text, number, date, datetime
+     * or checkbox value that carries one is written as an element is, without the
+     * 'ref': {"value": …, "state": …}.
+     */
+    states?: Record<string, StateFacet>;
+    /**
+     * Declarative plug-ins, on a list field: actions offered on each of its
+     * elements, by id, each one offered on every item kind this field is. An
+     * action run from an element reads that element's 'ref' as 'element'.
+     */
+    actions?: Identifier[];
     requires?: Requires;
 }
+/**
+ * One facet of a field's state, such as whether a piece of work is open or what
+ * review it has: its name, and the keys a value may name.
+ */
+export interface StateFacet {
+    /**
+     * What the facet is called.
+     */
+    name: LocalizedText;
+    /**
+     * The keys a value may name, at most 12, each with its badge's words and
+     * tone.
+     */
+    values: Record<string, StateValue>;
+}
+/**
+ * One key of a state facet, as its badge shows it.
+ */
+export interface StateValue {
+    label: LocalizedText;
+    tone?: Tone;
+}
 /**
  * One node of a part: one of Initiative's own components, told apart by 'type',
  * with its props and, for a section or a stack, the nodes inside it.
@@ -964,6 +1072,11 @@ export interface ValueNode {
 export interface TextNode {
     type: "text";
     props: {
+        /**
+         * May name '{item.id}', the item's id, and '{settings.<key>}', one of this
+         * plug-in's settings, which Initiative fills in when it draws the part. Any
+         * other '{…}' is refused.
+         */
         text: LocalizedText;
         tone?: Tone;
     };
@@ -1014,12 +1127,19 @@ export interface Part {
     requires?: Requires;
 }
 /**
- * Something a reader runs on one item, from a part's button or the item's own
- * menu. Initiative only connects: it calls the write endpoint as the
- * installation, with the reader as 'viewer' and the item as 'subject' in the
- * call's token, and the endpoint does the work, usually writing the plug-in's
- * metadata. Initiative then answers the reader with the item's metadata as it
- * stands.
+ * Something a reader runs on one item, from a part's button, the item's own
+ * menu, or an element of a list field that offers it. Initiative first asks the
+ * reader for the 'params' the action names, when it names any. For a container
+ * plug-in, Initiative only connects: it calls the write endpoint as the
+ * installation, with those parameters, the reader as 'viewer' and the item as
+ * 'subject' in the call's token, and the endpoint does the work, usually
+ * writing the plug-in's metadata. For a declarative plug-in, Initiative does
+ * the work: it makes the endpoint's call, when the action names one, with those
+ * parameters, on the credential its 'actors' say, its expressions reading the
+ * item as 'item' and the element it was run from, if any, as 'element'; then it
+ * makes the change 'write' answers, when the action has one, to the plug-in's
+ * values on the item, as the install. Either way Initiative then answers the
+ * reader with the item's metadata as it stands.
  */
 export interface Action {
     /**
@@ -1031,9 +1151,30 @@ export interface Action {
      */
     name: LocalizedText;
     /**
-     * A write endpoint this manifest declares.
+     * An endpoint this manifest declares. A container plug-in's action names a
+     * write, which its handler answers. A declarative plug-in's names a read or a
+     * write, a 'write' expression, or both: a read fetches what the 'write'
+     * keeps, a write changes something at the vendor.
+     */
+    endpoint?: NamespacedId;
+    /**
+     * Parameters of the action's endpoint, by key, that Initiative asks the
+     * reader for before it runs the action, in a form drawn from the endpoint's
+     * own declarations of them: each one's type and label, and its 'options' or
+     * 'options_from'. The endpoint is sent these and nothing else, so every
+     * parameter it requires is among them.
+     */
+    params?: Identifier[];
+    /**
+     * Declarative plug-ins: the change Initiative makes to the plug-in's values
+     * on the action's item, as the install: one change ('change'). It reads
+     * 'item', the item ({kind, id, title}); 'held', this install's values on it,
+     * by key; 'result', the endpoint's mapped answer, absent when the action
+     * names no endpoint; 'params', what the reader answered; 'element', the 'ref'
+     * of the list element it was run from, absent when it was not; 'settings',
+     * 'aliases' and 'now'. Answering nothing changes nothing.
      */
-    endpoint: NamespacedId;
+    write?: Expression;
     /**
      * The item kinds it is offered on.
      */
@@ -1046,8 +1187,171 @@ export interface Action {
      * Also offered in the item's own menu.
      */
     menu?: boolean;
+    /**
+     * Only the community's admins run this action, whatever roles a placement
+     * allows. Who else may run it is chosen in the community, per initiative and
+     * per role, not declared here.
+     */
+    admin_only?: boolean;
     requires?: Requires;
 }
+/**
+ * A change to the plug-in's values on one item or on its install, as a
+ * declarative plug-in's 'write' answers it. 'set' writes values by key, as a
+ * container's client.metadata.set does; 'upsert' and 'remove' change a list
+ * field's elements by their 'ref'. A change gives at least one of the three,
+ * and changes each key with only one. Initiative makes it as the install, and
+ * holds what is kept to the caps a field's description gives.
+ */
+export interface Change {
+    /**
+     * Values by metadata key, each any JSON value of at most 8192 bytes; a null
+     * removes its key. A list field's value is its whole list of elements, each
+     * held to that cap.
+     */
+    set?: Record<string, unknown>;
+    /**
+     * Elements by metadata key ('listElement'): each is added to that key's list,
+     * or merged into the element there with its 'ref': the properties it gives
+     * replace that element's, the ones it leaves out stay, and its 'state' merges
+     * the same way by facet. So a write that knows one fact about an element
+     * changes that fact alone.
+     */
+    upsert?: Record<string, ListElement[]>;
+    /**
+     * Refs by metadata key: the element with each is taken from that key's list.
+     * A ref the list does not hold changes nothing.
+     */
+    remove?: Record<string, ElementRef[]>;
+}
+/**
+ * A change and where Initiative makes it. A webhook event's or a schedule's
+ * 'write' answers a list of at most 100, and cannot read what their targets
+ * hold.
+ */
+export interface TargetedChange {
+    target: ChangeTarget;
+    /**
+     * As a change's: values by metadata key, a null removing its key.
+     */
+    set?: Record<string, unknown>;
+    /**
+     * As a change's: elements by metadata key, each added to its list or merged
+     * into the one with its 'ref', property by property and its 'state' facet by
+     * facet.
+     */
+    upsert?: Record<string, ListElement[]>;
+    /**
+     * As a change's: refs by metadata key, each element with one taken from its
+     * list.
+     */
+    remove?: Record<string, ElementRef[]>;
+}
+/**
+ * Where a change is made: {kind, id}, one item; {install: true}, the install
+ * itself; or {holding: {key, value}}, every item on which this install holds
+ * 'value' under 'key', as a container's client.metadata.find finds them.
+ * Initiative keeps each element of a list as a value of its own, so 'holding'
+ * reaches an element by its 'ref'. A target the install cannot read is skipped.
+ */
+export type ChangeTarget = {
+    kind: ItemKind;
+    id: number;
+} | {
+    install: true;
+} | {
+    holding: {
+        key: MetadataKey;
+        /**
+         * A value is found by its text: a string as it is, a number or a boolean as
+         * JSON writes it; a list element by its 'ref'.
+         */
+        value: string;
+    };
+};
+/**
+ * One element of a list field's value: one value of the field's 'kind', with a
+ * 'ref' that tells it from the list's others. A text, number, date, datetime or
+ * checkbox element holds its value in 'value'; a link element is {ref, url,
+ * text?}, a badge element {ref, text, tone?} and a progress element {ref,
+ * value, max}. Initiative keeps each element as a value of its own, of at most
+ * 8192 bytes as JSON. An 'upsert' may give only some of an element's
+ * properties: they are merged into the element with its 'ref'.
+ */
+export interface ListElement {
+    ref: ElementRef;
+    /**
+     * A text, number, date, datetime or checkbox element's value, or a progress
+     * element's figure.
+     */
+    value?: string | number | boolean;
+    /**
+     * A link element's address.
+     */
+    url?: string;
+    /**
+     * A link element's words, or a badge element's.
+     */
+    text?: string;
+    /**
+     * A badge element's tone.
+     */
+    tone?: Tone;
+    /**
+     * A progress element's whole.
+     */
+    max?: number;
+    /**
+     * A key of each of the field's state facets this element is in, by facet id.
+     */
+    state?: Record<string, Identifier>;
+}
+/**
+ * What tells a list's element from the others, such as the vendor's own id for
+ * what it shows: unique in its list, and how a change replaces or removes the
+ * element and a 'holding' target finds it.
+ */
+export type ElementRef = string;
+/**
+ * A value the community's admins see and may change on the install, which the
+ * plug-in's expressions read as 'settings.<key>' and its parts' text names as
+ * '{settings.<key>}'.
+ */
+export interface Setting {
+    /**
+     * Unique among this manifest's settings.
+     */
+    key: Identifier;
+    /**
+     * What the value is: 'string', a line of text.
+     */
+    type: SettingType;
+    label: LocalizedText;
+    /**
+     * A line under the label.
+     */
+    description?: LocalizedText;
+    /**
+     * No two communities on a deployment hold the same value for this plug-in,
+     * and the value is a 'uniqueSettingValue'. An admin who renames it keeps the
+     * earlier values, which no other community may take and the plug-in's
+     * expressions read as 'aliases.<key>'.
+     */
+    unique?: boolean;
+    /**
+     * A unique setting's only: Initiative gives it a value when the community
+     * installs the plug-in, which an admin may rename. 'community_name': the
+     * letters and digits of the community's name, in lowercase, with a short
+     * random suffix when another community holds that value.
+     */
+    assigned?: SettingAssignment;
+}
+/**
+ * A unique setting's value: a lowercase letter, then lowercase letters and
+ * digits, two to 16 characters in all. It holds no '-', so a reference such as
+ * '<value>-<number>' reads one way.
+ */
+export type UniqueSettingValue = string;
 export interface BundledDashboard {
     /**
      * This dashboard's own catalog id — publisher-assigned, immutable, never
@@ -1121,11 +1425,16 @@ export interface EndpointIdentity {
  * fields of the connection the request names; 'connections', on an endpoint's
  * requests and map, each connection its 'requires' names that the call has, by
  * its id, holding the same fields; 'now', the time of the call in ISO 8601,
- * which $now() and $millis() also answer; and 'steps', each earlier step's
- * answer by its name. On the way back it also holds 'response', the answer
- * being read: {status, headers, body}, with header names in lowercase. Each
- * evaluation is bounded: at most 1000 milliseconds, 500 levels of nesting and
- * an answer of 1048576 bytes as JSON. An expression that fails or passes a
+ * which $now() and $millis() also answer; 'steps', each earlier step's answer
+ * by its name; and, on the call an action makes, 'item', the item it runs on:
+ * {kind, id, title}, and 'element', the 'ref' of the list element it was run
+ * from, if it was. On the way back it also holds 'response', the answer being
+ * read: {status, headers, body}, with header names in lowercase. Every
+ * expression of a declarative plug-in also reads 'settings', the install's
+ * settings by key, and 'aliases', each unique setting's earlier values by key,
+ * as a list, except a token's 'exchange_body', which reads only its connection.
+ * Each evaluation is bounded: at most 1000 milliseconds, 500 levels of nesting
+ * and an answer of 1048576 bytes as JSON. An expression that fails or passes a
  * bound answers 'unavailable: mapping-failed'.
  */
 export type Expression = string;
@@ -1180,14 +1489,18 @@ export interface VendorRequest {
     body?: Expression;
     graphql?: GraphqlRequest;
     /**
-     * Which connection's credential the request carries: a static connection's is
-     * the community's, an interactive one's the acting member's. A call made as a
-     * member carries a static connection's credential only when the endpoint's
-     * 'requires' names that connection, and is refused otherwise. Required on an
-     * endpoint's requests. Absent on 'after_connect' and 'health', which carry
-     * the credential of the connection they belong to.
-     */
-    connection?: Identifier;
+     * Which connection's credential the request carries: one connection for every
+     * call, or, on a write endpoint's requests, one per actor
+     * ('actorConnections'), so a call made as the member carries the member's own
+     * credential and one made as the installation the community's. A static
+     * connection's credential is the community's, an interactive one's the acting
+     * member's, which a call made as the installation does not have. A call made
+     * as a member carries a static connection's credential only when the
+     * endpoint's 'requires' names that connection, and is refused otherwise.
+     * Required on an endpoint's requests. Absent on 'after_connect' and 'health',
+     * which carry the credential of the connection they belong to.
+     */
+    connection?: Identifier | ActorConnections;
     paging?: Paging;
 }
 /**
@@ -1203,6 +1516,25 @@ export interface GraphqlRequest {
      */
     variables?: Expression;
 }
+/**
+ * One connection per actor, on a write endpoint's requests: a call carries the
+ * credential of the connection named for the actor it is made as. Names exactly
+ * the actors the endpoint's 'actors' declare. The member's connection need not
+ * be named in 'requires': a call made as the member requires the connection its
+ * requests name for the member.
+ */
+export interface ActorConnections {
+    /**
+     * An interactive connection, which a call made as the member carries: the
+     * member's own account.
+     */
+    member?: Identifier;
+    /**
+     * A static connection, which a call made as the installation carries: the
+     * community's own.
+     */
+    installation?: Identifier;
+}
 export interface RequestStep {
     /**
      * Unique among its steps. Later steps, the map and the predicates beside it
@@ -1366,9 +1698,11 @@ export interface HealthState {
     state: ConnectionState;
 }
 /**
- * One way a delivery becomes an event. Its expressions read 'headers' (names in
- * lowercase), 'payload' (the parsed body), 'connection' (the routed
- * connection's non-secret fields) and 'now'.
+ * What one kind of delivery does: emit an event, change the plug-in's values,
+ * or both. It gives 'emit', 'write' or both, and 'map' exactly when it gives
+ * 'emit'. Its expressions read 'headers' (names in lowercase), 'payload' (the
+ * parsed body), 'connection' (the routed connection's non-secret fields),
+ * 'now', 'settings' and 'aliases'.
  */
 export interface WebhookEvent {
     /**
@@ -1378,11 +1712,17 @@ export interface WebhookEvent {
     /**
      * An emit endpoint this manifest declares.
      */
-    emit: NamespacedId;
+    emit?: NamespacedId;
     /**
      * The event's payload: an object of that endpoint's declared returns.
      */
-    map: Expression;
+    map?: Expression;
+    /**
+     * The changes Initiative makes to the plug-in's values, as the install: a
+     * list of at most 100 targeted changes ('targetedChange'). Answering nothing
+     * changes nothing.
+     */
+    write?: Expression;
 }
 /**
  * A delivery that says what state a connection is in, read as an event's
@@ -1405,23 +1745,26 @@ export interface WebhookStatus {
 /**
  * What a plug-in declares it can do. A plug-in is a container, which names its
  * `service` and answers Initiative's calls, or declarative, which names its
- * `hosts` and no service, and whose endpoints, connection checks and webhook
- * events Initiative runs itself from the requests and JSONata expressions
- * written here; one plug-in is never both. This is the 'definition' field of
- * the document served at /.well-known/initiative-plugin.json, NOT that whole
- * document: a registrar also requires protocol_version, public_id and kind
- * alongside it, and refuses a definition served bare. Generated from the
- * platform's own validator vocabulary. A manifest that satisfies this schema is
- * well-formed, not necessarily acceptable. Cross-references (the endpoint a
- * widget binds, a requires term's connection, an endpoint's service prefix),
- * the direction-specific rules on an endpoint, the features/blocks cross-check
- * in both directions, UTF-8 byte-size caps, the rules tying a connection's flow
+ * `hosts` and no service, and whose endpoints, connection checks, webhook
+ * events, schedules and actions Initiative runs itself from the requests and
+ * JSONata expressions written here, keeping the values they write on items; one
+ * plug-in is never both. This is the 'definition' field of the document served
+ * at /.well-known/initiative-plugin.json, NOT that whole document: a registrar
+ * also requires protocol_version, public_id and kind alongside it, and refuses
+ * a definition served bare. Generated from the platform's own validator
+ * vocabulary. A manifest that satisfies this schema is well-formed, not
+ * necessarily acceptable. Cross-references (the endpoint a widget binds, a
+ * requires term's connection, an endpoint's service prefix), the
+ * direction-specific rules on an endpoint, the features/blocks cross-check in
+ * both directions, UTF-8 byte-size caps, the rules tying a connection's flow
  * and token to its scope and fields, what a webhooks block names, what a vendor
  * setup writes to, whether every expression parses, what a declarative request
- * and its steps name, the bounds and unique ids of schedules, the unique keys
- * and ids of fields, parts and actions, what a part's nodes and an action name,
- * and a part's size and depth are enforced by the platform on publish and are
- * not expressible here.
+ * and its steps name, the bounds, ids and endpoints of schedules, which terms
+ * each kind's schedules, actions, fields and webhook events take, the unique
+ * keys and ids of fields, parts, actions and settings, what a part's nodes, a
+ * field's element actions and an action's endpoint and params name, the
+ * placeholders in a part's text, and a part's size and depth are enforced by
+ * the platform on publish and are not expressible here.
  */
 export interface Manifest {
     /**
@@ -1443,12 +1786,20 @@ export interface Manifest {
         /**
          * The scopes this plug-in asks a community to grant: what its installation
          * and member tokens act with. The fixed scopes, and 'plugins:<public_id>'
-         * for each plug-in this one calls (at most 24 of those). The community
-         * grants some or all of them when it installs the plug-in, and a token
-         * never carries more than was granted. Writing implies reading. Absent
-         * means none.
+         * for each plug-in this one uses, to call its public endpoints and read the
+         * values it shows on items (at most 24 of those). The community grants some
+         * or all of them when it installs the plug-in, and a token never carries
+         * more than was granted. Writing implies reading. Absent means none.
          */
         scopes?: Array<Scope | PluginScope>;
+        /**
+         * This plug-in may act through any plug-in the community lets it use, not
+         * only those its scopes name as 'plugins:<public_id>'. When a community
+         * installs another plug-in, it is asked there whether this one may use it,
+         * which grants 'plugins:<public_id>' for it. Absent: only the plug-ins its
+         * scopes name.
+         */
+        calls_plugins?: boolean;
     };
     /**
      * What this plug-in contributes. Cross-checked against the blocks present in
@@ -1488,12 +1839,21 @@ export interface Manifest {
      * Declarative plug-ins only.
      */
     auth?: VendorAuth;
+    /**
+     * Declarative plug-ins: the scopes this plug-in asks a community to grant,
+     * all of them read scopes ('<resource>:read'). A declarative plug-in keeps
+     * its own values on items it can read and does not call Initiative, and
+     * Initiative keeps them only on items these scopes read. A container plug-in
+     * declares its scopes in its service block.
+     */
+    scopes?: Array<Scope | PluginScope>;
     vendor?: Vendor;
     connections?: Connection[];
     webhooks?: Webhooks;
     /**
-     * What Initiative calls the plug-in's schedule hook for, and how often. At
-     * most 8.
+     * What Initiative runs on an interval for each community: a container
+     * plug-in's schedule hook, or a declarative plug-in's read and the values it
+     * writes from the answer. At most 8.
      */
     schedules?: Schedule[];
     endpoints?: Endpoint[];
@@ -1515,21 +1875,33 @@ export interface Manifest {
      */
     dashboards?: BundledDashboard[];
     /**
-     * How the plug-in's metadata is shown on items. A container plug-in's only: a
-     * declarative plug-in holds no installation token, so it keeps no metadata to
-     * show.
+     * How the plug-in's values on items are shown there. Any plug-in may keep
+     * values on items: a container writes them with its installation token, and
+     * for a declarative plug-in Initiative writes them from the plug-in's
+     * expressions.
      */
     fields?: Field[];
     /**
      * Pieces of items' pages and views, built from Initiative's components and
-     * bound to the plug-in's fields and actions. A container plug-in's only, as
-     * fields are.
+     * bound to the plug-in's fields and actions.
      */
     parts?: Part[];
     /**
-     * What a reader may run on an item, each one of the plug-in's write
-     * endpoints. A container plug-in's only: a declarative plug-in has no handler
-     * to do an action's work.
+     * What a reader may run on an item: a container plug-in's write endpoints,
+     * which its handlers answer, or a declarative plug-in's calls and changes to
+     * its values, which Initiative makes.
      */
     actions?: Action[];
+    /**
+     * Values the community's admins set on the install, which the plug-in's
+     * expressions and its parts' text read. At most 16.
+     */
+    settings?: Setting[];
+    /**
+     * Help with the plug-in, keyed by language tag: markdown of at most 2000
+     * characters in each language. Initiative shows it behind a '?' on the
+     * headers of the plug-in's parts and on its settings, in the reader's
+     * language, or failing that in any.
+     */
+    help?: Record<string, string>;
 }