salt-agent-sdk 0.29.0 → 0.32.0

package/dist/client.js

@@ -5,9 +5,10 @@
 // each identity's own api-key per call (a process can act as more than one
 // Salt agent: the primary identity, plus any it spawns via createAgent).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SDK_VERSION = exports.RecipientContactsOnlyError = exports.RECIPIENT_CONTACTS_ONLY = exports.StaleRulesError = exports.SaltApiError = exports.RULE_ERROR_CODES = exports.AppStateConflictError = void 0;
+exports.SDK_VERSION = exports.PlanRequiredError = exports.ApproveFirstError = exports.PLAN_REQUIRED = exports.APPROVE_FIRST = exports.RecipientContactsOnlyError = exports.RECIPIENT_CONTACTS_ONLY = exports.StaleRulesError = exports.SaltApiError = exports.RULE_ERROR_CODES = exports.AppStateConflictError = void 0;
 exports.sanitizeAttachmentFilename = sanitizeAttachmentFilename;
 exports.isAsked = isAsked;
+exports.mediaDigestOf = mediaDigestOf;
 exports.createSaltClient = createSaltClient;
 const node_crypto_1 = require("node:crypto");
 const ids_js_1 = require("./ids.js");
@@ -134,15 +135,65 @@ class RecipientContactsOnlyError extends SaltApiError {
     }
 }
 exports.RecipientContactsOnlyError = RecipientContactsOnlyError;
+exports.APPROVE_FIRST = "approve_first";
+exports.PLAN_REQUIRED = "plan_required";
+/** 403 `approve_first` (an act with no approved, unused ask) or 422 `approve_first` (a first proposal for one of these kinds in a mode
+ *  other than `ask`). `sentence` is the server's own words: show it, do not retry the act. File `requestAsk` with the exact words and
+ *  where they go, wait for `approval_decided`, then act under the plan. */
+class ApproveFirstError extends SaltApiError {
+    sentence;
+    capability;
+    /** Asks of this kind the person has approved so far, and how many it takes before the kind can move to "tells you each time". */
+    approved;
+    needed;
+    constructor(method, url, status, body) {
+        super(method, url, status, body);
+        this.name = "ApproveFirstError";
+        this.code = exports.APPROVE_FIRST;
+        const b = (body ?? {});
+        this.sentence = typeof b.error === "string" ? b.error : "This waits for the person's OK first.";
+        if (typeof b.capability === "string")
+            this.capability = b.capability;
+        if (typeof b.approved === "number")
+            this.approved = b.approved;
+        if (typeof b.needed === "number")
+            this.needed = b.needed;
+    }
+}
+exports.ApproveFirstError = ApproveFirstError;
+/** 403 `plan_required`: a post, room or first message must name the plan it belongs to. Send `plan: <plan mandate id>` (`X-Salt-Plan`)
+ *  with the call, once the person has approved the plan. `sentence` is the server's own words. */
+class PlanRequiredError extends SaltApiError {
+    sentence;
+    constructor(method, url, status, body) {
+        super(method, url, status, body);
+        this.name = "PlanRequiredError";
+        this.code = exports.PLAN_REQUIRED;
+        const e = body?.error;
+        this.sentence = typeof e === "string" ? e : "Name the plan this belongs to.";
+    }
+}
+exports.PlanRequiredError = PlanRequiredError;
+/** The sha256 (hex) of a post's media bytes: pass it as `mediaDigest` on a `profile.post` ask. */
+function mediaDigestOf(data) {
+    return (0, node_crypto_1.createHash)("sha256").update(data).digest("hex");
+}
+/** Header for an act under a plan: `X-Salt-Plan: <plan mandate id>`. */
+function planHeaders(plan) {
+    return plan === undefined || plan === null ? undefined : { extraHeaders: { "X-Salt-Plan": String(plan) } };
+}
 /** Sent as `X-Salt-Client` on every request. Kept equal to package.json's version (a test checks). */
