initiative-plugin-sdk 7.1.0 → 8.0.0

package/dist/statements.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Entitlement statements: what billing says a community holds of the plug-in,
+ * signed by billing and checked here.
+ *
+ * Billing signs each statement with its own Ed25519 key, a compact JWS with
+ * header `{alg: "EdDSA", typ: "initiative-entitlement+jwt", kid}` and claims
+ * `{iss: "initiative-billing", listing_uid, community_ref, version, values,
+ * iat}`. Initiative stores it and hands it on verbatim, on the `entitlement`
+ * hook and on `client.entitlement()`; it never signs one. The public half of
+ * billing's key reaches the plug-in from the deployment, as the runtime fact
+ * `entitlement_issuer_key` in {@link ENTITLEMENT_ISSUER_KEY_ENV}, so Initiative
+ * can withhold a statement but never mint one.
+ *
+ * A statement is checked in this order, and refused at the first failure:
+ *
+ * 1. the issuer key is configured and is Ed25519 (otherwise every statement is
+ *    refused, and why is logged once);
+ * 2. the header's `alg` is `EdDSA` and its `typ` is
+ *    `initiative-entitlement+jwt`, exactly: the header never picks the algorithm;
+ * 3. the Ed25519 signature over the JWS signing input;
+ * 4. `iss` is `initiative-billing`, `listing_uid` is the plug-in's own uid,
+ *    `version` is a whole number of one or more and `values` an object.
+ *
+ * Only then are `version` and `values` handed on, taken from the verified
+ * claims and nothing else.
+ *
+ * One gap stays, by design: `community_ref` is billing's pairwise reference,
+ * which the plug-in cannot relate to the community it is told the statement is
+ * for. Initiative vouches for that mapping, so a compromised Initiative could
+ * at worst copy a real, signed statement onto another community.
+ */
+/** The environment variable the deployment fills with billing's statement key (SPKI PEM). */
+export declare const ENTITLEMENT_ISSUER_KEY_ENV = "INITIATIVE_ENTITLEMENT_ISSUER_KEY_PEM";
+/** The runtime fact that names billing's statement key. */
+export declare const ENTITLEMENT_ISSUER_KEY_FACT = "entitlement_issuer_key";
+/** Who signs every statement. */
+export declare const ENTITLEMENT_ISSUER = "initiative-billing";
+/** A statement's JOSE `typ`. */
+export declare const ENTITLEMENT_STATEMENT_TYPE = "initiative-entitlement+jwt";
+/** Why a statement was refused. Each is counted as `refused-<reason>`. */
+export type EntitlementRefusal = 
+/** No issuer key is configured: the deployment runs no billing. */
+"no-key"
+/** The configured issuer key is not an Ed25519 public key. */
+ | "bad-key"
+/** Not a compact JWS with a JSON header. */
+ | "malformed" | "alg" | "typ" | "signature" | "iss"
+/** For another plug-in's listing. */
+ | "listing"
+/** `version` or `values` missing or of the wrong type. */
+ | "claims";
+/** A refused statement: `reason` is the counted outcome, `message` says it in words. */
+export declare class EntitlementStatementError extends Error {
+    readonly reason: EntitlementRefusal;
+    constructor(reason: EntitlementRefusal);
+}
+/** A statement that verified: what the plug-in is handed. */
+export interface VerifiedEntitlement {
+    version: number;
+    values: Record<string, unknown>;
+}
+export interface EntitlementStatementsOptions {
+    /** The plug-in's own listing uid; a statement for any other is refused. */
+    listingUid: string;
+    /**
+     * Billing's statement key, SPKI PEM (a PEM with literal `\n` or base64 of the
+     * PEM also do). Default: {@link ENTITLEMENT_ISSUER_KEY_ENV}. Absent, every
+     * statement is refused.
+     */
+    issuerKeyPem?: string | null;
+    /** Where the one warning about a missing or unusable key goes. Default: `console.warn`. */
+    warn?: (message: string) => void;
+}
+/**
+ * Checks billing's entitlement statements for one plug-in. The server makes one
+ * for its hook and its client; give one to an `Initiative` made by hand to read
+ * `client.entitlement()`.
+ */
+export declare class EntitlementStatements {
+    private readonly key;
+    private readonly listingUid;
+    private readonly warn;
+    private warned;
+    constructor(options: EntitlementStatementsOptions);
+    /**
+     * The statement's `version` and `values`, once it verifies, for the community
+     * Initiative names (`installation`, used only to count new unlimited grants).
+     * Throws {@link EntitlementStatementError} when it is refused.
+     */
+    verify(statement: unknown, installation: string): VerifiedEntitlement;
+    private check;
+}
+/** What the process has counted of entitlement statements since it started. */
+export interface EntitlementMetrics {
+    /** Statements by outcome: `applied`, or `refused-<reason>`. */
+    statements: Record<string, number>;
+    /** Grants of an unlimited allowance to a community that did not have one. */
+    unlimitedGrants: number;
+}
+/** A snapshot of the entitlement statement counters, for the plug-in's metrics endpoint. */
+export declare function entitlementMetrics(): EntitlementMetrics;
+/**
+ * The same counters in the Prometheus text format, to append to what the
+ * plug-in's metrics endpoint serves:
+ *
+ * - `initiative_plugin_entitlement_statements_total{outcome="…"}`
+ * - `initiative_plugin_entitlement_unlimited_grants_total`
+ *
+ * Alert on any `refused-*` and on any rise in unlimited grants.
+ */
+export declare function entitlementMetricsText(): string;

