@extrovert.dev/mcp 0.1.0-pre.3

package/dist/client.d.ts

@@ -0,0 +1,956 @@
+/**
+ * Thin, typed Extrovert API client.
+ *
+ * One method per REST endpoint in spec §8 (`/v1`). The base URL and scoped
+ * agent key come from config (env `EXTROVERT_API_BASE_URL` / `EXTROVERT_API_KEY`).
+ * This module is the single seam between the MCP tools and the network — the
+ * tools never touch `fetch` directly.
+ *
+ * While `config.mock` is true, each method returns deterministic fixture data
+ * via `FixtureStore` instead of issuing HTTP.
+ */
+import type { ExtrovertConfig } from "./config.js";
+import { NotFoundError } from "./fixtures.js";
+import type { Attachment, AttachmentDownload, AttachmentInput, BatchUpdateResult, Category, ContactListDirection, ContactListEntry, ContactListKind, DeleteResult, Domain, DomainOffboard, EnrollmentResult, GraduationStatus, Inbox, Job, KeyTier, MailboxCredentials, Message, Page, Review, RiskDial, ReviewDecisionContext, ReviewerAction, ReviewerDecisionResult, ReviewEventsResult, ReviewFeedback, ReviewIntent, ReviewMode, ReviewState, CategoryPacingState, ReviewTurn, Rule, RuleAuditEntry, ProblemField, ReplyEmailResult, ScanBacklogStatus, SendEmailResult, SignUpResult, SubmitForReviewResult, SuppressionEntry, SuppressionPrecheck, ReputationRollup, ReputationFinding, ListDeliverabilityFindingsInput, Thread, ThreadDetail, VerifyResult, WaitForEmailResult, Webhook, WebhookEvent, WhoAmI } from "./types.js";
+/** Normalized error surfaced from any client call. */
+export declare class ExtrovertApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    /**
+     * The problem's machine-readable field hints (`problem.errors[]`), verbatim.
+     *
+     * These are NOT decoration. A 422 `intent_required` carries the exact JSON to
+     * add under `retry_with`, and a 409 carries `state` / `revision` / `version` /
+     * one `allowed_action` per legal verb — the facts that let an agent recover in
+     * one turn instead of guessing. They reach the model only because
+     * `toErrorResult` renders them: anything left in `structuredContent` is
+     * invisible to a text-only agent.
+     */
+    readonly problemErrors?: ProblemField[] | undefined;
+    constructor(message: string, status: number, code?: string | undefined, details?: unknown | undefined, 
+    /**
+     * The problem's machine-readable field hints (`problem.errors[]`), verbatim.
+     *
+     * These are NOT decoration. A 422 `intent_required` carries the exact JSON to
+     * add under `retry_with`, and a 409 carries `state` / `revision` / `version` /
+     * one `allowed_action` per legal verb — the facts that let an agent recover in
+     * one turn instead of guessing. They reach the model only because
+     * `toErrorResult` renders them: anything left in `structuredContent` is
+     * invisible to a text-only agent.
+     */
+    problemErrors?: ProblemField[] | undefined);
+}
+export interface RedeemEnrollmentInput {
+    enrollment_token: string;
+    /** Idempotency handle (à la AgentMail `client_id`); rebinds the same agent. */
+    agent_handle?: string;
+    /**
+     * Optional client-supplied idempotency key sent as the `Idempotency-Key`
+     * header: a retry with the same key replays the original enrollment response.
+     */
+    client_id?: string;
+}
+/**
+ * A metadata patch on create/update. Each value is string | number | boolean to
+ * SET a key, or `null` to DELETE that key (merge-null-clear semantics). A
+ * top-level `null` on update clears ALL metadata (see {@link UpdateInboxInput}).
+ */
+export type InboxMetadataPatch = Record<string, string | number | boolean | null>;
+export interface CreateInboxInput {
+    username?: string;
+    domain?: string;
+    display_name?: string;
+    inbound_webhook_url?: string;
+    /**
+     * Optional arbitrary key-value metadata to store on the inbox (AgentMail
+     * parity). Values may be string, number, or boolean; a key with a `null` value
+     * is dropped. Caps: ≤256 keys, ≤256 chars per key, ≤256 chars per string value;
+     * nested objects/arrays are rejected. Echoed back (and replayed on idempotent
+     * retries) on the create response.
+     */
+    metadata?: InboxMetadataPatch;
+    /**
+     * Optional assertion that must match the key's bound project — NEVER a
+     * selector. A mismatch is rejected server-side; the inbox is always created in
+     * the key's stored project.
+     */
+    project_id?: string;
+    /**
+     * Optional client-supplied idempotency key sent as the `Idempotency-Key`
+     * header: re-creating with the same key returns the existing inbox rather than
+     * a duplicate (the same key with a different request is a 409).
+     */
+    client_id?: string;
+}
+export interface RegisterWebhookInput {
+    url: string;
+    events?: WebhookEvent[];
+    inbox?: string;
+    /**
+     * Optional client-supplied idempotency key sent as the `Idempotency-Key`
+     * header: a retry with the same key replays the original registration.
+     */
+    client_id?: string;
+}
+/** Mutable inbox settings for `PATCH /v1/inboxes/{inbox_id}`. Omitted fields are left unchanged. */
+export interface UpdateInboxInput {
+    /** New sender display / "From" name. Empty string falls back to the local-part. */
+    display_name?: string;
+    /** Replace the inbound webhook target (empty string clears it). */
+    inbound_webhook_url?: string;
+    /**
+     * Set the effective rolling-24-hour recipient cap (integer 1–10,000).
+     * Requires the opt-in `mailbox:quota` scope.
+     */
+    daily_send_limit?: number;
+    /**
+     * Patch the inbox's arbitrary metadata (AgentMail parity) with a shallow merge:
+     * an object merges into the existing metadata; a key whose value is `null`
+     * deletes that key; a top-level `null` clears ALL metadata (the response then
+     * carries `{}`). Omit the field entirely to leave metadata unchanged. Values
+     * may be string, number, or boolean; nested objects/arrays are rejected; the
+     * same ≤256 key/length caps as create apply.
+     */
+    metadata?: InboxMetadataPatch | null;
+    /**
+     * Optional assertion that must match the key's bound project — NEVER a
+     * selector. A mismatch is rejected server-side.
+     */
+    project_id?: string;
+}
+export interface SendEmailInput {
+    inbox: string;
+    to: string[];
+    subject: string;
+    text: string;
+    html?: string;
+    cc?: string[];
+    bcc?: string[];
+    /** Override the Reply-To header. */
+    reply_to?: string;
+    /** Custom headers to attach (reserved/unsafe names are dropped server-side). */
+    headers?: Record<string, string>;
+    /** Files to attach (base64). */
+    attachments?: AttachmentInput[];
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    client_id?: string;
+}
+export interface ReplyEmailInput {
+    inbox: string;
+    /** Exactly one of thread_id / message_id selects the parent. */
+    thread_id?: string;
+    message_id?: string;
+    text?: string;
+    html?: string;
+    cc?: string[];
+    bcc?: string[];
+    reply_to?: string;
+    headers?: Record<string, string>;
+    /** Reply to every thread recipient, not just the original sender. */
+    reply_all?: boolean;
+    /** Files to attach (base64). */
+    attachments?: AttachmentInput[];
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    client_id?: string;
+}
+export interface ForwardEmailInput {
+    inbox: string;
+    message_id: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    text?: string;
+    /** Accepted for wire compatibility but ignored; the materialized forward is plain text. */
+    html?: string;
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    client_id?: string;
+}
+/**
+ * Submit a forward for human review (Review Loop). A forward is an outbound
+ * message to arbitrary NEW recipients that quotes an entire received thread, so it
+ * is policy-enforced exactly like send and reply — otherwise it would be the
+ * documented bypass, and a worse one, because it exfiltrates a conversation.
+ *
+ * The subject and the quoted body are materialized server-side at SUBMIT time, so
+ * the human reviews the exact bytes that go out and an approved forward delivers
+ * the reviewer's edit rather than a body re-derived from the live parent.
+ */
+export interface SubmitForwardForReviewInput {
+    inbox: string;
+    message_id: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    /** Optional note to prepend; the parent quote is appended server-side. */
+    text?: string;
+    /** Accepted for wire compatibility but ignored; the materialized forward is plain text. */
+    html?: string;
+    mode?: ReviewMode;
+    /** Required when the resolved mode is review (D3). */
+    intent?: ReviewIntent;
+    category_id?: string;
+    /** See SubmitForReviewInput.category_confidence. */
+    category_confidence?: number;
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    client_id?: string;
+}
+/** Submit a new message for human review (Review Loop, spec §5.1). */
+export interface SubmitForReviewInput {
+    inbox: string;
+    to: string[];
+    subject?: string;
+    text: string;
+    html?: string;
+    cc?: string[];
+    bcc?: string[];
+    reply_to?: string;
+    headers?: Record<string, string>;
+    /**
+     * Files to attach (base64). Attachments now survive submit -> review row ->
+     * approval dispatch, so the human reviews the message WITH its files and the
+     * recipient receives the same ones.
+     */
+    attachments?: AttachmentInput[];
+    /** "review" (default) routes to the human queue; "direct" requests an immediate send. */
+    mode?: ReviewMode;
+    /** Required when the resolved mode is review (D3). */
+    intent?: ReviewIntent;
+    /** Opaque category id (cat_…) matched from the registry; never a name. */
+    category_id?: string;
+    /**
+     * Agent-supplied confidence (0..1) in the category match. Feeds the submit-time
+     * min_confidence auto-send gate ONLY; the server never scores ($0 LLM). Below the
+     * effective threshold (or omitted when a threshold is set) the would-be auto-send
+     * routes to needs_review with gate_outcome held:low_confidence.
+     */
+    category_confidence?: number;
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    client_id?: string;
+}
+/** Submit an in-thread reply for human review (Review Loop). */
+export interface SubmitReplyForReviewInput {
+    inbox: string;
+    thread_id?: string;
+    message_id?: string;
+    text: string;
+    html?: string;
+    cc?: string[];
+    bcc?: string[];
+    reply_to?: string;
+    headers?: Record<string, string>;
+    /** Reply to every thread recipient, not just the original sender. */
+    reply_all?: boolean;
+    /** Files to attach (base64); they survive submit -> review row -> dispatch. */
+    attachments?: AttachmentInput[];
+    mode?: ReviewMode;
+    intent?: ReviewIntent;
+    category_id?: string;
+    /** See SubmitForReviewInput.category_confidence. */
+    category_confidence?: number;
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    client_id?: string;
+}
+/** Filters for listing review requests (Review Loop, spec §5.2). */
+export interface ListReviewsInput {
+    state?: ReviewState | ReviewState[];
+    category_id?: string;
+    inbox?: string;
+    limit?: number;
+    page?: string;
+}
+/** Post a chat turn on a review's thread (Review Loop M5, spec §5.2). */
+export interface PostReviewChatInput {
+    /** Review id (rr_…). */
+    id: string;
+    /** The agent's question/comment for the human reviewer. */
+    text: string;
+    /** Optional idempotency key (sent as the `Idempotency-Key` header). */
+    client_id?: string;
+}
+/** Post a new agent draft under a parent_revision CAS (Review Loop M5, spec §5.2). */
+export interface SubmitRevisionInput {
+    /** Review id (rr_…). */
+    id: string;
+    /** The revision the agent composed against (PRIMARY CAS; 409 STALE on mismatch). */
+    parent_revision: number;
+    /** Optional row-version CAS (defense in depth). */
+    version?: number;
+    subject?: string;
+    /** The canonical new plain-text body (matches `text` on send/reply/forward). */
+    text?: string;
+    /**
+     * DEPRECATED alias for {@link text}, accepted indefinitely so already-shipped
+     * callers keep working. Sending BOTH with different content is rejected 400
+     * `conflicting_alias` — the server never guesses which bytes you meant.
+     */
+    body?: string;
+    html?: string;
+    /**
+     * REPLACES the draft's attachments when present; omit to leave them untouched,
+     * pass `[]` to clear them. Without this a redraft after reviewer feedback could
+     * never restore a file the human reviewed the message WITH.
+     */
+    attachments?: AttachmentInput[];
+    /** When the agent built this draft (informational). */
+    built_at?: string;
+    /** Rule high-water this draft was composed against (born-stale basis). */
+    rules_version_seen?: number;
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    client_id?: string;
+}
+/**
+ * The D19/§8 re-stamp-without-redraft escape valve ($0). The agent asserts it reviewed
+ * the draft against rules `against_version` and no change is needed; the server advances
+ * the draft's composed_* rules-versions WITHOUT a new draft.
+ */
+export interface RestampReviewInput {
+    /** Review id (rr_…). */
+    id: string;
+    /** The category rules-version the agent reviewed against (≤ the current version). */
+    against_version: number;
+    /** Optional: re-stamp the house-style axis to this version (≤ the current version). */
+    house_style_version?: number;
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    client_id?: string;
+}
+/**
+ * A reviewer decision (BYO review-agent plane; D5/§9). `action` is approve|edit|reject|
+ * escalate. `revision`/`version` are the optimistic CAS — a mismatch is a 409 STALE with
+ * NO mutation (the human always wins, D17). `subject`/`body` carry the edited content for
+ * the edit action; `feedback` is the reviewer's note.
+ */
+export interface ReviewerDecideInput {
+    /** Review id (rr_…). */
+    id: string;
+    /** approve | edit | reject | escalate. */
+    action: ReviewerAction;
+    /** The revision you decided against (PRIMARY CAS; 409 STALE on mismatch). */
+    revision: number;
+    /** Optional row-version CAS (defense in depth). */
+    version?: number;
+    /** Edited subject (edit action). */
+    subject?: string;
+    /** Edited body text (edit action). */
+    body?: string;
+    /** Reviewer note (reject: the rule-birth signal; escalate: the human-facing reason). */
+    feedback?: string;
+}
+/** Filters for draining/waiting on review events (Review Loop, spec §5.9). */
+export interface ListReviewEventsInput {
+    /** Restrict the drain to one review's events (rr_…). */
+    review_id?: string;
+    /** Max events to return in one drain. */
+    limit?: number;
+}
+/** Long-poll input: like {@link ListReviewEventsInput} plus a wait budget. */
+export interface WaitForReviewEventInput extends ListReviewEventsInput {
+    /** Long-poll budget in seconds (default ~30, capped ~55). */
+    wait_seconds?: number;
+}
+/** One per-(agent, review) cursor advance for ack_review_event. */
+export interface AckReviewEventEntry {
+    review_id: string;
+    through_seq: number;
+}
+/** Propose a new category (Review Loop registry, D9). */
+export interface ProposeCategoryInput {
+    name: string;
+    description?: string;
+    /** Defaults to org_shared server-side. */
+    scope?: "org_shared" | "agent_private";
+}
+/** Rename / re-describe a category — metadata only (D10). */
+export interface UpdateCategoryInput {
+    id: string;
+    name?: string;
+    description?: string;
+}
+/** Get the ordered writing-rule set (Review Loop, §7). */
+export interface GetRulesInput {
+    /** Category id (cat_…). Empty returns ONLY the house-style/general layer. */
+    category_id?: string;
+    /** Narrow to one layer (general | category). Default returns both. */
+    scope?: "general" | "category";
+}
+/** Save / edit a writing rule (append-only by supersession, D11). */
+export interface SaveRuleInput {
+    /** Defaults from category_id (general iff empty). */
+    scope?: "general" | "category";
+    /** Category id (cat_…); empty = house-style/general (D2). */
+    category_id?: string;
+    rule_text: string;
+    /** Defaults soft. hard = non-overridable. */
+    kind?: "soft" | "hard";
+    priority?: number;
+    source_review_id?: string;
+    source_turn_id?: string;
+    /** Set to EDIT the prior version (rule_…). */
+    supersedes_id?: string;
+    /** Set for a per-agent override; empty = all org agents. */
+    scope_agent_id?: string;
+    /** D8 retro-propagation HUMAN OPT-IN (default false): propagate a NEW category rule to pending siblings. */
+    propagate_to_pending?: boolean;
+    /** Override the propagate batch (0 = base 3, bounded by rework_batch_max). */
+    suggested_batch?: number;
+}
+/** Read the rule/category change audit log (D11). */
+export interface GetRuleAuditInput {
+    entity_kind?: "rule" | "category";
+    entity_id?: string;
+}
+/** Ack input: advance per-review cursor(s) and/or mark broadcast nudges done. */
+export interface AckReviewEventInput {
+    acks?: AckReviewEventEntry[];
+    broadcast_ids?: string[];
+}
+export interface AddContactListInput {
+    inbox: string;
+    kind: ContactListKind;
+    /** Defaults to "send" server-side. */
+    direction?: ContactListDirection;
+    /** A bare email address or a bare domain. */
+    pattern: string;
+}
+/** Filters for listing the caller's own org suppression rows (`GET /v1/suppressions`). */
+export interface ListSuppressionsInput {
+    /** Narrow to one scope; the agent plane only ever returns `org` rows. */
+    scope?: "org" | "shared_domain" | "global";
+    /** Include revoked rows too (default: active rows only). */
+    include_revoked?: boolean;
+    limit?: number;
+    /** Opaque cursor from a previous page's next_cursor. */
+    cursor?: string;
+}
+/** Onboarding modes the agent-facing domains API accepts. */
+export type DomainOnboardMode = "shared" | "ns_delegated" | "manual" | "purchased";
+export interface OnboardDomainInput {
+    domain: string;
+    /**
+     * Onboarding path. Defaults to ns_delegated server-side when omitted. `mode:
+     * "purchased"` spends money at the registrar and therefore requires BOTH the
+     * `domain:manage` scope (the route gate) AND the explicit, default-off
+     * `domain:purchase` scope (it is additionally bounded by the org/project
+     * purchased-domain cap). `manual` and `ns_delegated` need `domain:manage` only.
+     */
+    mode?: DomainOnboardMode;
+    /** A-record IP served at a delegated zone's apex (ns_delegated only). */
+    mail_host_ip?: string;
+    /**
+     * Domain visibility. `org` (default) makes it usable by every project in the
+     * org; `project` binds it to the key's OWN bound project (never client-selected)
+     * so it is only visible/mintable from that project. A legacy/unscoped key falls
+     * back to `org`.
+     */
+    scope?: "org" | "project";
+    /**
+     * Optional assertion that must match the key's bound project — NEVER a
+     * selector. A mismatch is rejected server-side; the binding is always derived
+     * from the key.
+     */
+    project_id?: string;
+}
+export interface WaitForEmailInput {
+    inbox: string;
+    from?: string;
+    subject?: string;
+    /** Case-sensitive Go RE2 expression over subject+body (maps to the API `match` field); use a leading `(?i)` for case-insensitive matching. */
+    regex?: string;
+    /** Prefer an extracted link containing this substring. */
+    link_hint?: string;
+    /** Only match arrivals after the wait begins (default true). */
+    since_now?: boolean;
+    timeout_ms: number;
+}
+export declare class ExtrovertClient {
+    private readonly config;
+    private readonly store?;
+    private apiKey;
+    constructor(config: ExtrovertConfig);
+    get isMock(): boolean;
+    redeemEnrollment(input: RedeemEnrollmentInput): Promise<EnrollmentResult>;
+    /** Grab a free account: `POST /v1/agent/sign-up` (unauthenticated). */
+    signUp(input: {
+        human_email: string;
+        username?: string;
+    }): Promise<SignUpResult>;
+    /** Confirm the signup OTP and elevate scope: `POST /v1/agent/verify`. */
+    verify(input: {
+        otp: string;
+    }): Promise<VerifyResult>;
+    /** Introspect the principal behind the current key: `GET /v1/auth/me`. */
+    whoami(): Promise<WhoAmI>;
+    createInbox(input: CreateInboxInput): Promise<Inbox>;
+    /**
+     * List the agent's inboxes (redesign §4.1 bare-vs-wildcard semantics).
+     *
+     * Scope is in the KEY. By tier:
+     *  - project/inbox key → that project's inboxes. Addressed via the canonical
+     *    project-prefixed envelope `GET /v1/projects/{project_id}/inboxes` (the §5.2
+     *    `{object:"list", data, has_more, next_cursor}` shape) when a project is
+     *    resolved; otherwise the bare `/v1/inboxes` curl-sugar form (which resolves
+     *    to the key's default project and returns the legacy `{inboxes, next_page}`).
+     *  - org key → MUST pick a breadth: pass `project` (a concrete id) or
+     *    `wildcard:true` (`/v1/projects/-/inboxes`, the org subtree). A bare org-key
+     *    list is a 400 `breadth_required` (mirrors the server choke-point) — we fail
+     *    fast client-side with the same code so the agent sees the next call to make.
+     *
+     * Either wire shape is normalized into the internal {@link Page}.
+     */
+    listInboxes(opts?: {
+        limit?: number;
+        project?: string;
+        wildcard?: boolean;
+        cursor?: string;
+    } | number): Promise<Page<Inbox>>;
+    /** The ceiling tier encoded in the current session's agent key (redesign §3.1). */
+    keyTier(): KeyTier;
+    getInbox(idOrAddress: string): Promise<Inbox>;
+    /**
+     * Update an inbox's settings in place: `PATCH /v1/inboxes/{inbox_id}` with
+     * `{display_name?, webhook_url?, daily_send_limit?, metadata?, project_id?}`. The agent-facing
+     * `inbound_webhook_url` maps to the API's `webhook_url`. `metadata` is a shallow
+     * merge: omit it to leave metadata unchanged; an object merges (a `null` value
+     * deletes that key); a top-level `null` clears ALL metadata. Owner-scoped
+     * server-side. Changing `daily_send_limit` requires the opt-in `mailbox:quota`
+     * scope. Returns the updated inbox with the effective enforced cap.
+     */
+    updateInbox(idOrAddress: string, input: UpdateInboxInput): Promise<Inbox>;
+    getCredentials(idOrAddress: string): Promise<MailboxCredentials>;
+    /**
+     * Permanently delete an inbox and its messages/sender identity. Requires
+     * `mailbox:delete`; this cannot be undone.
+     */
+    deleteInbox(idOrAddress: string): Promise<{
+        id: string;
+        deleted: true;
+    }>;
+    /**
+     * Send a new message WITHOUT the review overload.
+     *
+     * The return type is a union because the endpoint has two outcomes and the
+     * account's policy — not the caller — picks between them. This used to be typed
+     * `Promise<Message>` and rendered as a message header, which was garbage against
+     * every real response: the server has never returned a Message here. It returns
+     * `{status:"sent", message_id, review_id}` on the policy's direct path, and the
+     * §5.1 `{kind:"queued_for_review", review}` envelope (HTTP 202) when the policy
+     * queues it — which, under the `require_review` default, is the normal outcome.
+     *
+     * A send with no `intent` under `require_review` never reaches either arm: it is
+     * refused with 422 `intent_required` and NOTHING is sent or queued.
+     */
+    sendEmail(input: SendEmailInput): Promise<SendEmailResult>;
+    /**
+     * Thread-aware reply. Canonical contract:
+     * `POST /v1/inboxes/{inbox_id}/reply` with `{thread_id|message_id, text, html?, cc?,
+     * bcc?, reply_to?, reply_all?}`. The server derives To/Subject/In-Reply-To/
+     * References and returns `{message_id, thread_id, review_id}`. No `to` is sent.
+     *
+     * Like {@link sendEmail} the outcome is policy-decided: a bare reply under
+     * `require_review` is QUEUED (202 `{kind:"queued_for_review"}`), not sent, and a
+     * bare reply with no intent is refused 422 `intent_required`.
+     */
+    replyEmail(input: ReplyEmailInput): Promise<ReplyEmailResult>;
+    /**
+     * Forward an existing message to new recipients, preserving the original.
+     * `POST /v1/inboxes/{inbox_id}/messages/{id}/forward` `{to[], cc?, bcc?, text?, html?}`.
+     * `html` is accepted but ignored: the server materializes one plain-text body
+     * containing both the note and quoted parent, so HTML clients cannot hide the quote.
+     *
+     * Policy-decided like send and reply: a bare forward under `require_review` is
+     * QUEUED, and one with no intent is refused 422 `intent_required`.
+     */
+    forwardEmail(input: ForwardEmailInput): Promise<ReplyEmailResult>;
+    /**
+     * Submit a forward for human review — the SAME endpoint as {@link forwardEmail}
+     * with mode/intent/category_id attached, mirroring how send and reply overload.
+     * Returns the discriminated §5.1 envelope (queued OR sent).
+     */
+    submitForwardForReview(input: SubmitForwardForReviewInput): Promise<SubmitForReviewResult>;
+    /**
+     * Submit a new message for human review (`POST /v1/inboxes/{inbox_id}/send` with
+     * mode/intent/category_id). The server routes per the account/inbox review
+     * policy and returns either `{kind:"queued_for_review"}` (202) or
+     * `{kind:"sent"}` (200, policy-permitted direct/graduated path).
+     */
+    submitForReview(input: SubmitForReviewInput): Promise<SubmitForReviewResult>;
+    /**
+     * Submit an in-thread reply for human review (`POST /v1/inboxes/{inbox_id}/reply`
+     * with mode/intent/category_id). Same routing/return contract as submitForReview.
+     */
+    submitReplyForReview(input: SubmitReplyForReviewInput): Promise<SubmitForReviewResult>;
+    /** List review requests (`GET /v1/reviews`). Customer-scoped; agent monitors its submissions. */
+    listReviews(input?: ListReviewsInput): Promise<Page<Review>>;
+    /** Get one review request (`GET /v1/reviews/{id}`) — current draft + intent + state. */
+    getReview(id: string): Promise<Review>;
+    /** Get a review's append-only thread turns (`GET /v1/reviews/{id}/turns`). */
+    getReviewTurns(id: string): Promise<Page<ReviewTurn>>;
+    /**
+     * Get the human's assembled feedback for a review (`GET /v1/reviews/{id}/feedback`):
+     * the unified + structured diff, the human comments, the decision, and the rules born
+     * from this review (rule_ ids). Read-only; $0 LLM (pure assembly).
+     */
+    getReviewFeedback(id: string): Promise<ReviewFeedback>;
+    /**
+     * Post a chat turn on a review's thread (`POST /v1/reviews/{id}/chat`): append an
+     * agent_question turn, flip in_review -> chatting on the first turn, enqueue a
+     * feedback_added nudge to the human reviewer + emit review.chat. Idempotent on the
+     * client-supplied key. $0 LLM — YOU compose the question.
+     */
+    postReviewChat(input: PostReviewChatInput): Promise<Review>;
+    /**
+     * Post a new agent draft under a parent_revision CAS (`POST /v1/reviews/{id}/
+     * revision`). parent_revision must equal the draft's current revision, else 409
+     * STALE with NO mutation (D17). On a clean CAS the draft is re-rendered in place
+     * (revision++), returned to needs_review, and the reviewer is nudged. $0 LLM — YOU
+     * compose the redraft.
+     */
+    submitRevision(input: SubmitRevisionInput): Promise<Review>;
+    /**
+     * Withdraw a pending review (`POST /v1/reviews/{id}/cancel`): the composing agent
+     * cancels its own review to the terminal cancelled state. A foreign id / another
+     * agent's draft 404s; a terminal review 409s.
+     */
+    cancelReview(input: {
+        id: string;
+        client_id?: string;
+    }): Promise<Review>;
+    /**
+     * Re-stamp a draft's rules-version WITHOUT redrafting (`POST /v1/reviews/{id}/
+     * restamp`; D19/§8 $0 escape valve). Assert "reviewed against vX, no change needed"
+     * and the server advances the draft's composed_* versions with no new draft, no
+     * revision bump, no nudge. against_version above the category's current rules-version
+     * is 400; a terminal/sent draft 409s.
+     */
+    restampReview(input: RestampReviewInput): Promise<Review>;
+    /**
+     * Get the REVIEWER's decision context for a review (`GET /v1/reviews/{id}/
+     * decision-context`; BYO review-agent plane, D5/§9). The reviewer's read-only view:
+     * the intent + current draft + thread + the two-circuit-breaker budget (hop_count vs
+     * max_hops, the hard review_deadline). Requires review:act + a matching active link;
+     * a cross-tenant id is 404, a non-reviewer is 403. `force_to_human` is true when a
+     * reject would be FORCED to the human regardless of intent (D17).
+     */
+    getReviewDecisionContext(id: string): Promise<ReviewDecisionContext>;
+    /**
+     * Submit a reviewer decision (`POST /v1/reviews/{id}/decision`; reviewer_decide,
+     * D5/§9). approve/edit → the PLATFORM ACS-sends with the COMPOSER's creds (the
+     * reviewer NEVER holds mailbox:send — the credential boundary); reject → back to the
+     * composer (needs_review, hop_count++); escalate → the human queue. revision/version
+     * are the CAS (409 STALE on mismatch, NO mutation — the human always wins, D17). The
+     * two circuit breakers (hop_count ≥ max_hops, or the hard review_deadline) FORCE a
+     * reject to the human regardless of intent — `forced_by_breaker` names it. $0 LLM —
+     * you judged; we route, send, and enforce the breakers.
+     */
+    reviewerDecide(input: ReviewerDecideInput): Promise<ReviewerDecisionResult>;
+    /**
+     * Drain the next un-acked review events (`GET /v1/reviews/events`). Non-blocking;
+     * returns the FIFO-ordered nudges + per-review cursors. Side-effect free.
+     */
+    listReviewEvents(input?: ListReviewEventsInput): Promise<ReviewEventsResult>;
+    /**
+     * Long-poll for a review event (`GET /v1/reviews/events/wait`). Blocks ~25–55s
+     * until a nudge is available OR the deadline, then returns like
+     * {@link listReviewEvents} (empty on timeout).
+     */
+    waitForReviewEvent(input?: WaitForReviewEventInput): Promise<ReviewEventsResult>;
+    /**
+     * Ack review events (`POST /v1/reviews/events/ack`): advance per-(agent, review)
+     * cursor(s) and/or mark broadcast nudges done. Idempotent + monotonic.
+     */
+    ackReviewEvent(input: AckReviewEventInput): Promise<{
+        cursors: ReviewEventsResult["cursors"];
+    }>;
+    /**
+     * Browse the category registry (`GET /v1/categories?match=`). Returns id + name +
+     * description + scope + state for fuzzy matching. `match` is a pure lexical filter
+     * (NO LLM on our side) — the agent does the semantic match. Customer-scoped.
+     */
+    listCategories(match?: string): Promise<Page<Category>>;
+    /** Get one category (`GET /v1/categories/{id}`). A foreign id is 404. */
+    getCategory(id: string): Promise<Category>;
+    /**
+     * Propose a new category (`POST /v1/categories`). It stands immediately
+     * (author_kind=agent) and writes a create audit/undo row. Match the registry
+     * first so you do not duplicate an existing bucket.
+     */
+    proposeCategory(input: ProposeCategoryInput): Promise<Category>;
+    /**
+     * Rename / re-describe a category (`PUT /v1/categories/{id}`) — metadata ONLY
+     * (D10). Renaming never breaks a reference; a rename/redescribe undo row is
+     * written. Any agent in the customer may edit (the shared-registry exception).
+     */
+    updateCategory(input: UpdateCategoryInput): Promise<Category>;
+    /**
+     * Read the effective risk dial (`GET /v1/risk-dial`): the account default + every
+     * category's overrides (each with its resolved effective value; null override =
+     * inherit). Read-only — agents read but NEVER flip the dial (setting it is a human
+     * console action; D16).
+     */
+    getRiskDial(): Promise<RiskDial>;
+    /**
+     * Read a category's graduation gate status (`GET /v1/categories/{id}/graduation-
+     * status`): the gates passed / still needed toward the next rung (approvals N/needed,
+     * age, maturity gate, drift vs K, can_graduate). Read-only.
+     */
+    getGraduationStatus(categoryId: string): Promise<GraduationStatus>;
+    /**
+     * Propose graduating a category (`POST /v1/categories/{id}/graduation-request`).
+     * RECORDS the request (durable evidence) and returns the current gate status; it
+     * does NOT change the category state — flipping the bit is a human (console) action
+     * (D16/D6). A never_graduate category stays locked.
+     */
+    proposeGraduation(categoryId: string, evidence?: Record<string, unknown>): Promise<GraduationStatus>;
+    /**
+     * Read the D19/§8 backlog-reconciliation status (`GET /v1/categories/{id}/
+     * backlog-status`): how many QUEUED drafts are stale vs current-enough against the
+     * current rules-version (a pure $0-LLM integer compare). Read-only — agents READ the
+     * picture; the human (console scan-backlog) / hooks TRIGGER the actual sweep.
+     */
+    getBacklogStatus(categoryId: string): Promise<ScanBacklogStatus>;
+    /**
+     * Read the demand-driven pacing state (`GET /v1/categories/{id}/pacing-state`;
+     * M7 Slice B/§8): the human review cursor, the effective window/ceiling/interval, and
+     * each queued draft's in-window/redrafting/behind-cursor classification. Read-only;
+     * the cursor advances from the human's console approve/reject/edit actions.
+     */
+    getPacingState(categoryId: string): Promise<CategoryPacingState>;
+    /**
+     * Get the ORDERED active rule set (`GET /v1/rules?category_id=&scope=`). The §7
+     * precedence ladder is applied SERVER-SIDE (NO LLM): hard>soft; per-agent>category>
+     * general; human>agent; newest rev/created_at; higher priority; plus a soft cap.
+     * Includes the general/house-style layer (D2) IN ADDITION to the category's rules.
+     */
+    getRules(input?: GetRulesInput): Promise<Page<Rule>>;
+    /**
+     * Save / edit a writing rule (`PUT /v1/rules`) — append-only by supersession (D11).
+     * scope='general' iff category_id is empty (house-style, D2). With supersedes_id
+     * the write is an EDIT (rev+1, same lineage). Writes a create/supersede audit row.
+     */
+    saveRule(input: SaveRuleInput): Promise<Rule>;
+    /**
+     * Promote a rule between the category and general/house-style layers
+     * (`POST /v1/rules/{id}/promote`) via a supersession.
+     */
+    promoteRule(id: string, toScope: "general" | "category"): Promise<Rule>;
+    /** Retire a rule (`POST /v1/rules/{id}/retire`) — soft delete; history survives. */
+    retireRule(id: string): Promise<Rule>;
+    /**
+     * Read the rule/category change audit log (`GET /v1/rules/audit`) — read-only,
+     * agent-visible (the audit log is the shared safety net, D11).
+     */
+    getRuleAudit(input?: GetRuleAuditInput): Promise<Page<RuleAuditEntry>>;
+    /**
+     * Undo a rule change (`POST /v1/rules/audit/{udo_id}/undo`) — restore the prior
+     * version as a forward 'restore' supersession (D11; agents may undo too).
+     * Idempotent: a re-undo of an already-undone row is a clean 409.
+     */
+    undoRuleChange(udoId: string): Promise<Rule>;
+    /**
+     * List messages in an inbox, newest-first. Canonical contract:
+     * `GET /v1/inboxes/{inbox_id}/messages` with optional exact-field filters
+     * (from/to/subject), an `unread=true` filter (native IMAP \Seen), and
+     * limit/offset paging. Returns the canonical `Page<Message>` ({items,total}).
+     */
+    listMessages(input: {
+        inbox: string;
+        limit?: number;
+        offset?: number;
+        unread_only?: boolean;
+        from?: string;
+        to?: string;
+        subject?: string;
+    }): Promise<Page<Message>>;
+    /** Fetch a single message by its opaque id (`GET /v1/messages/{id}`). */
+    getMessage(id: string): Promise<Message>;
+    /**
+     * List a message's attachment metadata
+     * (`GET /v1/inboxes/{inbox_id}/messages/{id}/attachments` → `Page<Attachment>`).
+     */
+    listAttachments(input: {
+        inbox: string;
+        message_id: string;
+    }): Promise<Page<Attachment>>;
+    /**
+     * Download one attachment's bytes (base64) + metadata
+     * (`GET /v1/inboxes/{inbox_id}/messages/{id}/attachments/{attId}` → raw bytes with
+     * Content-Type + Content-Disposition). The "easy attachment fetch."
+     */
+    getAttachment(input: {
+        inbox: string;
+        message_id: string;
+        attachment_id: string;
+    }): Promise<AttachmentDownload>;
+    /**
+     * Mark a message read/unread via the native IMAP \Seen flag
+     * (`PATCH /v1/inboxes/{inbox_id}/messages/{id}` {read}). The inbox is resolved
+     * from the message id. Returns the updated message.
+     */
+    markRead(input: {
+        inbox: string;
+        id: string;
+        read: boolean;
+    }): Promise<Message>;
+    listThreads(input: {
+        inbox: string;
+        limit?: number;
+    }): Promise<Page<Thread>>;
+    /**
+     * Fetch one thread (with its messages, oldest-first) by stable id, scoped to
+     * the owning inbox: `GET /v1/inboxes/{inbox_id}/threads/{id}`.
+     */
+    getThread(input: {
+        inbox: string;
+        thread_id: string;
+    }): Promise<ThreadDetail>;
+    /**
+     * Delete a message: move it to Trash, or permanently expunge it when
+     * `expunge` is set (`DELETE /v1/inboxes/{inbox_id}/messages/{id}?expunge=`). A
+     * message already in Trash is always expunged.
+     */
+    deleteMessage(input: {
+        inbox: string;
+        id: string;
+        expunge?: boolean;
+    }): Promise<DeleteResult>;
+    /**
+     * Delete an entire thread (every message): move to Trash, or expunge when
+     * `expunge` is set (`DELETE /v1/inboxes/{inbox_id}/threads/{id}?expunge=`).
+     */
+    deleteThread(input: {
+        inbox: string;
+        thread_id: string;
+        expunge?: boolean;
+    }): Promise<DeleteResult>;
+    /**
+     * Batch mark read/unread and/or move folder for a list of message ids in one
+     * inbox (`PATCH /v1/inboxes/{inbox_id}/messages/batch`). At least one of
+     * `read` / `folder` must be set; returns the per-id `{updated, failed}` split.
+     */
+    batchUpdateMessages(input: {
+        inbox: string;
+        ids: string[];
+        read?: boolean;
+        folder?: string;
+    }): Promise<BatchUpdateResult>;
+    /**
+     * Full-text search backed by IMAP SEARCH, scoped to one inbox
+     * (`GET /v1/inboxes/{inbox_id}/messages/search?q=...`). When `inbox` is omitted,
+     * iterate every inbox the agent owns and merge the results (newest-first).
+     */
+    search(input: {
+        query: string;
+        inbox?: string;
+        limit?: number;
+    }): Promise<Page<Message>>;
+    waitForEmail(input: WaitForEmailInput): Promise<WaitForEmailResult>;
+    /**
+     * Register an inbound webhook (`POST /v1/webhooks`). The signing `secret` is
+     * returned ONCE here; deliveries are HMAC-signed in the canonical
+     * `X-Extrovert-Signature: t=<unix>,v1=<hex>` format.
+     */
+    registerWebhook(input: RegisterWebhookInput): Promise<Webhook>;
+    /** List registered webhooks (`GET /v1/webhooks`); secrets are redacted. */
+    listWebhooks(): Promise<Page<Webhook>>;
+    /** Get one webhook by id (`GET /v1/webhooks/{id}`); secret redacted. */
+    getWebhook(id: string): Promise<Webhook>;
+    /**
+     * Update a webhook in place (`PATCH /v1/webhooks/{id}`). Every field is
+     * optional; an omitted field is left unchanged (PATCH semantics). The signing
+     * secret is immutable and stays redacted in the response.
+     */
+    updateWebhook(id: string, input: {
+        url?: string;
+        events?: WebhookEvent[];
+        inbox?: string;
+        active?: boolean;
+    }): Promise<Webhook>;
+    /** Delete a webhook by id (`DELETE /v1/webhooks/{id}`). */
+    deleteWebhook(id: string): Promise<{
+        id: string;
+        deleted: true;
+    }>;
+    /**
+     * Add an allow/block entry to an inbox's contact lists
+     * (`POST /v1/inboxes/{inbox_id}/lists`). A `block` entry rejects a matching
+     * recipient on send; when an `allow` entry exists, sends from this inbox are
+     * restricted to recipients that match one (allowlist mode).
+     */
+    addContactListEntry(input: AddContactListInput): Promise<ContactListEntry>;
+    /** List the contact-list entries governing an inbox (`GET /v1/inboxes/{inbox_id}/lists`). */
+    listContactListEntries(inbox: string): Promise<Page<ContactListEntry>>;
+    /** Delete a contact-list entry by id (`DELETE /v1/inboxes/{inbox_id}/lists/{id}`). */
+    deleteContactListEntry(inbox: string, id: string): Promise<{
+        id: string;
+        deleted: true;
+    }>;
+    /** List the customer's onboarded domains (`GET /v1/domains`). Canonical page envelope. */
+    listDomains(): Promise<Page<Domain>>;
+    /** Get one domain's detail + verification status + the DNS records to set (`GET /v1/domains/{domain}`). */
+    getDomain(domain: string): Promise<Domain>;
+    /** Onboard/add a domain for the customer (`POST /v1/domains`). */
+    onboardDomain(input: OnboardDomainInput): Promise<Domain>;
+    /** Trigger/refresh verification for a domain (`POST /v1/domains/{domain}/verify`). */
+    verifyDomain(domain: string): Promise<Domain>;
+    /**
+     * Offboard (remove) a domain from the customer (`DELETE /v1/domains/{domain}`).
+     * The API accepts the request (HTTP 202) and runs the teardown — reaping the
+     * outbound provider sender identities + routing rows, then scrubbing the DNS
+     * zone/records and the domain row — as an async job. This returns the job id and
+     * a poll URL (`status_url`, i.e. `GET /v1/jobs/{job_id}`); offboarding is
+     * ACCEPTED, not yet complete. Poll with `getJob(job_id)` (the `get_job` tool)
+     * until the status is terminal.
+     */
+    offboardDomain(domain: string): Promise<DomainOffboard>;
+    /**
+     * Poll the status of an async job (`GET /v1/jobs/{job_id}`) — currently only
+     * the domain-offboard teardown enqueues one. `status` is terminal on
+     * succeeded/failed/cancelled; keep polling otherwise.
+     */
+    getJob(jobId: string): Promise<Job>;
+    /**
+     * Pre-check whether the caller's org suppresses a recipient
+     * (`GET /v1/suppressions?recipient=…`). Returns `{recipient, suppressed, rows}`
+     * over the caller's OWN active org rows — never a global/shared/cross-tenant
+     * opt-out. Use it BEFORE composing to skip a would-be-rejected recipient.
+     */
+    precheckSuppression(recipient: string): Promise<SuppressionPrecheck>;
+    /**
+     * List the caller's own org suppression rows (`GET /v1/suppressions`). No
+     * `recipient` is sent here — that param switches the server to the pre-check.
+     */
+    listSuppressions(input?: ListSuppressionsInput): Promise<Page<SuppressionEntry>>;
+    /**
+     * Revoke one org-scope suppression row (`POST /v1/suppressions/{id}/revoke`),
+     * re-enabling sending to that recipient. A `reason` is REQUIRED (empty is a 400)
+     * and is audit-logged. A foreign/global/shared id is an indistinguishable 404.
+     */
+    revokeSuppression(id: string, reason: string): Promise<SuppressionEntry>;
+    /**
+     * The caller's org deliverability rollup (`GET /v1/reputation`): derived status
+     * badge, per-provider/tenant sending status, latest Sends/Bounces/Complaints
+     * window, and open-finding count. Read-only; strictly org-scoped. Advisor
+     * findings show `unavailable_vdm_disabled` when VDM is off.
+     */
+    getReputation(): Promise<ReputationRollup>;
+    /**
+     * List the caller's org deliverability findings (`GET /v1/reputation/findings`),
+     * newest-first, with optional status/severity/domain/sender filters. Read-only.
+     */
+    listDeliverabilityFindings(input?: ListDeliverabilityFindingsInput): Promise<Page<ReputationFinding>>;
+    private get;
+    /**
+     * Fetch a binary endpoint (the attachment download) and return its bytes as
+     * base64 plus the filename + content type pulled from the response headers.
+     * Bypasses the JSON `request` path so arbitrary bytes survive intact.
+     */
+    private getBinary;
+    private post;
+    private del;
+    private patch;
+    private put;
+    private request;
+    private setSessionKey;
+}
+export { NotFoundError };
+//# sourceMappingURL=client.d.ts.map