initiative-plugin-sdk 7.2.0 → 8.0.0

package/dist/testing.d.ts

@@ -1,6 +1,6 @@
 /**
- * `initiative-plugin-sdk/testing`: a declarative plug-in's requests and mappings,
- * run against recorded vendor answers, with no server and no network.
+ * `initiative-plugin-sdk/testing`: a declarative plug-in's requests, mappings and
+ * writes, run against recorded vendor answers, with no server and no network.
  *
  * Each runner renders the requests the way Initiative makes them (method,
  * address with its query, headers, body), answers them from `responses` in
@@ -16,15 +16,28 @@
  *   to retry;
  * - `{ refused }`: an `after_connect` that refused the connection.
  *
+ * Every runner but {@link runExchangeBody}, whose expression reads only the
+ * connection's fields, takes the install's `settings`, each setting's value by
+ * key, and `aliases`, each unique setting's earlier values by key, which every
+ * other expression reads; both default to none.
+ *
+ * An action's run answers the `change` its `write` makes to the plug-in's values
+ * on the item, and a schedule's or a delivery's the targeted `writes`, each held
+ * to the contract's `change` or `targetedChange`, to one operation on each key,
+ * and to the plug-in's fields: a list field's whole value is a list of
+ * elements, and only a list's elements are upserted or removed. A `write`
+ * answering nothing changes nothing.
+ *
  * A rendered request carries no credential: Initiative adds the one its
  * `connection` names, as the plug-in's `auth` says. A predicate (`when`, `more`,
  * `refuse_when`) holds when JSONata's `$boolean` of its answer is true.
  *
  * A run fails, rather than answering, on a mistake in the test or the plug-in: a
  * request with no recorded response left for it, a recorded response nothing
- * asked for, or a mapped answer that does not fit the declared returns.
+ * asked for, a mapped answer that does not fit the declared returns, or a
+ * `write` answering what is not a change.
  */
-import type { ConnectionState } from "./contract.js";
+import type { ActorKind, Change, ConnectionState, ItemKind, TargetedChange } from "./contract.js";
 import type { AnyPlugin } from "./define.js";
 export { evaluate, ExpressionError, parseExpression } from "./expression.js";
 /** One answer the vendor gave, as a test records it. Status 200 and no headers when left out. */
@@ -39,7 +52,7 @@ export interface RenderedRequest {
     url: string;
     headers: Record<string, string>;
     body?: unknown;
-    /** The connection whose credential Initiative would add. */
+    /** The connection whose credential Initiative would add, for the call's actor when the request names one per actor. */
     connection?: string;
 }
 /** What a run made and what it answered. */
@@ -55,59 +68,157 @@ export type Run<T> = {
 } | {
     refused: string;
 });
+/** A declarative action's run: what it sent, and what its endpoint and its `write` answered. */
+export type ActionRun = {
+    requests: RenderedRequest[];
+} & ({
+    /** The endpoint's mapped answer, when the action names one. */
+    result?: Record<string, unknown>;
+    /** The change its `write` answered, when it has one that answered something. */
+    change?: Change;
+} | {
+    unavailable: string;
+    detail?: string;
+} | {
+    transient: true;
+});
+/** A declarative schedule's run: what it sent, the endpoint's mapped answer, and the changes its `write` answered. */
+export type ScheduleRun = {
+    requests: RenderedRequest[];
+} & ({
+    result: Record<string, unknown>;
+    writes: TargetedChange[];
+} | {
+    unavailable: string;
+    detail?: string;
+} | {
+    transient: true;
+});
 export interface Recorded {
     /** The vendor's answers, in the order the requests are made. */
     responses: RecordedResponse[];
     /** The time of the call: `now`, and what `$now()` and `$millis()` answer. Default: the present. */
     now?: Date | string | number;
 }