package/dist/statements.js

@@ -0,0 +1,205 @@
+/**
+ * Entitlement statements: what billing says a community holds of the plug-in,
+ * signed by billing and checked here.
+ *
+ * Billing signs each statement with its own Ed25519 key, a compact JWS with
+ * header `{alg: "EdDSA", typ: "initiative-entitlement+jwt", kid}` and claims
+ * `{iss: "initiative-billing", listing_uid, community_ref, version, values,
+ * iat}`. Initiative stores it and hands it on verbatim, on the `entitlement`
+ * hook and on `client.entitlement()`; it never signs one. The public half of
+ * billing's key reaches the plug-in from the deployment, as the runtime fact
+ * `entitlement_issuer_key` in {@link ENTITLEMENT_ISSUER_KEY_ENV}, so Initiative
+ * can withhold a statement but never mint one.
+ *
+ * A statement is checked in this order, and refused at the first failure:
+ *
+ * 1. the issuer key is configured and is Ed25519 (otherwise every statement is
+ *    refused, and why is logged once);
+ * 2. the header's `alg` is `EdDSA` and its `typ` is
+ *    `initiative-entitlement+jwt`, exactly: the header never picks the algorithm;
+ * 3. the Ed25519 signature over the JWS signing input;
+ * 4. `iss` is `initiative-billing`, `listing_uid` is the plug-in's own uid,
+ *    `version` is a whole number of one or more and `values` an object.
+ *
+ * Only then are `version` and `values` handed on, taken from the verified
+ * claims and nothing else.
+ *
+ * One gap stays, by design: `community_ref` is billing's pairwise reference,
+ * which the plug-in cannot relate to the community it is told the statement is
+ * for. Initiative vouches for that mapping, so a compromised Initiative could
+ * at worst copy a real, signed statement onto another community.
+ */
+import { createPublicKey, verify } from "node:crypto";
+/** The environment variable the deployment fills with billing's statement key (SPKI PEM). */
+export const ENTITLEMENT_ISSUER_KEY_ENV = "INITIATIVE_ENTITLEMENT_ISSUER_KEY_PEM";
+/** The runtime fact that names billing's statement key. */
+export const ENTITLEMENT_ISSUER_KEY_FACT = "entitlement_issuer_key";
+/** Who signs every statement. */
+export const ENTITLEMENT_ISSUER = "initiative-billing";
+/** A statement's JOSE `typ`. */
+export const ENTITLEMENT_STATEMENT_TYPE = "initiative-entitlement+jwt";
+const REASONS = {
+    "no-key": `no entitlement issuer key is configured (${ENTITLEMENT_ISSUER_KEY_ENV})`,
+    "bad-key": `the entitlement issuer key (${ENTITLEMENT_ISSUER_KEY_ENV}) is not an Ed25519 public key`,
+    malformed: "the statement is not a compact JWS",
+    alg: "the statement is not signed EdDSA",
+    typ: `the statement's typ is not ${ENTITLEMENT_STATEMENT_TYPE}`,
+    signature: "the statement's signature does not verify under the issuer key",
+    iss: `the statement is not issued by ${ENTITLEMENT_ISSUER}`,
+    listing: "the statement is for another plug-in",
+    claims: "the statement's version or values are not well formed",
+};
+/** A refused statement: `reason` is the counted outcome, `message` says it in words. */
+export class EntitlementStatementError extends Error {
+    reason;
+    constructor(reason) {
+        super(REASONS[reason]);
+        this.reason = reason;
+        this.name = "EntitlementStatementError";
+    }
+}
+/**
+ * Checks billing's entitlement statements for one plug-in. The server makes one
+ * for its hook and its client; give one to an `Initiative` made by hand to read
+ * `client.entitlement()`.
+ */
+export class EntitlementStatements {
+    key;
+    listingUid;
+    warn;
+    warned = false;
+    constructor(options) {
+        if (!options.listingUid)
+            throw new TypeError("listingUid is the plug-in's own listing uid");
+        this.listingUid = options.listingUid;
+        this.warn = options.warn ?? ((message) => console.warn(message));
+        const pem = options.issuerKeyPem === undefined ? process.env[ENTITLEMENT_ISSUER_KEY_ENV] : options.issuerKeyPem;
+        this.key = issuerKey(pem);
+    }
+    /**
+     * The statement's `version` and `values`, once it verifies, for the community
+     * Initiative names (`installation`, used only to count new unlimited grants).
+     * Throws {@link EntitlementStatementError} when it is refused.
+     */
+    verify(statement, installation) {
+        let verified;
+        try {
+            verified = this.check(statement);
+        }
+        catch (error) {
+            if (error instanceof EntitlementStatementError)
+                count(`refused-${error.reason}`);
+            throw error;
+        }
+        count("applied");
+        noteAllowance(this.listingUid, installation, verified.values);
+        return verified;
+    }
+    check(statement) {
+        if (typeof this.key === "string") {
+            if (!this.warned) {
+                this.warned = true;
+                this.warn(`entitlement statements are all refused: ${REASONS[this.key]}`);
+            }
+            throw new EntitlementStatementError(this.key);
+        }
+        const parts = typeof statement === "string" ? statement.split(".") : [];
+        // The signature may be empty here, as an unsigned (`alg: none`) token's is: the alg check refuses it by name.
+        if (parts.length !== 3 || !/^[A-Za-z0-9_-]+$/.test(parts[0]) || !/^[A-Za-z0-9_-]+$/.test(parts[1]) || !/^[A-Za-z0-9_-]*$/.test(parts[2])) {
+            throw new EntitlementStatementError("malformed");
+        }
+        const header = jsonOf(parts[0]);
+        if (!isRecord(header))
+            throw new EntitlementStatementError("malformed");
+        if (header.alg !== "EdDSA")
+            throw new EntitlementStatementError("alg");
+        if (header.typ !== ENTITLEMENT_STATEMENT_TYPE)
+            throw new EntitlementStatementError("typ");
+        const signature = Buffer.from(parts[2], "base64url");
+        if (!verify(null, Buffer.from(`${parts[0]}.${parts[1]}`), this.key, signature)) {
+            throw new EntitlementStatementError("signature");
+        }
+        const claims = jsonOf(parts[1]);
+        if (!isRecord(claims))
+            throw new EntitlementStatementError("claims");
+        if (claims.iss !== ENTITLEMENT_ISSUER)
+            throw new EntitlementStatementError("iss");
+        if (claims.listing_uid !== this.listingUid)
+            throw new EntitlementStatementError("listing");
+        const { version, values } = claims;
+        if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1 || !isRecord(values)) {
+            throw new EntitlementStatementError("claims");
+        }
+        return { version, values };
+    }
+}
+function issuerKey(pem) {
+    if (!pem)
+        return "no-key";
+    try {
+        const text = pem.includes("-----BEGIN") ? pem.replaceAll("\\n", "\n") : Buffer.from(pem, "base64").toString("utf-8");
+        const key = createPublicKey(text);
+        return key.asymmetricKeyType === "ed25519" ? key : "bad-key";
+    }
+    catch {
+        return "bad-key";
+    }
+}
+function jsonOf(part) {
+    try {
+        return JSON.parse(Buffer.from(part, "base64url").toString("utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Metrics, for alerts only: nothing here refuses a statement.
+const outcomes = new Map();
+let unlimitedGrants = 0;
+/** Whether each community's last verified statement granted an unlimited allowance, by listing and community. */
+const unlimited = new Map();
+function count(outcome) {
+    outcomes.set(outcome, (outcomes.get(outcome) ?? 0) + 1);
+}
+/**
+ * Count a grant of an unlimited allowance (`monthly_allowance` null) for a
+ * community whose last statement this process saw did not grant one. The
+ * memory is the process's own, so the first statement after a start counts
+ * when it grants one.
+ */
+function noteAllowance(listingUid, installation, values) {
+    const key = `${listingUid}\u0000${installation}`;
+    const isUnlimited = "monthly_allowance" in values && values.monthly_allowance === null;
+    if (isUnlimited && unlimited.get(key) !== true)
+        unlimitedGrants += 1;
+    unlimited.set(key, isUnlimited);
+}
+/** A snapshot of the entitlement statement counters, for the plug-in's metrics endpoint. */
+export function entitlementMetrics() {
+    return { statements: Object.fromEntries([...outcomes].sort(([a], [b]) => a.localeCompare(b))), unlimitedGrants };
+}
+/**
+ * The same counters in the Prometheus text format, to append to what the
+ * plug-in's metrics endpoint serves:
+ *
+ * - `initiative_plugin_entitlement_statements_total{outcome="…"}`
+ * - `initiative_plugin_entitlement_unlimited_grants_total`
+ *
+ * Alert on any `refused-*` and on any rise in unlimited grants.
+ */
+export function entitlementMetricsText() {
+    const { statements, unlimitedGrants: grants } = entitlementMetrics();
+    const lines = [
+        "# HELP initiative_plugin_entitlement_statements_total Entitlement statements, by outcome.",
+        "# TYPE initiative_plugin_entitlement_statements_total counter",
+        ...Object.entries(statements).map(([outcome, value]) => `initiative_plugin_entitlement_statements_total{outcome="${outcome}"} ${value}`),
+        "# HELP initiative_plugin_entitlement_unlimited_grants_total Grants of an unlimited allowance to a community that did not have one.",
+        "# TYPE initiative_plugin_entitlement_unlimited_grants_total counter",
+        `initiative_plugin_entitlement_unlimited_grants_total ${grants}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=statements.js.map

package/dist/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../src/statements.ts"],"names":[],"mappings":"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"}

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. */