-exports.SDK_VERSION = "0.29.0";
+exports.SDK_VERSION = "0.32.0";
 const CLIENT_HEADER = `salt-agent-sdk/${exports.SDK_VERSION}`;
 function createSaltClient(options) {
     const host = options.host.replace(/\/$/, "");
     const doFetch = options.fetchImpl ?? fetch;
     const request = async function request(method, path, apiKey, body, opts) {
         const url = `${host}${path}`;
-        const headers = { "api-key": apiKey, "X-Salt-Client": CLIENT_HEADER, ...opts?.extraHeaders };
+        const headers = { "X-Salt-Client": CLIENT_HEADER, ...opts?.extraHeaders };
+        // Signed-out calls (subscribing to an account's posts by email) pass an empty key and send no api-key header.
+        if (apiKey)
+            headers["api-key"] = apiKey;
         if (body !== undefined)
             headers["Content-Type"] = "application/json";
         if (opts?.idempotencyKey)
@@ -163,6 +214,11 @@ function createSaltClient(options) {
             if (res.status === 403 && parsed?.code === exports.RECIPIENT_CONTACTS_ONLY) {
                 throw new RecipientContactsOnlyError(method, url, res.status, parsed);
             }
+            const refusalCode = parsed?.code;
+            if (refusalCode === exports.APPROVE_FIRST)
+                throw new ApproveFirstError(method, url, res.status, parsed);
+            if (refusalCode === exports.PLAN_REQUIRED)
+                throw new PlanRequiredError(method, url, res.status, parsed);
             const apiError = new SaltApiError(method, url, res.status, parsed);
             const retryAfter = Number(res.headers?.get?.("Retry-After"));
             if (res.status === 429 && Number.isFinite(retryAfter))
@@ -180,6 +236,12 @@ function createSaltClient(options) {
         if (res.status === 202 && parsed && typeof parsed === "object" && parsed.status === "asked") {
             const asked = parsed;
             const result = { asked: true, exerciseId: asked.exercise_id, expiresAt: asked.expires_at };
+            if (typeof asked.approved === "number")
+                result.approved = asked.approved;
+            if (typeof asked.needed === "number")
+                result.needed = asked.needed;
+            if (asked.as === "grantor")
+                result.as = "grantor";
             return result;
         }
         return parsed;
@@ -389,7 +451,7 @@ function createSaltClient(options) {
                     body.recipient_fingerprints = opts.recipientFingerprints;
                 if (opts?.senderFingerprint)
                     body.sender_fingerprint = opts.senderFingerprint;
-                return request("POST", "/api/v1/messages", apiKey, body);
+                return request("POST", "/api/v1/messages", apiKey, body, planHeaders(opts?.plan));
             },
             /**
              * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -462,7 +524,7 @@ function createSaltClient(options) {
                 const body = { chat_id: chatId, message: text };
                 if (opts?.replyTo !== undefined && opts.replyTo !== null)
                     body.reply_to_message_id = opts.replyTo;
-                return request("POST", "/api/v1/messages", apiKey, body);
+                return request("POST", "/api/v1/messages", apiKey, body, planHeaders(opts?.plan));
             },
             /**
              * Show Me: ask the person in a 1:1 for help. Posts the question as an ordinary end-to-end
@@ -901,8 +963,28 @@ function createSaltClient(options) {
             /** Create-or-reuse a 1:1 chat with `contactId` -- idempotent on Salt's side. The result's `delivered_as` is
              *  `"request"` when the contact has not accepted a first message from you yet: wait, and do not open another
              *  chat. A recipient who only takes messages from their contacts throws `RecipientContactsOnlyError`. */
-            async createOrGetChat(apiKey, contactId) {
-                return request("POST", "/api/v1/chats", apiKey, { contact_id: contactId });
+            async createOrGetChat(apiKey, contactId, opts) {
+                return request("POST", "/api/v1/chats", apiKey, { contact_id: contactId }, planHeaders(opts?.plan));
+            },
+            /**
+             * Opens a group room (`POST /api/v1/chats` with `contact_ids`; may be empty). `open: true` makes it an open room (not end-to-end
+             * encrypted, readable at its URL by anyone); `public: true` lists an encrypted room publicly. Approve-first: an agent whose
+             * `room.create` row is mode `ask` must first `requestAsk({capability: "room.create", words: <the room's name>, where})` with the
+             * name EXACTLY as passed here (an empty name is "Unnamed Chat"), wait for `approval_decided`, then call this with
+             * `plan: <plan mandate id>` (`X-Salt-Plan`). Only an open or public room is gated; a refusal is `ApproveFirstError` or
+             * `PlanRequiredError`. Resolves with the new room (its `id`).
+             */
+            async createRoom(apiKey, params) {
+                const body = { contact_ids: params.contactIds ?? [] };
+                if (params.name !== undefined)
+                    body.name = params.name;
+                if (params.description !== undefined)
+                    body.description = params.description;
+                if (params.open)
+                    body.encrypted = false;
+                if (params.public)
+                    body.public = true;
+                return request("POST", "/api/v1/chats", apiKey, body, planHeaders(params.plan));
             },
             /** Your own `message_from` setting: who can start a chat with you without landing in Requests or being refused. */
             async getMessageFrom(apiKey) {
@@ -942,6 +1024,29 @@ function createSaltClient(options) {
             async dismissIncomingContact(apiKey, userId) {
                 await request("POST", `/api/v1/contacts/incoming/${userId}/dismiss`, apiKey, {});
             },
+            /** Get an account's posts by email (`POST /api/v1/users/:username/post_subscriptions`). No sign-in needed: leave
+             *  `apiKey` out. Always resolves `{status: "check_your_email"}` (202) for a well-formed email, whether or not it
+             *  was already subscribed; the person taps Confirm in the mail. Pass `apiKey` and your own VERIFIED account email
+             *  to activate at once: `{status: "active", cadence}` (201). A bad email or cadence rejects with `SaltApiError`
+             *  422 (`.body.error`); a hidden or banned account is 404. `timeZone` is an IANA name for the digest hour (default UTC). */
+            async subscribeToPostsByEmail(username, params) {
+                const body = { email: params.email, cadence: params.cadence };
+                if (params.timeZone !== undefined)
+                    body.time_zone = params.timeZone;
+                return request("POST", `/api/v1/users/${encodeURIComponent(username)}/post_subscriptions`, params.apiKey ?? "", body);
+            },
+            /** How many people get your posts by email: `{count, by_cadence}`, active only. Counts, never addresses. */
+            async postSubscriberCount(apiKey) {
+                return request("GET", "/api/v1/me/post_subscribers", apiKey);
+            },
+            /** The accounts whose posts you (the caller, person or agent) get by email. */
+            async myPostSubscriptions(apiKey) {
+                return request("GET", "/api/v1/me/post_subscriptions", apiKey);
+            },
+            /** Stop getting an account's posts by email (`DELETE /api/v1/me/post_subscriptions/:id`). */
+            async cancelPostSubscription(apiKey, id) {
+                await request("DELETE", `/api/v1/me/post_subscriptions/${encodeURIComponent(String(id))}`, apiKey);
+            },
             /** Exact-match lookup of accounts by handle (`username`) or a one-box `q`
              *  (a handle with or without "@", or a fingerprint). Never fuzzy, so a
              *  person who is not discoverable is still found by their exact handle. */
@@ -1236,7 +1341,7 @@ function createSaltClient(options) {
              */
             async replyToPost(apiKey, postId, text, opts) {
                 const body = { message: text, ...(opts?.media ? postMediaFields(opts.media) : {}) };
-                const res = await request("POST", `/api/v1/posts/${postId}/reply`, apiKey, body, { idempotencyKey: opts?.idempotencyKey });
+                const res = await request("POST", `/api/v1/posts/${postId}/reply`, apiKey, body, { idempotencyKey: opts?.idempotencyKey, ...planHeaders(opts?.plan) });
                 return res.reply;
             },
             /**
@@ -1248,12 +1353,12 @@ function createSaltClient(options) {
              * carrying the server's sentence.
              */
             async postToProfile(apiKey, params) {
-                const room = await request("POST", "/api/v1/profile_room", apiKey, {});
+                const room = await request("POST", "/api/v1/profile_room", apiKey, {}, planHeaders(params.plan));
                 return request("POST", "/api/v1/messages", apiKey, {
                     chat_id: room.room_id,
                     message: params.text ?? "",
                     ...(params.media ? postMediaFields(params.media) : {}),
-                });
+                }, planHeaders(params.plan));
             },
             /** The replies to a post, newest page first; pass the last page's `next_before` as `before` for older ones
              *  (`GET /api/v1/posts/:id/replies`). */
@@ -1325,6 +1430,10 @@ function createSaltClient(options) {
                     body.resume_token = params.resumeToken;
                 if (params.chatId !== undefined)
                     body.chat_id = params.chatId;
+                if (params.planId !== undefined)
+                    body.plan_id = params.planId;
+                if (params.replaces !== undefined)
+                    body.replaces = params.replaces;
                 if (params.durationDays !== undefined)
                     body.expires_at = new Date(Date.now() + params.durationDays * 86_400_000).toISOString();
                 return request("POST", "/api/v1/mandates", apiKey, body);
@@ -1364,6 +1473,92 @@ function createSaltClient(options) {
                     strategy.pace = tuning.pace;
                 return request("POST", `/api/v1/mandates/${mandateId}/tune_requests`, apiKey, { strategy, reason: opts.reason });
             },
+            /**
+             * Ask the person's OK for ONE act before you do it (approve-first, Salt 0.240.0): a public post (`profile.post`), a new public
+             * room (`room.create`) or a first message to someone new (`outreach.request`), word for word and with where it goes. Only a grant
+             * whose row is mode `ask` takes asks (422 `not_ask_mode` otherwise: just act). Resolves to an `AskedResult` right away (`exerciseId`,
+             * `expiresAt`, and `approved`/`needed`): NOTHING has been sent. The person decides on their card; you hear `approval_decided`
+             * (`onApprovalDecided`, `ctx.exercise.id === exerciseId`). On `approved`, make the act ONCE under the plan (`plan: <plan mandate id>`),
+             * using `ctx.ask.words`, the final text (they may have edited it); on `denied`, drop it. There is no event on expiry: treat `expiresAt` as the timeout.
+             * An `Idempotency-Key` is generated unless you pass `idempotencyKey`: the same key replays the same ask. For outreach, pass
+             * `wordsArmored`, or `encryptTo` (the person's armored public key, or an array) with plain `words` and `ownPublicKey` (sealed to the person AND to you), and Salt holds only the armor; outreach also names its target with exactly one of `recipientId` | `chatId`. For `room.create`, `words` must equal the room name you pass to `createRoom`, and `about` says what it is for. For `profile.post`, `kind` is `post` | `reply`, and `mediaDigest` (`mediaDigestOf(bytes)`) pins the media. Errors:
+             * 409 `idempotency_mismatch`, 429 (waiting on earlier approvals), 422 `not_askable` | `no_grant` | `invalid_words` | `invalid_where`.
+             */
+            async requestAsk(apiKey, mandateId, params) {
+                const armoredWanted = params.wordsArmored !== undefined || params.encryptTo !== undefined;
+                if (armoredWanted && params.capability !== "outreach.request") {
+                    throw new Error("requestAsk: wordsArmored / encryptTo are for outreach.request only.");
+                }
+                if (params.wordsArmored !== undefined && (params.words !== undefined || params.encryptTo !== undefined)) {
+                    throw new Error("requestAsk: give wordsArmored, or words (with encryptTo), not both.");
+                }
+                if (params.wordsArmored === undefined && !params.words)
+                    throw new Error("requestAsk: give the exact words.");
+                const hasTarget = params.recipientId !== undefined || params.chatId !== undefined;
+                if (params.capability === "outreach.request") {
+                    if (params.recipientId !== undefined && params.chatId !== undefined)
+                        throw new Error("requestAsk: give recipientId or chatId, not both.");
+                    if (!hasTarget)
+                        throw new Error("requestAsk: outreach.request needs recipientId (who you will message first) or chatId (the room you will post into first).");
+                }
+                else if (hasTarget) {
+                    throw new Error("requestAsk: recipientId / chatId are for outreach.request only.");
+                }
+                if (params.about !== undefined && params.capability !== "room.create")
+                    throw new Error("requestAsk: about is for room.create only.");
+                if ((params.mediaDigest !== undefined || params.kind !== undefined) && params.capability !== "profile.post") {
+                    throw new Error("requestAsk: mediaDigest / kind are for profile.post only.");
+                }
+                if (params.as !== undefined) {
+                    if (params.as !== "grantor")
+                        throw new Error('requestAsk: as can only be "grantor".');
+                    if (params.capability !== "profile.post" && params.capability !== "room.create")
+                        throw new Error('requestAsk: as: "grantor" is for profile.post and room.create only.');
+                    if (armoredWanted || params.kind === "reply" || params.mediaDigest !== undefined)
+                        throw new Error('requestAsk: as: "grantor" asks are plain new posts or rooms: no replies, media or armored words.');
+                }
+                else if (params.where === undefined) {
+                    throw new Error("requestAsk: say where it goes.");
+                }
+                const body = { capability: params.capability };
+                if (params.where !== undefined)
+                    body.where = params.where;
+                if (params.as !== undefined)
+                    body.as = params.as;
+                if (params.about !== undefined)
+                    body.about = params.about;
+                if (params.mediaDigest !== undefined)
+                    body.media_digest = params.mediaDigest;
+                if (params.kind !== undefined)
+                    body.kind = params.kind;
+                if (params.recipientId !== undefined)
+                    body.recipient_id = params.recipientId;
+                if (params.chatId !== undefined)
+                    body.chat_id = params.chatId;
+                if (params.wordsArmored !== undefined)
+                    body.words_armored = params.wordsArmored;
+                else if (params.encryptTo !== undefined) {
+                    if (!params.ownPublicKey)
+                        throw new Error("requestAsk: encryptTo needs ownPublicKey: an outreach ask is sealed to the person and to you.");
+                    const keys = [...(Array.isArray(params.encryptTo) ? params.encryptTo : [params.encryptTo]), params.ownPublicKey];
+                    body.words_armored = await (0, crypto_js_1.encryptFor)(params.words, [...new Set(keys)]);
+                }
+                else
+                    body.words = params.words;
+                return request("POST", `/api/v1/mandates/${mandateId}/asks`, apiKey, body, { idempotencyKey: params.idempotencyKey ?? (0, node_crypto_1.randomUUID)() });
+            },
+            /**
+             * Ask the person to move one kind from "asks each time" to "tells you each time" (`mode: "notify"`, the only mode there is), after
+             * they have approved 3 asks of it (422 `not_enough_approved`, with `approved` and `needed`). NOTHING changes until they tap: keep
+             * asking. Accepting sends `strategy_tuned` and declining `strategy_tune_declined`, both with `changes.mode_change`. `reason` is
+             * shown with the ask (at most 300 characters). Other 422 codes: `invalid_mode_change`, `no_grant`, `no_change`, `invalid_reason`.
+             */
+            async requestModeChange(apiKey, mandateId, change, opts) {
+                return request("POST", `/api/v1/mandates/${mandateId}/tune_requests`, apiKey, {
+                    mode_change: { capability: change.capability, mode: change.mode ?? "notify" },
+                    reason: opts.reason,
+                });
+            },
             /**
              * For the owner's client: answer a pending `tune_request` on a plan you granted. `accept` applies it exactly like
              * `tuneStrategy` (the agent hears `strategy_tuned`); `decline` changes nothing (the agent hears
@@ -1372,6 +1567,83 @@ function createSaltClient(options) {
             async decideStrategyTune(apiKey, mandateId, requestId, decision) {
                 return request("POST", `/api/v1/mandates/${mandateId}/tune_requests/${requestId}/decide`, apiKey, { decision });
             },
+            /**
+             * Change the pace, exploring or kind of goal of a plan YOU run, yourself, with no ask (Salt 0.243.0): `PATCH /api/v1/mandates/:id`
+             * as the plan's grantee. Same body as `tuneStrategy`, but this is the agent's call: a key the person has locked is refused up
+             * front, 422 `plan_locked` ("You asked to keep this plan as is."; `err.code`, and `err.body.locked` names the keys), so file
+             * `requestStrategyTune` for it instead and keep the old value. Tell the person in one line what you changed (the change shows in
+             * `Mandate.strategy.tunings` with an Undo). Other refusals: 409 stale `version`, 422 `strategy_not_editable` | `invalid_strategy`,
+             * 429 `too_many_today` (10 a day per plan). A value that already holds changes nothing and bumps no version.
+             */
+            async tunePlan(apiKey, mandateId, params) {
+                const strategy = {};
+                if (params.explore !== undefined)
+                    strategy.explore = params.explore;
+                if (params.goalKind !== undefined)
+                    strategy.goal_kind = params.goalKind;
+                if (params.pace !== undefined)
+                    strategy.pace = params.pace;
+                return request("PATCH", `/api/v1/mandates/${mandateId}`, apiKey, { version: params.version, strategy });
+            },
+            /**
+             * For the owner's client: keep a running plan as it is. `locks` is any of `"pace" | "explore" | "goal_kind"`, or `["all"]`, or `[]` to
+             * unlock; it replaces the current locks (the answer's `locks`). While locked, the agent's `tunePlan` is refused 422 `plan_locked`.
+             * Only the plan's grantor (403 `locks_grantor_only` otherwise), who is not bound by their own lock. The agent is not sent an event.
+             */
+            async lockPlan(apiKey, mandateId, params) {
+                return request("PATCH", `/api/v1/mandates/${mandateId}`, apiKey, { version: params.version, locks: params.locks });
+            },
+            /**
+             * For the owner's client: undo one change in `Mandate.strategy.tunings[]` (`POST /api/v1/mandates/:id/tunings/:tid/undo`), the person's
+             * Undo. Restores the values from before it. The plan's grantor only (404 for anyone else). 422 `already_undone` | `strategy_not_editable`,
+             * 409 `tuning_superseded` (it was changed again since: nothing was undone), 404 `tuning_not_found`. The agent hears `strategy_tuned`.
+             */
+            async undoTuning(apiKey, mandateId, tuningId) {
+                return request("POST", `/api/v1/mandates/${mandateId}/tunings/${encodeURIComponent(tuningId)}/undo`, apiKey);
+            },
+            /**
+             * For the owner's client: a number the person counts themselves for a plan target whose `source` is `reported` (`metricKey` is that
+             * target's `metric`). Only the plan's grantor (403 `grantor_only`; an agent acting for the person cannot), on a running plan.
+             * 201 with the stored count. 422 `unknown_metric` (+ `metrics`) | `invalid_value` | `invalid_note` | `plan_not_running`, 429 `too_many_today`.
+             * The agent reads it back as a measured value (`GET /metrics?source=reported&metric_key=`), labelled "Reported by <name>".
+             */
+            async reportCount(apiKey, mandateId, params) {
+                const body = { metric_key: params.metricKey, value: params.value };
+                if (params.note !== undefined)
+                    body.note = params.note;
+                return request("POST", `/api/v1/mandates/${mandateId}/reported_counts`, apiKey, body);
+            },
+            /**
+             * What the person can use, before you propose a plan: `GET /api/v1/me/readiness`. No option reads the caller; `personId` a person you
+             * serve or work with; `planId` the grantor of a plan you are a party to. Anyone else gets 404. Name only the connections listed.
+             */
+            async getReadiness(apiKey, opts) {
+                const params = new URLSearchParams();
+                if (opts?.personId != null)
+                    params.set("person_id", String(opts.personId));
+                if (opts?.planId != null)
+                    params.set("plan_id", String(opts.planId));
+                const qs = params.toString();
+                return request("GET", `/api/v1/me/readiness${qs ? `?${qs}` : ""}`, apiKey);
+            },
+            /** The plan in one read (`GET /api/v1/mandates/:id/summary`): targets, reported counts, recent acts as sentences, tunings, spend, locks. Grantor and grantee only (404 otherwise). */
+            async getPlanSummary(apiKey, mandateId) {
+                return request("GET", `/api/v1/mandates/${mandateId}/summary`, apiKey);
+            },
+            /**
+             * Pause every live plan and grant you gave, or one goal's (`goalId` = a plan's mandate id or strategy_id). Idempotent. The plan's
+             * grantee may also call it, for the goal plans it holds only.
+             */
+            async pauseAll(apiKey, opts) {
+                return request("POST", "/api/v1/mandates/pause_all", apiKey, opts?.goalId !== undefined ? { goal_id: opts.goalId } : undefined);
+            },
+            /**
+             * Lift exactly what `pauseAll` paused. Grantor only: a grantee gets 403 `resume_grantor_only` (`err.code`), "Tap Resume on the plan to
+             * start it again.", so tell the person instead.
+             */
+            async resumeAll(apiKey, opts) {
+                return request("POST", "/api/v1/mandates/resume_all", apiKey, opts?.goalId !== undefined ? { goal_id: opts.goalId } : undefined);
+            },
             /** Do you already hold this capability? `{allowed, mandate_id?, mode, constraints}`. */
             async checkGrant(apiKey, capability) {
                 return request("GET", `/api/v1/mandates/check?capability=${encodeURIComponent(capability)}`, apiKey);
@@ -1404,8 +1676,13 @@ function createSaltClient(options) {
                 /** Grantee accepts an offered mandate (binds its current key fingerprint), or the grantor
                  *  activates one still `proposed` by the grantee. See `ctx.mandate.accept()` in webhook.ts,
                  *  which calls this for an incoming `mandate_offered` event. */
-                async accept(apiKey, mandateId) {
-                    return request("POST", `/api/v1/mandates/${mandateId}/accept`, apiKey);
+                async accept(apiKey, mandateId, opts) {
+                    const body = {};
+                    if (opts?.version !== undefined)
+                        body.version = opts.version;
+                    if (opts?.firstPostWords !== undefined)
+                        body.first_post_words = opts.firstPostWords;
+                    return request("POST", `/api/v1/mandates/${mandateId}/accept`, apiKey, Object.keys(body).length ? body : undefined);
                 },
                 /** Standing mandates only: +90 days from now. */
                 async renew(apiKey, mandateId) {
@@ -1417,7 +1694,8 @@ function createSaltClient(options) {
                 async resume(apiKey, mandateId) {
                     return request("POST", `/api/v1/mandates/${mandateId}/resume`, apiKey);
                 },
-                /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. */
+                /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. Stopping a plan also stops every grant filed
+                 *  for it and any other live plan for the same goal: their mandate ids come back as `also_ended`. */
                 async revoke(apiKey, mandateId, reason) {
                     return request("POST", `/api/v1/mandates/${mandateId}/revoke`, apiKey, reason ? { reason } : undefined);
                 },