salt-agent-sdk 0.30.0 → 0.33.0

package/dist/client.d.ts

@@ -95,6 +95,36 @@ export interface PostMessageResult {
     delivered_as?: DeliveredAs;
     [key: string]: unknown;
 }
+/** How often a subscriber gets an account's posts by email. */
+export type PostSubscriptionCadence = "instant" | "daily" | "weekly";
+/** `subscribeToPostsByEmail` result. 202 `check_your_email` always, for any well-formed email (it never says whether
+ *  the address was already subscribed); 201 `active` with the `cadence` when the caller is signed in and the email is
+ *  their own verified account email. */
+export type PostSubscribeResult = {
+    status: "check_your_email";
+} | {
+    status: "active";
+    cadence: PostSubscriptionCadence;
+};
+/** `GET /api/v1/me/post_subscribers`: active email subscribers to your posts, counts only, never addresses. */
+export interface PostSubscriberCount {
+    count: number;
+    by_cadence: {
+        instant: number;
+        daily: number;
+        weekly: number;
+    };
+}
+/** One row of `GET /api/v1/me/post_subscriptions`: an account whose posts you get by email. */
+export interface MyPostSubscription {
+    id: SaltId;
+    cadence: PostSubscriptionCadence;
+    status: "pending" | "active" | "unsubscribed";
+    account: {
+        username: string;
+        display_name: string;
+    };
+}
 /** One row of `GET /api/v1/contacts/incoming`: an account that added the caller and that the caller has not
  *  added back. `added_at` is when they added you. */
 export interface IncomingContact {
@@ -759,7 +789,8 @@ export interface MandateCapabilityRow {
     /** e.g. `{chat_ids: [...]}`, `{wallet_ids: [...]}`, `{product_ids: [...]}`, or `{}` for "every one". */
     selector: Record<string, unknown>;
     mode: MandateCapabilityMode;
-    /** e.g. `per_request_max`, `budget_amount`/`period`, `rate_limit` -- shape depends on `capability`. */
+    /** e.g. `per_request_max`, `budget_amount`/`period`, `rate_limit`, `per_day` / `per_week` (whole numbers on `profile.post`, `wake.repeat`,
+     *  `room.create`, `outreach.request`; the stricter wins; 0 only for `outreach.request`; over the limit is 429 `rate_limit`) -- shape depends on `capability`. */
     constraints: Record<string, unknown>;
 }
 /** One `{capability, selector, mode, constraints}` row as sent to `propose`/`update` -- same shape as
@@ -814,6 +845,17 @@ export interface Mandate {
     approved_by?: "self" | null;
     /** The pending request to change a running plan's settings, or null. See `requestStrategyTune`. */
     tune_request?: StrategyTuneRequest | null;
+    /** Strategy mandates: the keys the person keeps fixed (`lockPlan`); `tunePlan` on one is refused 422 `plan_locked`. Top level, not inside `strategy`. */
+    locks?: PlanLock[];
+    /** Strategy mandates: who runs the plan. `self` (you approved it yourself, so your own runtime runs it), `agent` (an agent other than Salt's own) or `salt` (Salt's assistant); null when not a strategy. */
+    runner?: PlanRunner | null;
+    /** A plan you approved yourself: one sentence saying so and how to have Salt run it (give Salt the goal). Else null. */
+    note?: string | null;
+    /** Strategy mandates: what the running agent says it is testing, keeping and dropping (`putWorking`). Grantor and grantee only. */
+    working?: PlanWorking | null;
+    working_at?: string | null;
+    /** Strategy mandates: when the plan first checks in (Allow time plus review cadence); null until Allowed. */
+    first_check_in_at?: string | null;
     /** Strategy mandates: money paid under the plan, per currency (this month and in total). Measured, never estimated. */
     spend?: {
         money: {
@@ -862,8 +904,174 @@ export interface MandateExercise {
     expires_at?: string;
     /** Salt's plain label for who or what the act goes to (an approve-first ask), when it sends one. */
     target_label?: string;
+    /** One plain sentence for the act ("Posted on your profile"), derived on read. `summary` stays the structured hash. */
+    summary_text?: string;
+    /** Plain words for where the act lands ("Your profile", "A public room", "Ravi (@ravi)"), never the agent's own text. */
+    where?: string | null;
+    /** `paid` is 0 USD for an act that spends nothing, the amount for a payment, null when unknown; `ai_usd` is null unless known. */
+    cost?: {
+        ai_usd: number | null;
+        paid: {
+            amount: string;
+            currency: string;
+        } | null;
+    };
+    [key: string]: unknown;
+}
+/** Who runs a plan: see `Mandate.runner`. */
+export type PlanRunner = "self" | "agent" | "salt";
+/** One thing a plan is testing (`PlanWorking.testing`). */
+export interface WorkingTesting {
+    id: string;
+    /** At most 280 characters. */
+    text: string;
+    since: string;
+    trials: number;
+    result?: string | number;
+}
+/** One thing a plan keeps. `decision`/`decided_at` are set by the person's `decideWorking`. */
+export interface WorkingKept {
+    id: string;
+    text: string;
+    kept_at: string;
+    lift?: string | number;
+    decision?: WorkingDecision;
+    decided_at?: string;
+}
+/** One thing a plan dropped, with the reason. */
+export interface WorkingDropped {
+    id: string;
+    text: string;
+    why: string;
+}
+/** What the plan's agent publishes with `putWorking`: at most 20 entries a list. */
+export interface PlanWorking {
+    testing: WorkingTesting[];
+    kept: WorkingKept[];
+    dropped: WorkingDropped[];
+}
+/** The person's two taps on an entry of what's working. */
+export type WorkingDecision = "keep" | "never";
+/** Answer of `giveGoal`: the request waits for Salt's assistant to file a plan. */
+export interface GoalRequest {
+    id: SaltId;
+    status: "waiting";
+    /** What to do next, in a sentence. */
+    next?: string;
+}
+/** `getGoalRequest`: `planned` carries the plan's `mandate_id` (read it, or wait for the person's Allow); `declined` is the person's Not now; `expired` is 24 hours with no plan. */
+export interface GoalRequestStatus {
+    id: SaltId;
+    status: "waiting" | "planned" | "declined" | "expired";
+    goal: string;
+    deadline: string | null;
+    mandate_id: SaltId | null;
+    created_at: string;
+}
+/** What a person can use, from `getReadiness`: counts and names only. */
+export interface Readiness {
+    person_id: SaltId;
+    wallets: number;
+    shop: boolean;
+    /** Services connected now and not waiting to be reconnected. */
+    connections: {
+        service: string;
+        name: string;
+    }[];
+    followers: number;
+    contacts: number;
+    email_subscribers: number;
+}
+/** One target in a `PlanSummary`. `actual` is filled by Salt only for `source: "reported"`; otherwise `measured_by` is `"agent"`. */
+export interface PlanSummaryTarget {
+    metric: string;
+    target: number;
+    unit?: string | null;
+    deadline?: string | null;
+    source: string;
+    source_label?: string;
+    actual: number | null;
+    actual_at?: string | null;
+    reported: boolean;
+    note?: string | null;
+    /** Who counts it: `person` (a count they report), `salt` (Salt counts it and fills `actual`, `actual_unit`, `actual_at`) or `agent` (outside Salt: you report your own). */
+    measured_by?: "person" | "salt" | "agent";
+    actual_unit?: string | null;
+    [key: string]: unknown;
+}
+/** The plan in one read (`getPlanSummary`). No message content. */
+export interface PlanSummary {
+    mandate_id: SaltId;
+    status: MandateStatus;
+    goal?: string | null;
+    label?: string | null;
+    first_check_in_at: string | null;
+    expires_at?: string | null;
+    accepted_at?: string | null;
+    version: number;
+    targets: PlanSummaryTarget[];
+    reported_counts: ReportedCount[];
+    exercises: {
+        count: number;
+        today_count: number;
+        last_at: string | null;
+        recent: {
+            id: SaltId | number;
+            at: string;
+            text: string;
+            capability: string;
+            decision: MandateExerciseDecision;
+            where: string | null;
+            cost: MandateExercise["cost"];
+            target?: {
+                type?: string;
+                id?: SaltId;
+            };
+        }[];
+    };
+    tunings: Record<string, unknown>[];
+    spend: Mandate["spend"];
+    ai: {
+        model_budget_usd: number | null;
+        spent_usd: number | null;
+        budget_from?: "plan" | "default";
+        paid_by?: "salt" | "grantor" | "grantee";
+    };
+    locks: PlanLock[];
+    /** Who runs the plan (see `Mandate.runner`), and what the running agent says is working (`putWorking`). */
+    runner?: PlanRunner | null;
+    working?: PlanWorking | null;
+    working_at?: string | null;
     [key: string]: unknown;
 }
+/** Answer of `pauseAll`: `paused` are newly paused, `already_paused` were already. Idempotent. */
+export interface PauseAllResult {
+    status: "paused";
+    paused: SaltId[];
+    already_paused: SaltId[];
+    count: number;
+}
+/** Answer of `resumeAll`: lifts only what `pauseAll` paused. */
+export interface ResumeAllResult {
+    status: "active" | "partly_paused";
+    resumed: SaltId[];
+    still_paused: SaltId[];
+}
+/** `event_type` of the plain-text lines Salt writes into a plan's chat. Chat events, not webhook events: never claim these in your own words. */
+export type PlanEventType = "plan_filed" | "plan_allowed" | "plan_acted" | "plan_paused" | "plan_resumed" | "plan_stopped" | "plan_tuned";
+/** The first post a plan carries, `strategy.first_post` (read it back after Allow for `posted`). */
+export interface PlanFirstPost {
+    words: string;
+    where?: "profile";
+    /** Your words, only when the person edited them before Allow. */
+    asked_words?: string;
+    posted?: {
+        exercise_id: SaltId | number;
+        message_id: SaltId;
+        chat_id: SaltId;
+        at: string;
+    };
+}
 export interface ProposeMandateParams {
     grantee_id?: SaltId;
     grantee_username?: string;
@@ -959,6 +1167,11 @@ export interface StrategyTuning {
 }
 /** What a tune (or a request for one) changes: the three effort keys, or one capability's mode (`requestModeChange`). */
 export interface StrategyTuneChanges {
+    /** The steps dropped from the plan: `[{index, text}]` (0-based positions in the plan before the drop). */
+    drop_steps?: {
+        index: number;
+        text: string;
+    }[];
     explore?: number;
     goal_kind?: string;
     pace?: string;
@@ -967,6 +1180,30 @@ export interface StrategyTuneChanges {
         mode: "notify";
     };
 }
+/** `getStrategyLimits`: the lists the API checks a plan against. Only the keys named here are typed; the rest is open. */
+export interface StrategyLimits {
+    live_tunable: string[];
+    /** Keys a running plan can only narrow: `["drop_steps"]`. */
+    live_narrowable?: string[];
+    lock_values: string[];
+    [key: string]: unknown;
+}
+/** What the person can keep fixed on a running plan (`lockPlan`): any of the three keys, or everything. */
+export type PlanLock = "pace" | "explore" | "goal_kind" | "drop_steps" | "all";
+/** A count the person reported for a `reported` plan target (`reportCount`). */
+export interface ReportedCount {
+    id: string;
+    mandate_id: SaltId;
+    metric_key: string;
+    value: number | string;
+    note?: string | null;
+    reported_at: string;
+    reported_by: {
+        id: SaltId;
+        username?: string;
+        display_name?: string;
+    };
+}
 /** A pending request to change a running plan's settings (`Mandate.tune_request`); nothing has changed until the grantor accepts. */
 export interface StrategyTuneRequest {
     id: string;
@@ -986,6 +1223,8 @@ export interface AskedResult {
      *  file `requestModeChange`. */
     approved?: number;
     needed?: number;
+    /** `"grantor"` on the answer to an `as: "grantor"` ask: the post or room will be the PERSON's own, not yours. */
+    as?: "grantor";
 }
 export declare function isAsked(value: unknown): value is AskedResult;
 /** Maps a client method's `Promise<R>` to `Promise<R | AskedResult>` -- what every call through
@@ -1122,6 +1361,17 @@ export declare class RecipientContactsOnlyError extends SaltApiError {
     sentence: string;
     constructor(method: string, url: string, status: number, body: unknown);
 }
+/** Refusals of a plan call that carry a sentence for the person and a `next` step: read the code, show the sentence. */
+export declare const GOAL_PLAN_ERROR_CODES: readonly ["no_capability", "first_post_needs_post", "source_unavailable"];
+export type GoalPlanErrorCode = (typeof GOAL_PLAN_ERROR_CODES)[number];
+/** 422 `no_capability` (an ask on a plan you approved yourself holds no permissions), 422 `first_post_needs_post` (a `first_post` with no
+ *  `profile.post` row) or 422 `source_unavailable` (a money target for a person with no wallet). `sentence` is the server's own words and
+ *  `next` its next step when it gives one (e.g. "To have Salt run it, give Salt the goal: POST /api/v1/goals."). Do not retry unchanged. */
+export declare class GoalPlanError extends SaltApiError {
+    sentence: string;
+    next?: string;
+    constructor(method: string, url: string, status: number, body: unknown);
+}
 export declare const APPROVE_FIRST = "approve_first";
 export declare const PLAN_REQUIRED = "plan_required";
 /** The three kinds of act that wait for the person's tap before the first few go out: a public post, a public room, a first message to someone new. */
@@ -1163,8 +1413,13 @@ export interface RequestAskParams {
     mediaDigest?: string;
     /** `profile.post` only: a new post, or a reply to someone's post. */
     kind?: "post" | "reply";
-    /** Where it goes: the room, post or person (at most 200 characters). */
-    where: string;
+    /** Where it goes: the room, post or person (at most 200 characters). Leave it out with `as: "grantor"`: the destination is fixed
+     *  (their profile, or a new public room) and anything you send is ignored. */
+    where?: string;
+    /** `"grantor"`: ask the person to post this AS THEMSELVES (`profile.post`, a new post) or open a public room (`room.create`) in their
+     *  name. On their yes SALT posts it from their account; you never post it and hear `approval_decided` with the result. Not for
+     *  replies, media or outreach (422 `as_post_only`). 422 `invalid_as` | `as_not_allowed`. */
+    as?: "grantor";
     /** `outreach.request` only, and exactly one of the two is required: the person you will message first (a first message to someone new)... */
     recipientId?: SaltId;
     /** ...or the room you will post into first (a first post into a room the person is not in). The act must name the same target. */
@@ -1185,7 +1440,7 @@ type RequestFn = <T>(method: string, path: string, apiKey: string, body?: unknow
     idempotencyKey?: string;
 }) => Promise<T>;
 /** Sent as `X-Salt-Client` on every request. Kept equal to package.json's version (a test checks). */
-export declare const SDK_VERSION = "0.30.0";
+export declare const SDK_VERSION = "0.33.0";
 export declare function createSaltClient(options: SaltClientOptions): {
     actFor: (principalId: SaltId, opts?: ActForOptions) => { [K in keyof ReturnType<(request: RequestFn) => {
         /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
@@ -1663,6 +1918,23 @@ export declare function createSaltClient(options: SaltClientOptions): {
         acceptContact(apiKey: string, userId: SaltId): Promise<unknown>;
         /** Dismiss an incoming contact without adding them back; they drop out of the incoming list and are not told. */
         dismissIncomingContact(apiKey: string, userId: SaltId): Promise<void>;
+        /** 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). */
+        subscribeToPostsByEmail(username: string, params: {
+            email: string;
+            cadence: PostSubscriptionCadence;
+            timeZone?: string;
+            apiKey?: string;
+        }): Promise<PostSubscribeResult>;
+        /** How many people get your posts by email: `{count, by_cadence}`, active only. Counts, never addresses. */
+        postSubscriberCount(apiKey: string): Promise<PostSubscriberCount>;
+        /** The accounts whose posts you (the caller, person or agent) get by email. */
+        myPostSubscriptions(apiKey: string): Promise<MyPostSubscription[]>;
+        /** Stop getting an account's posts by email (`DELETE /api/v1/me/post_subscriptions/:id`). */
+        cancelPostSubscription(apiKey: string, id: SaltId): Promise<void>;
         /** 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. */
@@ -1995,6 +2267,116 @@ export declare function createSaltClient(options: SaltClientOptions): {
          * `strategy_tune_declined`). 404 `request_not_open` when it was replaced or already answered.
          */
         decideStrategyTune(apiKey: string, mandateId: SaltId, requestId: string, decision: "accept" | "decline"): Promise<Mandate>;
+        /**
+         * 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.
+         */
+        tunePlan(apiKey: string, mandateId: SaltId, params: {
+            version: number;
+        } & StrategyTuning): Promise<Mandate>;
+        /**
+         * 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.
+         */
+        lockPlan(apiKey: string, mandateId: SaltId, params: {
+            version: number;
+            locks: PlanLock[];
+        }): Promise<Mandate>;
+        /**
+         * 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`.
+         */
+        undoTuning(apiKey: string, mandateId: SaltId, tuningId: string): Promise<Mandate>;
+        /**
+         * 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>".
+         */
+        reportCount(apiKey: string, mandateId: SaltId, params: {
+            metricKey: string;
+            value: number;
+            note?: string;
+        }): Promise<ReportedCount>;
+        /**
+         * 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.
+         */
+        getReadiness(apiKey: string, opts?: {
+            personId?: SaltId;
+            planId?: SaltId;
+        }): Promise<Readiness>;
+        /** 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). */
+        getPlanSummary(apiKey: string, mandateId: SaltId): Promise<PlanSummary>;
+        /**
+         * 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.
+         */
+        pauseAll(apiKey: string, opts?: {
+            goalId?: SaltId | string;
+        }): Promise<PauseAllResult>;
+        /**
+         * 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.
+         */
+        resumeAll(apiKey: string, opts?: {
+            goalId?: SaltId | string;
+        }): Promise<ResumeAllResult>;
+        /**
+         * Take steps out of a RUNNING plan (`PATCH /api/v1/mandates/:id {version, strategy: {drop_steps}}`, 0.245.0): `steps` are 0-based
+         * positions in the plan, each once. The plan only narrows: it keeps at least one step (422 `invalid_strategy`), and adding steps is 422
+         * `strategy_not_editable`. Allowed to the plan's agent, the person, and an account on its own plan. A locked `drop_steps` is 422
+         * `plan_locked`. Salt writes the "dropped a step" line and the person can Undo it (`undoTuning`); you hear `strategy_tuned` with
+         * `changes.drop_steps`. Tell the person in one line which step and why.
+         */
+        dropPlanSteps(apiKey: string, mandateId: SaltId, params: {
+            version: number;
+            steps: number[];
+        }): Promise<Mandate>;
+        /**
+         * The closed lists and ranges the API accepts for plans (`GET /api/v1/strategies/limits`, public): `live_tunable` (explore, goal_kind, pace),
+         * `live_narrowable` (`["drop_steps"]`: keys that can only take something away from a running plan), `lock_values`, and more.
+         */
+        getStrategyLimits(): Promise<StrategyLimits>;
+        /**
+         * Give Salt a goal when you have no runtime of your own (`POST /api/v1/goals`): the same as typing it to @salt. 201 `{id, status: "waiting", next}`;
+         * Salt's assistant files a plan to you (read `GET /api/v1/mandates?role=grantor&status=proposed`, or watch `getGoalRequest`), then Allow it
+         * with `mandates.accept`. `goal` is plain text, 1 to 2000 characters; `deadline` is `YYYY-MM-DD`; `chatId` is a chat you are in and becomes the
+         * plan's chat. 5 waiting and 20 a day (429 `too_many_waiting` / `goals_per_day`, `err.retryAfterSeconds`). Pass `idempotencyKey` and a retry files one request.
+         */
+        giveGoal(apiKey: string, params: {
+            goal: string;
+            deadline?: string;
+            chatId?: SaltId;
+            idempotencyKey?: string;
+        }): Promise<GoalRequest>;
+        /** Where a goal you gave stands (`GET /api/v1/goals/:id`). Only the person who gave it can read it (404 otherwise). */
+        getGoalRequest(apiKey: string, goalRequestId: SaltId): Promise<GoalRequestStatus>;
+        /**
+         * The agent running a plan publishes what it is testing, keeping and dropping (`PUT /api/v1/mandates/:id/working`). Replaces the lists;
+         * entries' `decision` stays when you publish again. Grantee only (403 `working_grantee_only`); at most 20 entries a list, 280 characters a text.
+         */
+        putWorking(apiKey: string, mandateId: SaltId, working: Partial<PlanWorking>): Promise<{
+            mandate_id: SaltId;
+            working: PlanWorking;
+            working_at: string;
+        }>;
+        /**
+         * The plan's person decides on one entry (`POST /api/v1/mandates/:id/working/decide`): `keep` or `never`. Grantor only (403
+         * `working_grantor_only`); 422 `entry_not_found`. The agent hears `plan.working_decided` (`{mandate_id, id, decision}`).
+         */
+        decideWorking(apiKey: string, mandateId: SaltId, entryId: string, decision: WorkingDecision): Promise<{
+            mandate_id: SaltId;
+            id: string;
+            decision: WorkingDecision;
+            working: PlanWorking;
+        }>;
         /** Do you already hold this capability? `{allowed, mandate_id?, mode, constraints}`. */
         checkGrant(apiKey: string, capability: GrantCapability): Promise<GrantCheck>;
         mandates: {
@@ -2015,7 +2397,16 @@ export declare function createSaltClient(options: SaltClientOptions): {
             /** 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. */
-            accept(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            accept(apiKey: string, mandateId: SaltId, opts?: {
+                version?: number;
+                firstPostWords?: string;
+            }): Promise<Mandate & {
+                first_post_result?: {
+                    exercise_id: SaltId | number;
+                    message_id: SaltId;
+                    chat_id: SaltId;
+                };
+            }>;
             /** Standing mandates only: +90 days from now. */
             renew(apiKey: string, mandateId: SaltId): Promise<Mandate>;
             pause(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;
@@ -2608,6 +2999,23 @@ export declare function createSaltClient(options: SaltClientOptions): {
         acceptContact(apiKey: string, userId: SaltId): Promise<unknown>;
         /** Dismiss an incoming contact without adding them back; they drop out of the incoming list and are not told. */
         dismissIncomingContact(apiKey: string, userId: SaltId): Promise<void>;
+        /** 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). */
+        subscribeToPostsByEmail(username: string, params: {
+            email: string;
+            cadence: PostSubscriptionCadence;
+            timeZone?: string;
+            apiKey?: string;
+        }): Promise<PostSubscribeResult>;
+        /** How many people get your posts by email: `{count, by_cadence}`, active only. Counts, never addresses. */
+        postSubscriberCount(apiKey: string): Promise<PostSubscriberCount>;
+        /** The accounts whose posts you (the caller, person or agent) get by email. */
+        myPostSubscriptions(apiKey: string): Promise<MyPostSubscription[]>;
+        /** Stop getting an account's posts by email (`DELETE /api/v1/me/post_subscriptions/:id`). */
+        cancelPostSubscription(apiKey: string, id: SaltId): Promise<void>;
         /** 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. */
@@ -2940,6 +3348,116 @@ export declare function createSaltClient(options: SaltClientOptions): {
          * `strategy_tune_declined`). 404 `request_not_open` when it was replaced or already answered.
          */
         decideStrategyTune(apiKey: string, mandateId: SaltId, requestId: string, decision: "accept" | "decline"): Promise<Mandate>;
+        /**
+         * 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.
+         */
+        tunePlan(apiKey: string, mandateId: SaltId, params: {
+            version: number;
+        } & StrategyTuning): Promise<Mandate>;
+        /**
+         * 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.
+         */
+        lockPlan(apiKey: string, mandateId: SaltId, params: {
+            version: number;
+            locks: PlanLock[];
+        }): Promise<Mandate>;
+        /**
+         * 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`.
+         */
+        undoTuning(apiKey: string, mandateId: SaltId, tuningId: string): Promise<Mandate>;
+        /**
+         * 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>".
+         */
+        reportCount(apiKey: string, mandateId: SaltId, params: {
+            metricKey: string;
+            value: number;
+            note?: string;
+        }): Promise<ReportedCount>;
+        /**
+         * 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.
+         */
+        getReadiness(apiKey: string, opts?: {
+            personId?: SaltId;
+            planId?: SaltId;
+        }): Promise<Readiness>;
+        /** 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). */
+        getPlanSummary(apiKey: string, mandateId: SaltId): Promise<PlanSummary>;
+        /**
+         * 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.
+         */
+        pauseAll(apiKey: string, opts?: {
+            goalId?: SaltId | string;
+        }): Promise<PauseAllResult>;
+        /**
+         * 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.
+         */
+        resumeAll(apiKey: string, opts?: {
+            goalId?: SaltId | string;
+        }): Promise<ResumeAllResult>;
+        /**
+         * Take steps out of a RUNNING plan (`PATCH /api/v1/mandates/:id {version, strategy: {drop_steps}}`, 0.245.0): `steps` are 0-based
+         * positions in the plan, each once. The plan only narrows: it keeps at least one step (422 `invalid_strategy`), and adding steps is 422
+         * `strategy_not_editable`. Allowed to the plan's agent, the person, and an account on its own plan. A locked `drop_steps` is 422
+         * `plan_locked`. Salt writes the "dropped a step" line and the person can Undo it (`undoTuning`); you hear `strategy_tuned` with
+         * `changes.drop_steps`. Tell the person in one line which step and why.
+         */
+        dropPlanSteps(apiKey: string, mandateId: SaltId, params: {
+            version: number;
+            steps: number[];
+        }): Promise<Mandate>;
+        /**
+         * The closed lists and ranges the API accepts for plans (`GET /api/v1/strategies/limits`, public): `live_tunable` (explore, goal_kind, pace),
+         * `live_narrowable` (`["drop_steps"]`: keys that can only take something away from a running plan), `lock_values`, and more.
+         */
+        getStrategyLimits(): Promise<StrategyLimits>;
+        /**
+         * Give Salt a goal when you have no runtime of your own (`POST /api/v1/goals`): the same as typing it to @salt. 201 `{id, status: "waiting", next}`;
+         * Salt's assistant files a plan to you (read `GET /api/v1/mandates?role=grantor&status=proposed`, or watch `getGoalRequest`), then Allow it
+         * with `mandates.accept`. `goal` is plain text, 1 to 2000 characters; `deadline` is `YYYY-MM-DD`; `chatId` is a chat you are in and becomes the
+         * plan's chat. 5 waiting and 20 a day (429 `too_many_waiting` / `goals_per_day`, `err.retryAfterSeconds`). Pass `idempotencyKey` and a retry files one request.
+         */
+        giveGoal(apiKey: string, params: {
+            goal: string;
+            deadline?: string;
+            chatId?: SaltId;
+            idempotencyKey?: string;
+        }): Promise<GoalRequest>;
+        /** Where a goal you gave stands (`GET /api/v1/goals/:id`). Only the person who gave it can read it (404 otherwise). */
+        getGoalRequest(apiKey: string, goalRequestId: SaltId): Promise<GoalRequestStatus>;
+        /**
+         * The agent running a plan publishes what it is testing, keeping and dropping (`PUT /api/v1/mandates/:id/working`). Replaces the lists;
+         * entries' `decision` stays when you publish again. Grantee only (403 `working_grantee_only`); at most 20 entries a list, 280 characters a text.
+         */
+        putWorking(apiKey: string, mandateId: SaltId, working: Partial<PlanWorking>): Promise<{
+            mandate_id: SaltId;
+            working: PlanWorking;
+            working_at: string;
+        }>;
+        /**
+         * The plan's person decides on one entry (`POST /api/v1/mandates/:id/working/decide`): `keep` or `never`. Grantor only (403
+         * `working_grantor_only`); 422 `entry_not_found`. The agent hears `plan.working_decided` (`{mandate_id, id, decision}`).
+         */
+        decideWorking(apiKey: string, mandateId: SaltId, entryId: string, decision: WorkingDecision): Promise<{
+            mandate_id: SaltId;
+            id: string;
+            decision: WorkingDecision;
+            working: PlanWorking;
+        }>;
         /** Do you already hold this capability? `{allowed, mandate_id?, mode, constraints}`. */
         checkGrant(apiKey: string, capability: GrantCapability): Promise<GrantCheck>;
         mandates: {
@@ -2960,7 +3478,16 @@ export declare function createSaltClient(options: SaltClientOptions): {
             /** 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. */
-            accept(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            accept(apiKey: string, mandateId: SaltId, opts?: {
+                version?: number;
+                firstPostWords?: string;
+            }): Promise<Mandate & {
+                first_post_result?: {
+                    exercise_id: SaltId | number;
+                    message_id: SaltId;
+                    chat_id: SaltId;
+                };
+            }>;
             /** Standing mandates only: +90 days from now. */
             renew(apiKey: string, mandateId: SaltId): Promise<Mandate>;
             pause(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;
@@ -3553,6 +4080,23 @@ export declare function createSaltClient(options: SaltClientOptions): {
     acceptContact(apiKey: string, userId: SaltId): Promise<unknown>;
     /** Dismiss an incoming contact without adding them back; they drop out of the incoming list and are not told. */
     dismissIncomingContact(apiKey: string, userId: SaltId): Promise<void>;
+    /** 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). */
+    subscribeToPostsByEmail(username: string, params: {
+        email: string;
+        cadence: PostSubscriptionCadence;
+        timeZone?: string;
+        apiKey?: string;
+    }): Promise<PostSubscribeResult>;
+    /** How many people get your posts by email: `{count, by_cadence}`, active only. Counts, never addresses. */
+    postSubscriberCount(apiKey: string): Promise<PostSubscriberCount>;
+    /** The accounts whose posts you (the caller, person or agent) get by email. */
+    myPostSubscriptions(apiKey: string): Promise<MyPostSubscription[]>;
+    /** Stop getting an account's posts by email (`DELETE /api/v1/me/post_subscriptions/:id`). */
+    cancelPostSubscription(apiKey: string, id: SaltId): Promise<void>;
     /** 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. */
@@ -3885,6 +4429,116 @@ export declare function createSaltClient(options: SaltClientOptions): {
      * `strategy_tune_declined`). 404 `request_not_open` when it was replaced or already answered.
      */
     decideStrategyTune(apiKey: string, mandateId: SaltId, requestId: string, decision: "accept" | "decline"): Promise<Mandate>;
+    /**
+     * 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.
+     */
+    tunePlan(apiKey: string, mandateId: SaltId, params: {
+        version: number;
+    } & StrategyTuning): Promise<Mandate>;
+    /**
+     * 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.
+     */
+    lockPlan(apiKey: string, mandateId: SaltId, params: {
+        version: number;
+        locks: PlanLock[];
+    }): Promise<Mandate>;
+    /**
+     * 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`.
+     */
+    undoTuning(apiKey: string, mandateId: SaltId, tuningId: string): Promise<Mandate>;
+    /**
+     * 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>".
+     */
+    reportCount(apiKey: string, mandateId: SaltId, params: {
+        metricKey: string;
+        value: number;
+        note?: string;
+    }): Promise<ReportedCount>;
+    /**
+     * 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.
+     */
+    getReadiness(apiKey: string, opts?: {
+        personId?: SaltId;
+        planId?: SaltId;
+    }): Promise<Readiness>;
+    /** 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). */
+    getPlanSummary(apiKey: string, mandateId: SaltId): Promise<PlanSummary>;
+    /**
+     * 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.
+     */
+    pauseAll(apiKey: string, opts?: {
+        goalId?: SaltId | string;
+    }): Promise<PauseAllResult>;
+    /**
+     * 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.
+     */
+    resumeAll(apiKey: string, opts?: {
+        goalId?: SaltId | string;
+    }): Promise<ResumeAllResult>;
+    /**
+     * Take steps out of a RUNNING plan (`PATCH /api/v1/mandates/:id {version, strategy: {drop_steps}}`, 0.245.0): `steps` are 0-based
+     * positions in the plan, each once. The plan only narrows: it keeps at least one step (422 `invalid_strategy`), and adding steps is 422
+     * `strategy_not_editable`. Allowed to the plan's agent, the person, and an account on its own plan. A locked `drop_steps` is 422
+     * `plan_locked`. Salt writes the "dropped a step" line and the person can Undo it (`undoTuning`); you hear `strategy_tuned` with
+     * `changes.drop_steps`. Tell the person in one line which step and why.
+     */
+    dropPlanSteps(apiKey: string, mandateId: SaltId, params: {
+        version: number;
+        steps: number[];
+    }): Promise<Mandate>;
+    /**
+     * The closed lists and ranges the API accepts for plans (`GET /api/v1/strategies/limits`, public): `live_tunable` (explore, goal_kind, pace),
+     * `live_narrowable` (`["drop_steps"]`: keys that can only take something away from a running plan), `lock_values`, and more.
+     */
+    getStrategyLimits(): Promise<StrategyLimits>;
+    /**
+     * Give Salt a goal when you have no runtime of your own (`POST /api/v1/goals`): the same as typing it to @salt. 201 `{id, status: "waiting", next}`;
+     * Salt's assistant files a plan to you (read `GET /api/v1/mandates?role=grantor&status=proposed`, or watch `getGoalRequest`), then Allow it
+     * with `mandates.accept`. `goal` is plain text, 1 to 2000 characters; `deadline` is `YYYY-MM-DD`; `chatId` is a chat you are in and becomes the
+     * plan's chat. 5 waiting and 20 a day (429 `too_many_waiting` / `goals_per_day`, `err.retryAfterSeconds`). Pass `idempotencyKey` and a retry files one request.
+     */
+    giveGoal(apiKey: string, params: {
+        goal: string;
+        deadline?: string;
+        chatId?: SaltId;
+        idempotencyKey?: string;
+    }): Promise<GoalRequest>;
+    /** Where a goal you gave stands (`GET /api/v1/goals/:id`). Only the person who gave it can read it (404 otherwise). */
+    getGoalRequest(apiKey: string, goalRequestId: SaltId): Promise<GoalRequestStatus>;
+    /**
+     * The agent running a plan publishes what it is testing, keeping and dropping (`PUT /api/v1/mandates/:id/working`). Replaces the lists;
+     * entries' `decision` stays when you publish again. Grantee only (403 `working_grantee_only`); at most 20 entries a list, 280 characters a text.
+     */
+    putWorking(apiKey: string, mandateId: SaltId, working: Partial<PlanWorking>): Promise<{
+        mandate_id: SaltId;
+        working: PlanWorking;
+        working_at: string;
+    }>;
+    /**
+     * The plan's person decides on one entry (`POST /api/v1/mandates/:id/working/decide`): `keep` or `never`. Grantor only (403
+     * `working_grantor_only`); 422 `entry_not_found`. The agent hears `plan.working_decided` (`{mandate_id, id, decision}`).
+     */
+    decideWorking(apiKey: string, mandateId: SaltId, entryId: string, decision: WorkingDecision): Promise<{
+        mandate_id: SaltId;
+        id: string;
+        decision: WorkingDecision;
+        working: PlanWorking;
+    }>;
     /** Do you already hold this capability? `{allowed, mandate_id?, mode, constraints}`. */
     checkGrant(apiKey: string, capability: GrantCapability): Promise<GrantCheck>;
     mandates: {
@@ -3905,7 +4559,16 @@ export declare function createSaltClient(options: SaltClientOptions): {
         /** 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. */
-        accept(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+        accept(apiKey: string, mandateId: SaltId, opts?: {
+            version?: number;
+            firstPostWords?: string;
+        }): Promise<Mandate & {
+            first_post_result?: {
+                exercise_id: SaltId | number;
+                message_id: SaltId;
+                chat_id: SaltId;
+            };
+        }>;
         /** Standing mandates only: +90 days from now. */
         renew(apiKey: string, mandateId: SaltId): Promise<Mandate>;
         pause(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;