+/** The install's settings, as every expression reads them. */
+export interface InstallSettings {
+    /** Each setting's value, by key. */
+    settings?: Record<string, string>;
+    /** Each unique setting's earlier values, by key. */
+    aliases?: Record<string, string[]>;
+}
 /**
  * One declarative endpoint: its request or steps rendered from `params`, the
- * `connections`' non-secret fields (keyed by connection id) and `now`, answered
- * from `responses`, and its map held to the declared returns. An expression
- * reads `connection`, the fields of the connection its request names, and
- * `connections`, the fields of each connection the endpoint's `requires` names
- * that `connections` holds, by id. The call has no actor: who may run it, and
- * on whose credential, is Initiative's to decide.
+ * `connections`' non-secret fields (keyed by connection id), the install's
+ * `settings` and `aliases`, and `now`, answered from `responses`, and its map
+ * held to the declared returns. The call is made as `actor`, by default the
+ * endpoint's first: a request naming a connection per actor carries the one it
+ * names for that actor, and the run throws a TypeError when it names none. An
+ * expression reads `connection`, the fields of the connection its request
+ * carries, and `connections`, the fields of each connection the endpoint's
+ * `requires` names that `connections` holds, by id. Who may make the call is
+ * Initiative's to decide.
  */
-export declare function runEndpoint(plugin: AnyPlugin, name: string, call: Recorded & {
+export declare function runEndpoint(plugin: AnyPlugin, name: string, call: Recorded & InstallSettings & {
     params?: Record<string, unknown>;
     connections?: Record<string, Record<string, unknown>>;
+    /** Who the call is made as. Default: the endpoint's first actor. */
+    actor?: ActorKind;
 }): Promise<Run<Record<string, unknown>>>;
+/**
+ * A declarative action, run on one item with the `params` the reader answered,
+ * from one of a list field's elements when `element` names its `ref`. Its
+ * endpoint, when it names one, is sent those params, made as `actor` (by
+ * default the endpoint's first), and rendered and answered as
+ * {@link runEndpoint} does it, its expressions also reading `item` and
+ * `element`; an answer of unavailable or transient is the run's, and nothing is
+ * written. Its `write`, when it has one, then answers the change Initiative
+ * makes to the plug-in's values on the item, reading `item`, `held` (those
+ * values as they stand, by key), `result` (the endpoint's mapped answer, absent
+ * with no endpoint), `params`, `element`, `settings`, `aliases` and `now`. Like
+ * the endpoint's, an expression that fails answers `mapping-failed`.
+ */
+export declare function runAction(plugin: AnyPlugin, name: string, call: Omit<Recorded, "responses"> & InstallSettings & {
+    /** The vendor's answers to the endpoint's calls; none when the action names no endpoint. */
+    responses?: RecordedResponse[];
+    item: {
+        kind: ItemKind;
+        id: number;
+        title: string;
+    };
+    held?: Record<string, unknown>;
+    /** What the reader answered, for the params the action asks for. */
+    params?: Record<string, unknown>;
+    /** The `ref` of the list element it was run from. */
+    element?: string;
+    connections?: Record<string, Record<string, unknown>>;
+    /** Who its endpoint's call is made as. Default: the endpoint's first actor. */
+    actor?: ActorKind;
+}): Promise<ActionRun>;
+/**
+ * A declarative schedule's run in one community, made as the installation. Its
+ * `params` answer the endpoint's params from `since`, `now`, `connection` (the
+ * fields of the connection the endpoint's first request names), `settings` and
+ * `aliases`; the endpoint is rendered and answered with them as
+ * {@link runEndpoint} does it; and its `write` answers, from the endpoint's
+ * mapped answer as `result` beside `since`, `now`, `settings` and `aliases`,
+ * the changes Initiative makes as the install. `since` is when the schedule
+ * last succeeded there, as ISO 8601: null, the default, the first time.
+ */
+export declare function runSchedule(plugin: AnyPlugin, name: string, call: Recorded & InstallSettings & {
+    since?: string | null;
+    connections?: Record<string, Record<string, unknown>>;
+}): Promise<ScheduleRun>;
 /**
  * A declarative `after_connect`: its request or steps made with the flow's
  * `params`, mapped, and refused when it says. The map and `refuse_when` read
  * the last answer as `response` and, with steps, each one's as `steps.<name>`.
  */
-export declare function runAfterConnect(plugin: AnyPlugin, connection: string, call: Recorded & {
+export declare function runAfterConnect(plugin: AnyPlugin, connection: string, call: Recorded & InstallSettings & {
     params?: Record<string, string>;
 }): Promise<Run<{
     values?: Record<string, unknown>;
     account_label?: string;
 }>>;
 /** A connection's health check: its request made with the connection's non-secret `fields`, and the state it reads. */
-export declare function runHealth(plugin: AnyPlugin, connection: string, call: Recorded & {
+export declare function runHealth(plugin: AnyPlugin, connection: string, call: Recorded & InstallSettings & {
     fields?: Record<string, unknown>;
 }): Promise<Run<ConnectionState>>;
-/** What one delivery emits, and the connection state it sets. */
+/**
+ * The body Initiative posts with a connection's signed JWT, from its token's
+ * `exchange_body`: the object with each `{vendor.<key>}` in its strings filled
+ * from `vendor` and each `{<key>}` from the connection's non-secret `fields`,
+ * or the expression's answer, which reads those fields as `connection` and
+ * nothing else. It throws a TypeError where Initiative fails the token request,
+ * on a name with no value or an answer that is not an object, and for a
+ * connection with no `exchange_body`; an expression that fails throws
+ * {@link ExpressionError}.
+ */
+export declare function runExchangeBody(plugin: AnyPlugin, connection: string, call?: {
+    fields?: Record<string, unknown>;
+    vendor?: Record<string, string>;
+}): Promise<Record<string, unknown>>;
+/** What one delivery emits, the changes it makes, and the connection state it sets. */
 export interface WebhookRun {
     event?: {
         emit: string;
         payload: Record<string, unknown>;
     };
+    /** The targeted changes the matching `events` row's `write` answered, when it has one. */
+    writes?: TargetedChange[];
     status?: {
         connection: string;
         state: ConnectionState;
     };
 }
 /**
- * One webhook delivery, as a declarative plug-in maps it: the event the first
- * matching `events` row emits (by the emit endpoint's key, its payload held to
- * that endpoint's returns), and the state the first matching `status` row
- * sets. A delivery nothing matches answers neither. An expression that fails
- * throws {@link ExpressionError}.
+ * One webhook delivery, as a declarative plug-in maps it: the first matching
+ * `events` row's event (by the emit endpoint's key, its payload held to that
+ * endpoint's returns) and the changes its `write` answers, and the state the
+ * first matching `status` row sets. A delivery nothing matches answers neither.
+ * An expression that fails throws {@link ExpressionError}.
  */
-export declare function runWebhook(plugin: AnyPlugin, delivery: {
+export declare function runWebhook(plugin: AnyPlugin, delivery: InstallSettings & {
     headers?: Record<string, string>;
     payload: unknown;
     /** The routed connection's non-secret fields. */

package/dist/testing.js

@@ -1,6 +1,6 @@
 /**
- * `initiative-plugin-sdk/testing`: a declarative plug-in's requests and mappings,
- * run against recorded vendor answers, with no server and no network.
+ * `initiative-plugin-sdk/testing`: a declarative plug-in's requests, mappings and
+ * writes, run against recorded vendor answers, with no server and no network.
  *
  * Each runner renders the requests the way Initiative makes them (method,
  * address with its query, headers, body), answers them from `responses` in
@@ -16,16 +16,30 @@
  *   to retry;
  * - `{ refused }`: an `after_connect` that refused the connection.
  *
+ * Every runner but {@link runExchangeBody}, whose expression reads only the
+ * connection's fields, takes the install's `settings`, each setting's value by
+ * key, and `aliases`, each unique setting's earlier values by key, which every
+ * other expression reads; both default to none.
+ *
+ * An action's run answers the `change` its `write` makes to the plug-in's values
+ * on the item, and a schedule's or a delivery's the targeted `writes`, each held
+ * to the contract's `change` or `targetedChange`, to one operation on each key,
+ * and to the plug-in's fields: a list field's whole value is a list of
+ * elements, and only a list's elements are upserted or removed. A `write`
+ * answering nothing changes nothing.
+ *
  * A rendered request carries no credential: Initiative adds the one its
  * `connection` names, as the plug-in's `auth` says. A predicate (`when`, `more`,
  * `refuse_when`) holds when JSONata's `$boolean` of its answer is true.
  *
  * A run fails, rather than answering, on a mistake in the test or the plug-in: a
  * request with no recorded response left for it, a recorded response nothing
- * asked for, or a mapped answer that does not fit the declared returns.
+ * asked for, a mapped answer that does not fit the declared returns, or a
+ * `write` answering what is not a change.
  */
-import { PLATFORM_CODES } from "./contract.js";
+import { CAPS, PLATFORM_CODES } from "./contract.js";
 import { evaluate, ExpressionError } from "./expression.js";
+import { definitionValidator } from "./validate.js";
 export { evaluate, ExpressionError, parseExpression } from "./expression.js";
 /** A run's answer, thrown from wherever it is decided. */
 class Outcome {
@@ -37,17 +51,24 @@ class Outcome {
 class Context {
     hosts;
     rules;
+    actor;
     requests = [];
     now;
+    /** What every expression reads of the install. */
+    installed;
     clock;
     responses;
     constructor(hosts, recorded, 
     /** The endpoint's own rules, and whether an answer outside 2xx fails the run. */
-    rules) {
+    rules, 
+    /** Who the call is made as, when it is made as one of an endpoint's actors. */
+    actor) {
         this.hosts = hosts;
         this.rules = rules;
+        this.actor = actor;
         this.clock = recorded.now ?? new Date();
         this.now = new Date(this.clock).toISOString();
+        this.installed = { settings: recorded.settings ?? {}, aliases: recorded.aliases ?? {} };
         this.responses = [...recorded.responses];
     }
     async value(text, document, where) {
@@ -60,6 +81,17 @@ class Context {
             throw new Outcome({ unavailable: "mapping-failed", detail: `${where}: ${error.message}` });
         }
     }
+    /** The connection a request names, for the call's actor when it names one per actor. */
+    connection(request, where) {
+        const named = request.connection;
+        if (typeof named !== "object")
+            return named;
+        const id = this.actor === undefined ? undefined : named[this.actor];
+        if (id === undefined) {
+            throw new TypeError(`${where} names no connection for ${this.actor === undefined ? "a call with no actor" : `the ${this.actor}`}`);
+        }
+        return id;
+    }
     async holds(text, document, where) {
         return (await evaluate("$boolean($)", await this.value(text, document, where))) === true;
     }
@@ -169,12 +201,13 @@ async function render(request, document, context, where, page) {
         }
         body = { query: request.graphql.query, ...(variables === undefined ? {} : { variables }) };
     }
+    const connection = context.connection(request, where);
     return {
         method: request.method,
         url: url.toString(),
         headers,
         ...(body === undefined ? {} : { body }),
-        ...(request.connection ? { connection: request.connection } : {}),
+        ...(connection ? { connection } : {}),
     };
 }
 /**
@@ -255,48 +288,190 @@ function fits(answer, returns, where) {
     return answer;
 }
 /**
- * One declarative endpoint: its request or steps rendered from `params`, the
- * `connections`' non-secret fields (keyed by connection id) and `now`, answered
- * from `responses`, and its map held to the declared returns. An expression
- * reads `connection`, the fields of the connection its request names, and
- * `connections`, the fields of each connection the endpoint's `requires` names
- * that `connections` holds, by id. The call has no actor: who may run it, and
- * on whose credential, is Initiative's to decide.
+ * Holds what a `write` answered to the contract's definition `name`, `change`
+ * or `targetedChange`, to one operation on each key, and to the plug-in's
+ * fields: a list field's whole value is a list of elements, and only a list's
+ * elements are upserted or removed. Each value, and each element, is held to
+ * the cap on one value.
  */
-export async function runEndpoint(plugin, name, call) {
+function fitsChange(plugin, answer, name, where) {
+    const check = definitionValidator(name);
+    if (!check(answer)) {
+        const why = (check.errors ?? []).map((error) => `${error.instancePath || "/"} ${error.message}`).join("; ");
+        throw new Error(`${where} answered ${text(answer)}, which is not a ${name === "change" ? "change" : "targeted change"}: ${why}`);
+    }
+    const { set = {}, upsert = {}, remove = {} } = answer;
+    const keys = [...Object.keys(set), ...Object.keys(upsert), ...Object.keys(remove)];
+    const twice = keys.find((key, index) => keys.indexOf(key) !== index);
+    if (twice !== undefined)
+        throw new Error(`${where} changes '${twice}' twice: a change sets, upserts or removes a key`);
+    const list = (key) => plugin.fields?.[key]?.list === true;
+    for (const key of [...Object.keys(upsert), ...Object.keys(remove)]) {
+        if (!list(key))
+            throw new Error(`${where} changes elements of '${key}', which is not a list field`);
+    }
+    const values = Object.entries(upsert).flatMap(([key, elements]) => elements.map((element) => [key, element]));
+    const element = definitionValidator("listElement");
+    for (const [key, value] of Object.entries(set)) {
+        if (value === null)
+            continue;
+        if (!list(key))
+            values.push([key, value]);
+        else if (Array.isArray(value) && value.every((one) => element(one)))
+            values.push(...value.map((one) => [key, one]));
+        else
+            throw new Error(`${where} sets '${key}', a list field, to ${text(value)}, which is not a list of elements`);
+    }
+    for (const [key, value] of values) {
+        if (Buffer.byteLength(JSON.stringify(value), "utf-8") > CAPS.metadataValueBytes) {
+            throw new Error(`${where} gives '${key}' a value of more than ${CAPS.metadataValueBytes} bytes as JSON`);
+        }
+    }
+}
+/** What a `write` answered, as targeted changes: a list of at most `writeTargets`. Nothing is no change. */
+function targeted(plugin, answer, where) {
+    if (answer === undefined)
+        return [];
+    if (!Array.isArray(answer)) {
+        throw new Error(`${where} answered ${text(answer)}, which is not a list of targeted changes ` +
+            "(a JSONata path matching one item answers it alone: wrap the answer in [ ] to keep a list)");
+    }
+    if (answer.length > CAPS.writeTargets)
+        throw new Error(`${where} answered ${answer.length} changes, more than ${CAPS.writeTargets}`);
+    answer.forEach((change, index) => fitsChange(plugin, change, "targetedChange", `${where}/${index}`));
+    return answer;
+}
+/** A declarative endpoint of the plug-in, by its key. */
+function declarative(plugin, name) {
     const endpoint = plugin.endpoints?.[name];
     if (!endpoint || !("map" in endpoint))
         throw new TypeError(`'${name}' is not a declarative endpoint of this plug-in`);
-    const context = new Context(plugin.hosts ?? [], call, endpoint.errors ?? []);
-    return context.run(async () => {
-        const given = call.connections ?? {};
-        const required = [...(endpoint.requires?.all_of ?? []), ...(endpoint.requires?.any_of ?? [])];
-        const connections = Object.fromEntries(required.filter((id) => Object.hasOwn(given, id)).map((id) => [id, given[id]]));
-        const base = { params: call.params ?? {}, connections, now: context.now };
-        const steps = endpoint.steps ?? [{ name: "", request: endpoint.request }];
-        const answers = {};
-        let read = base;
-        for (const [index, step] of steps.entries()) {
-            read = {
-                ...base,
-                connection: call.connections?.[step.request.connection ?? ""] ?? {},
-                ...(endpoint.steps ? { steps: { ...answers } } : {}),
-            };
-            const where = endpoint.steps ? `steps/${index}/request` : "request";
-            const response = await perform(step.request, read, context, where);
-            if (endpoint.steps)
-                answers[step.name] = response;
-            read = { ...read, ...(endpoint.steps ? { steps: { ...answers } } : {}), response };
+    return endpoint;
+}
+/**
+ * One declarative endpoint's request or steps, answered in `context`, and its
+ * map held to the declared returns: what {@link runEndpoint} runs, and what an
+ * action or a schedule runs for the endpoint it names. An action's call also
+ * reads its `subject`: the `item`, and the `element` it was run from.
+ */
+async function answerEndpoint(endpoint, call, context) {
+    const given = call.connections ?? {};
+    const required = [...(endpoint.requires?.all_of ?? []), ...(endpoint.requires?.any_of ?? [])];
+    const connections = Object.fromEntries(required.filter((id) => Object.hasOwn(given, id)).map((id) => [id, given[id]]));
+    const base = { params: call.params ?? {}, connections, now: context.now, ...context.installed, ...call.subject };
+    const steps = endpoint.steps ?? [{ name: "", request: endpoint.request }];
+    const answers = {};
+    let read = base;
+    for (const [index, step] of steps.entries()) {
+        const where = endpoint.steps ? `steps/${index}/request` : "request";
+        read = {
+            ...base,
+            connection: given[context.connection(step.request, where) ?? ""] ?? {},
+            ...(endpoint.steps ? { steps: { ...answers } } : {}),
+        };
+        const response = await perform(step.request, read, context, where);
+        if (endpoint.steps)
+            answers[step.name] = response;
+        read = { ...read, ...(endpoint.steps ? { steps: { ...answers } } : {}), response };
+    }
+    const answer = await context.value(endpoint.map, read, "map");
+    if (answer && typeof answer === "object" && "unavailable" in answer) {
+        const code = answer.unavailable;
+        if (typeof code !== "string" || ![...(endpoint.unavailable ?? []), ...PLATFORM_CODES].includes(code)) {
+            throw new Error(`map answered unavailable ${text(code)}, which is not one of this endpoint's codes`);
         }
-        const answer = await context.value(endpoint.map, read, "map");
-        if (answer && typeof answer === "object" && "unavailable" in answer) {
-            const code = answer.unavailable;
-            if (typeof code !== "string" || ![...(endpoint.unavailable ?? []), ...PLATFORM_CODES].includes(code)) {
-                throw new Error(`map answered unavailable ${text(code)}, which is not one of this endpoint's codes`);
-            }
-            return { unavailable: code };
+        return { unavailable: code };
+    }
+    return { result: fits(answer, endpoint.returns, "map") };
+}
+/**
+ * One declarative endpoint: its request or steps rendered from `params`, the
+ * `connections`' non-secret fields (keyed by connection id), the install's
+ * `settings` and `aliases`, and `now`, answered from `responses`, and its map
+ * held to the declared returns. The call is made as `actor`, by default the
+ * endpoint's first: a request naming a connection per actor carries the one it
+ * names for that actor, and the run throws a TypeError when it names none. An
+ * expression reads `connection`, the fields of the connection its request
+ * carries, and `connections`, the fields of each connection the endpoint's
+ * `requires` names that `connections` holds, by id. Who may make the call is
+ * Initiative's to decide.
+ */
+export async function runEndpoint(plugin, name, call) {
+    const endpoint = declarative(plugin, name);
+    const context = new Context(plugin.hosts ?? [], call, endpoint.errors ?? [], call.actor ?? endpoint.actors?.[0]);
+    return context.run(() => answerEndpoint(endpoint, call, context));
+}
+/**
+ * A declarative action, run on one item with the `params` the reader answered,
+ * from one of a list field's elements when `element` names its `ref`. Its
+ * endpoint, when it names one, is sent those params, made as `actor` (by
+ * default the endpoint's first), and rendered and answered as
+ * {@link runEndpoint} does it, its expressions also reading `item` and
+ * `element`; an answer of unavailable or transient is the run's, and nothing is
+ * written. Its `write`, when it has one, then answers the change Initiative
+ * makes to the plug-in's values on the item, reading `item`, `held` (those
+ * values as they stand, by key), `result` (the endpoint's mapped answer, absent
+ * with no endpoint), `params`, `element`, `settings`, `aliases` and `now`. Like
+ * the endpoint's, an expression that fails answers `mapping-failed`.
+ */
+export async function runAction(plugin, name, call) {
+    const action = plugin.actions?.[name];
+    if (!action)
+        throw new TypeError(`'${name}' is not an action of this plug-in`);
+    if (!action.on.includes(call.item.kind))
+        throw new TypeError(`'${name}' is not offered on ${call.item.kind}`);
+    const unasked = Object.keys(call.params ?? {}).find((key) => !action.params?.includes(key));
+    if (unasked !== undefined)
+        throw new TypeError(`'${name}' does not ask for '${unasked}'`);
+    if (call.element !== undefined && !Object.values(plugin.fields ?? {}).some((field) => field.actions?.includes(name))) {
+        throw new TypeError(`'${name}' is offered on no list's elements`);
+    }
+    const endpoint = action.endpoint === undefined ? undefined : declarative(plugin, action.endpoint);
+    const context = new Context(plugin.hosts ?? [], { ...call, responses: call.responses ?? [] }, endpoint?.errors ?? [], call.actor ?? endpoint?.actors?.[0]);
+    const subject = { item: call.item, ...(call.element === undefined ? {} : { element: call.element }) };
+    return context.run(async () => {
+        const sent = { params: call.params, connections: call.connections, subject };
+        const called = endpoint && (await answerEndpoint(endpoint, sent, context));
+        if (called && !("result" in called))
+            return called;
+        const read = { ...subject, held: call.held ?? {}, ...called, params: call.params ?? {}, ...context.installed, now: context.now };
+        const change = action.write === undefined ? undefined : await context.value(action.write, read, "write");
+        if (change !== undefined)
+            fitsChange(plugin, change, "change", "write");
+        return { ...called, ...(change === undefined ? {} : { change: change }) };
+    });
+}
+/**
+ * A declarative schedule's run in one community, made as the installation. Its
+ * `params` answer the endpoint's params from `since`, `now`, `connection` (the
+ * fields of the connection the endpoint's first request names), `settings` and
+ * `aliases`; the endpoint is rendered and answered with them as
+ * {@link runEndpoint} does it; and its `write` answers, from the endpoint's
+ * mapped answer as `result` beside `since`, `now`, `settings` and `aliases`,
+ * the changes Initiative makes as the install. `since` is when the schedule
+ * last succeeded there, as ISO 8601: null, the default, the first time.
+ */
+export async function runSchedule(plugin, name, call) {
+    const schedule = plugin.schedules?.[name];
+    if (!schedule || "run" in schedule)
+        throw new TypeError(`'${name}' is not a declarative schedule of this plug-in`);
+    const endpoint = declarative(plugin, schedule.endpoint);
+    const context = new Context(plugin.hosts ?? [], call, endpoint.errors ?? [], "installation");
+    return context.run(async () => {
+        const since = call.since ?? null;
+        const first = endpoint.steps?.[0].request ?? endpoint.request;
+        const connection = call.connections?.[context.connection(first, endpoint.steps ? "steps/0/request" : "request") ?? ""] ?? {};
+        const read = { since, now: context.now, ...context.installed };
+        const params = schedule.params === undefined ? undefined : await context.value(schedule.params, { ...read, connection }, "params");
+        if (params !== undefined && (!params || typeof params !== "object" || Array.isArray(params))) {
+            throw new Error(`params answered ${text(params)}, which is not an object of the endpoint's params`);
         }
-        return { result: fits(answer, endpoint.returns, "map") };
+        const sent = { params: params, connections: call.connections };
+        const called = await answerEndpoint(endpoint, sent, context);
+        if (!("result" in called))
+            return called;
+        const writes = targeted(plugin, await context.value(schedule.write, { result: called.result, ...read }, "write"), "write");
+        return { result: called.result, writes };
     });
 }
 /**
@@ -310,7 +485,7 @@ export async function runAfterConnect(plugin, connection, call) {
         throw new TypeError(`'${connection}' has no declarative after_connect`);
     const context = new Context(plugin.hosts ?? [], call, []);
     return context.run(async () => {
-        const base = { params: call.params ?? {}, now: context.now };
+        const base = { params: call.params ?? {}, now: context.now, ...context.installed };
         const steps = after.steps ?? [{ name: "", request: after.request }];
         const answers = {};
         let read = base;
@@ -339,7 +514,7 @@ export async function runHealth(plugin, connection, call) {
         throw new TypeError(`'${connection}' declares no health check`);
     const context = new Context(plugin.hosts ?? [], call, null);
     return context.run(async () => {
-        const document = { params: {}, connection: call.fields ?? {}, now: context.now };
+        const document = { params: {}, connection: call.fields ?? {}, now: context.now, ...context.installed };
         const response = await perform(health.request, document, context, "health/request");
         for (const [index, row] of health.states.entries()) {
             if (row.status !== undefined && !matches(row.status, response.status))
@@ -352,11 +527,52 @@ export async function runHealth(plugin, connection, call) {
     });
 }
 /**
- * One webhook delivery, as a declarative plug-in maps it: the event the first
- * matching `events` row emits (by the emit endpoint's key, its payload held to
- * that endpoint's returns), and the state the first matching `status` row
- * sets. A delivery nothing matches answers neither. An expression that fails
- * throws {@link ExpressionError}.
+ * The body Initiative posts with a connection's signed JWT, from its token's
+ * `exchange_body`: the object with each `{vendor.<key>}` in its strings filled
+ * from `vendor` and each `{<key>}` from the connection's non-secret `fields`,
+ * or the expression's answer, which reads those fields as `connection` and
+ * nothing else. It throws a TypeError where Initiative fails the token request,
+ * on a name with no value or an answer that is not an object, and for a
+ * connection with no `exchange_body`; an expression that fails throws
+ * {@link ExpressionError}.
+ */
+export async function runExchangeBody(plugin, connection, call = {}) {
+    const body = plugin.connections?.[connection]?.token?.exchange_body;
+    if (body === undefined)
+        throw new TypeError(`'${connection}' declares no exchange_body`);
+    const fields = call.fields ?? {};
+    if (typeof body === "string") {
+        const answer = await evaluate(body, { connection: fields });
+        if (!answer || typeof answer !== "object" || Array.isArray(answer)) {
+            throw new TypeError(`exchange_body answered ${text(answer)}, which is not an object`);
+        }
+        return answer;
+    }
+    const filled = (value, where) => {
+        if (typeof value === "string") {
+            return value.replace(/\{([^}]*)\}/g, (_, name) => {
+                const [values, key] = name.startsWith("vendor.") ? [call.vendor ?? {}, name.slice("vendor.".length)] : [fields, name];
+                const given = Object.hasOwn(values, key) ? values[key] : undefined;
+                if (given === undefined || given === null || given === "")
+                    throw new TypeError(`${where} names '{${name}}', which has no value`);
+                return text(given);
+            });
+        }
+        if (Array.isArray(value))
+            return value.map((child, index) => filled(child, `${where}/${index}`));
+        if (value && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, filled(child, `${where}/${key}`)]));
+        }
+        return value;
+    };
+    return filled(body, "exchange_body");
+}
+/**
+ * One webhook delivery, as a declarative plug-in maps it: the first matching
+ * `events` row's event (by the emit endpoint's key, its payload held to that
+ * endpoint's returns) and the changes its `write` answers, and the state the
+ * first matching `status` row sets. A delivery nothing matches answers neither.
+ * An expression that fails throws {@link ExpressionError}.
  */
 export async function runWebhook(plugin, delivery) {
     const clock = delivery.now ?? new Date();
@@ -365,14 +581,20 @@ export async function runWebhook(plugin, delivery) {
         payload: delivery.payload,
         connection: delivery.connection ?? {},
         now: new Date(clock).toISOString(),
+        settings: delivery.settings ?? {},
+        aliases: delivery.aliases ?? {},
     };
     const holds = async (expression) => (await evaluate("$boolean($)", await evaluate(expression, document, { now: clock }))) === true;
     const out = {};
     for (const row of plugin.webhooks?.events ?? []) {
         if (!(await holds(row.when)))
             continue;
-        const payload = await evaluate(row.map, document, { now: clock });
-        out.event = { emit: row.emit, payload: fits(payload, plugin.endpoints?.[row.emit]?.returns, `the ${row.emit} event`) };
+        if (row.emit !== undefined) {
+            const payload = await evaluate(row.map, document, { now: clock });
+            out.event = { emit: row.emit, payload: fits(payload, plugin.endpoints?.[row.emit]?.returns, `the ${row.emit} event`) };
+        }
+        if (row.write !== undefined)
+            out.writes = targeted(plugin, await evaluate(row.write, document, { now: clock }), "write");
         break;
     }
     for (const row of plugin.webhooks?.status ?? []) {