@extrovert.dev/mcp 0.1.0-pre.3

package/dist/client.js

@@ -0,0 +1,1354 @@
+/**
+ * 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 { FixtureStore, NotFoundError } from "./fixtures.js";
+import { keyTierFromRawKey, listEnvelopeToPage } from "./types.js";
+/** Normalized error surfaced from any client call. */
+export class ExtrovertApiError extends Error {
+    status;
+    code;
+    details;
+    problemErrors;
+    constructor(message, status, code, details, 
+    /**
+     * 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) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.problemErrors = problemErrors;
+        this.name = "ExtrovertApiError";
+    }
+}
+export class ExtrovertClient {
+    config;
+    store;
+    apiKey;
+    constructor(config) {
+        this.config = config;
+        this.apiKey = config.apiKey;
+        // The offline store enforces the SAME key-tier ceiling assertions as the live
+        // choke-point, derived from the configured key prefix (redesign §3.1).
+        if (config.mock) {
+            this.store = new FixtureStore({
+                keyTier: keyTierFromRawKey(config.apiKey),
+                reviewPolicy: config.mockReviewPolicy,
+            });
+        }
+    }
+    get isMock() {
+        return this.config.mock;
+    }
+    // ---- enrollment (POST /v1/enroll) -------------------------------------
+    async redeemEnrollment(input) {
+        if (this.store) {
+            const res = this.store.redeemEnrollment(input.enrollment_token, input.agent_handle);
+            this.setSessionKey(res.agent_key);
+            return res;
+        }
+        const res = await this.post("/v1/enroll", {
+            token: input.enrollment_token,
+            agent_handle: input.agent_handle,
+            client_id: input.client_id,
+        }, undefined, idempotencyHeader(input.client_id));
+        this.setSessionKey(res.agent_key);
+        return res;
+    }
+    // ---- self-signup + auth (Slice E) -------------------------------------
+    /** Grab a free account: `POST /v1/agent/sign-up` (unauthenticated). */
+    async signUp(input) {
+        if (this.store) {
+            const res = this.store.signUp(input);
+            this.setSessionKey(res.agent_key);
+            return res;
+        }
+        const res = await this.post("/v1/agent/sign-up", {
+            human_email: input.human_email,
+            username: input.username,
+        });
+        this.setSessionKey(res.agent_key);
+        return res;
+    }
+    /** Confirm the signup OTP and elevate scope: `POST /v1/agent/verify`. */
+    async verify(input) {
+        if (this.store) {
+            const res = this.store.verify(input.otp);
+            this.setSessionKey(res.agent_key);
+            return res;
+        }
+        const res = await this.post("/v1/agent/verify", { otp: input.otp });
+        this.setSessionKey(res.agent_key);
+        return res;
+    }
+    /** Introspect the principal behind the current key: `GET /v1/auth/me`. */
+    async whoami() {
+        if (this.store)
+            return this.store.whoami();
+        return this.get("/v1/auth/me");
+    }
+    // ---- inboxes ----------------------------------------------------------
+    async createInbox(input) {
+        if (this.store) {
+            return this.store.createInbox({
+                username: input.username,
+                domain: input.domain,
+                displayName: input.display_name,
+                inboundWebhookUrl: input.inbound_webhook_url,
+                metadata: input.metadata,
+                projectId: input.project_id,
+                clientId: input.client_id,
+            });
+        }
+        const body = {};
+        if (input.username !== undefined)
+            body.username = input.username;
+        if (input.domain !== undefined)
+            body.domain = input.domain;
+        if (input.display_name !== undefined)
+            body.display_name = input.display_name;
+        // The agent-facing `inbound_webhook_url` maps to the API's `webhook_url`.
+        if (input.inbound_webhook_url !== undefined)
+            body.webhook_url = input.inbound_webhook_url;
+        if (input.metadata !== undefined)
+            body.metadata = input.metadata;
+        if (input.project_id !== undefined)
+            body.project_id = input.project_id;
+        if (input.client_id !== undefined)
+            body.client_id = input.client_id;
+        return this.post("/v1/inboxes", body, undefined, idempotencyHeader(input.client_id));
+    }
+    /**
+     * 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}.
+     */
+    async listInboxes(opts = {}) {
+        // Back-compat: a bare number is the page limit.
+        const o = typeof opts === "number" ? { limit: opts } : opts;
+        const limit = o.limit ?? 20;
+        if (this.store)
+            return this.store.listInboxes({ limit, project: o.project, wildcard: o.wildcard });
+        const tier = this.keyTier();
+        // Resolve the project segment for the canonical envelope form.
+        const projectSegment = o.wildcard ? "-" : o.project;
+        if (projectSegment) {
+            // Org key on the wildcard is fine; a non-org key on the wildcard is a 403
+            // (server enforces; we let the server be authoritative and just call it).
+            const list = await this.get(`/v1/projects/${encodeURIComponent(projectSegment)}/inboxes`, { limit, cursor: o.cursor });
+            return listEnvelopeToPage(list);
+        }
+        if (tier === "org") {
+            // Bare list under an org key needs an explicit breadth (RFC D2 / §4.1).
+            throw new ExtrovertApiError("An org-tier key must pick a list breadth: pass a project id (e.g. list_inboxes project=<id>) " +
+                "or wildcard=true (the org subtree).", 400, "breadth_required");
+        }
+        // project/inbox key, bare sugar → the legacy {inboxes, next_page} shape.
+        const raw = await this.get("/v1/inboxes", { limit });
+        const items = raw.inboxes ?? raw.items ?? [];
+        const page = { items };
+        const cursor = raw.next_cursor ?? raw.next_page;
+        if (cursor)
+            page.next_cursor = cursor;
+        return page;
+    }
+    /** The ceiling tier encoded in the current session's agent key (redesign §3.1). */
+    keyTier() {
+        return keyTierFromRawKey(this.apiKey);
+    }
+    async getInbox(idOrAddress) {
+        if (this.store) {
+            const inbox = this.store.getInbox(idOrAddress);
+            if (!inbox)
+                throw new ExtrovertApiError(`Inbox not found: ${idOrAddress}`, 404, "not_found");
+            return inbox;
+        }
+        return this.get(`/v1/inboxes/${encodeURIComponent(idOrAddress)}`);
+    }
+    /**
+     * 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.
+     */
+    async updateInbox(idOrAddress, input) {
+        if (this.store) {
+            const inbox = this.store.updateInbox(idOrAddress, {
+                displayName: input.display_name,
+                inboundWebhookUrl: input.inbound_webhook_url,
+                dailySendLimit: input.daily_send_limit,
+                metadata: input.metadata,
+                projectId: input.project_id,
+            });
+            if (!inbox)
+                throw new ExtrovertApiError(`Inbox not found: ${idOrAddress}`, 404, "not_found");
+            return inbox;
+        }
+        const body = {};
+        if (input.display_name !== undefined)
+            body.display_name = input.display_name;
+        if (input.inbound_webhook_url !== undefined)
+            body.webhook_url = input.inbound_webhook_url;
+        if (input.daily_send_limit !== undefined)
+            body.daily_send_limit = input.daily_send_limit;
+        // `metadata` is forwarded verbatim — including an explicit top-level `null`
+        // (clear-all) — so the merge-null-clear semantics reach the server unchanged.
+        if (input.metadata !== undefined)
+            body.metadata = input.metadata;
+        if (input.project_id !== undefined)
+            body.project_id = input.project_id;
+        return this.patch(`/v1/inboxes/${encodeURIComponent(idOrAddress)}`, body);
+    }
+    // ---- credentials (GET /v1/inboxes/{inbox_id}/credentials) -------------------
+    async getCredentials(idOrAddress) {
+        if (this.store)
+            return this.store.getCredentials(idOrAddress);
+        return this.get(`/v1/inboxes/${encodeURIComponent(idOrAddress)}/credentials`);
+    }
+    /**
+     * Permanently delete an inbox and its messages/sender identity. Requires
+     * `mailbox:delete`; this cannot be undone.
+     */
+    async deleteInbox(idOrAddress) {
+        if (this.store) {
+            const result = this.store.deleteInbox(idOrAddress);
+            if (!result)
+                throw new ExtrovertApiError(`Inbox not found: ${idOrAddress}`, 404, "not_found");
+            return result;
+        }
+        return this.del(`/v1/inboxes/${encodeURIComponent(idOrAddress)}`);
+    }
+    // ---- send / reply -----------------------------------------------------
+    /**
+     * 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.
+     */
+    async sendEmail(input) {
+        if (this.store)
+            return this.store.sendEmail(input);
+        const { inbox, client_id, ...body } = input;
+        // `body` carries to/subject/text/html/cc/bcc/reply_to/headers and (when
+        // present) attachments — the canonical send contract, mirroring reply; the
+        // server emits multipart/mixed when needed and drops unsafe header names.
+        return this.post(`/v1/inboxes/${encodeURIComponent(inbox)}/send`, body, undefined, idempotencyHeader(client_id));
+    }
+    /**
+     * 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`.
+     */
+    async replyEmail(input) {
+        if (this.store) {
+            return this.store.replyEmail({
+                inbox: input.inbox,
+                threadId: input.thread_id,
+                messageId: input.message_id,
+                text: input.text,
+                html: input.html,
+                cc: input.cc,
+                bcc: input.bcc,
+                replyTo: input.reply_to,
+                replyAll: input.reply_all,
+                attachments: input.attachments,
+            });
+        }
+        const { inbox, client_id, ...body } = input;
+        return this.post(`/v1/inboxes/${encodeURIComponent(inbox)}/reply`, body, undefined, idempotencyHeader(client_id));
+    }
+    /**
+     * 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`.
+     */
+    async forwardEmail(input) {
+        if (this.store) {
+            return this.store.forwardEmail({
+                inbox: input.inbox,
+                messageId: input.message_id,
+                to: input.to,
+                cc: input.cc,
+                bcc: input.bcc,
+                text: input.text,
+                html: input.html,
+            });
+        }
+        const { inbox, message_id, client_id, ...body } = input;
+        return this.post(`/v1/inboxes/${encodeURIComponent(inbox)}/messages/${encodeURIComponent(message_id)}/forward`, body, undefined, idempotencyHeader(client_id));
+    }
+    /**
+     * 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).
+     */
+    async submitForwardForReview(input) {
+        if (this.store)
+            return this.store.submitForwardForReview(input);
+        const { inbox, message_id, client_id, ...body } = input;
+        return this.post(`/v1/inboxes/${encodeURIComponent(inbox)}/messages/${encodeURIComponent(message_id)}/forward`, body, undefined, idempotencyHeader(client_id));
+    }
+    // ---- Review Loop (HITL) -----------------------------------------------
+    /**
+     * 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).
+     */
+    async submitForReview(input) {
+        if (this.store)
+            return this.store.submitForReview(input);
+        const { inbox, client_id, ...body } = input;
+        return this.post(`/v1/inboxes/${encodeURIComponent(inbox)}/send`, body, undefined, idempotencyHeader(client_id));
+    }
+    /**
+     * 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.
+     */
+    async submitReplyForReview(input) {
+        if (this.store)
+            return this.store.submitReplyForReview(input);
+        const { inbox, client_id, ...body } = input;
+        return this.post(`/v1/inboxes/${encodeURIComponent(inbox)}/reply`, body, undefined, idempotencyHeader(client_id));
+    }
+    /** List review requests (`GET /v1/reviews`). Customer-scoped; agent monitors its submissions. */
+    async listReviews(input = {}) {
+        if (this.store)
+            return this.store.listReviews(input);
+        const query = {};
+        if (input.state !== undefined) {
+            query.state = Array.isArray(input.state) ? input.state.join(",") : input.state;
+        }
+        if (input.category_id !== undefined)
+            query.category_id = input.category_id;
+        if (input.inbox !== undefined)
+            query.inbox = input.inbox;
+        if (input.limit !== undefined)
+            query.limit = input.limit;
+        if (input.page !== undefined)
+            query.page = input.page;
+        return this.get("/v1/reviews", query);
+    }
+    /** Get one review request (`GET /v1/reviews/{id}`) — current draft + intent + state. */
+    async getReview(id) {
+        if (this.store)
+            return this.store.getReview(id);
+        return this.get(`/v1/reviews/${encodeURIComponent(id)}`);
+    }
+    /** Get a review's append-only thread turns (`GET /v1/reviews/{id}/turns`). */
+    async getReviewTurns(id) {
+        if (this.store)
+            return this.store.getReviewTurns(id);
+        return this.get(`/v1/reviews/${encodeURIComponent(id)}/turns`);
+    }
+    /**
+     * 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).
+     */
+    async getReviewFeedback(id) {
+        if (this.store)
+            return this.store.getReviewFeedback(id);
+        return this.get(`/v1/reviews/${encodeURIComponent(id)}/feedback`);
+    }
+    /**
+     * 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.
+     */
+    async postReviewChat(input) {
+        if (this.store)
+            return this.store.postReviewChat(input);
+        return this.post(`/v1/reviews/${encodeURIComponent(input.id)}/chat`, { text: input.text }, undefined, idempotencyHeader(input.client_id));
+    }
+    /**
+     * 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.
+     */
+    async submitRevision(input) {
+        if (this.store)
+            return this.store.submitRevision(input);
+        const body = { parent_revision: input.parent_revision };
+        if (input.version !== undefined)
+            body.version = input.version;
+        if (input.subject !== undefined)
+            body.subject = input.subject;
+        // `text` is canonical; `body` is the permanent deprecated alias. BOTH are
+        // forwarded verbatim when supplied so the server's own alias resolution decides
+        // — including rejecting a both-but-different pair with 400 conflicting_alias.
+        // Picking a winner here would silently relay the wrong bytes.
+        if (input.text !== undefined)
+            body.text = input.text;
+        if (input.body !== undefined)
+            body.body = input.body;
+        if (input.html !== undefined)
+            body.html = input.html;
+        if (input.attachments !== undefined)
+            body.attachments = input.attachments;
+        if (input.built_at !== undefined)
+            body.built_at = input.built_at;
+        if (input.rules_version_seen !== undefined)
+            body.rules_version_seen = input.rules_version_seen;
+        return this.post(`/v1/reviews/${encodeURIComponent(input.id)}/revision`, body, undefined, idempotencyHeader(input.client_id));
+    }
+    /**
+     * 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.
+     */
+    async cancelReview(input) {
+        if (this.store)
+            return this.store.cancelReview(input.id);
+        return this.post(`/v1/reviews/${encodeURIComponent(input.id)}/cancel`, {}, undefined, idempotencyHeader(input.client_id));
+    }
+    /**
+     * 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.
+     */
+    async restampReview(input) {
+        if (this.store)
+            return this.store.restampReview(input);
+        const body = { against_version: input.against_version };
+        if (input.house_style_version !== undefined)
+            body.house_style_version = input.house_style_version;
+        return this.post(`/v1/reviews/${encodeURIComponent(input.id)}/restamp`, body, undefined, idempotencyHeader(input.client_id));
+    }
+    /**
+     * 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).
+     */
+    async getReviewDecisionContext(id) {
+        if (this.store)
+            return this.store.getReviewDecisionContext(id);
+        return this.get(`/v1/reviews/${encodeURIComponent(id)}/decision-context`);
+    }
+    /**
+     * 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.
+     */
+    async reviewerDecide(input) {
+        if (this.store)
+            return this.store.reviewerDecide(input);
+        const body = { action: input.action, revision: input.revision };
+        if (input.version !== undefined)
+            body.version = input.version;
+        if (input.subject !== undefined)
+            body.subject = input.subject;
+        if (input.body !== undefined)
+            body.body = input.body;
+        if (input.feedback !== undefined)
+            body.feedback = input.feedback;
+        return this.post(`/v1/reviews/${encodeURIComponent(input.id)}/decision`, body);
+    }
+    /**
+     * Drain the next un-acked review events (`GET /v1/reviews/events`). Non-blocking;
+     * returns the FIFO-ordered nudges + per-review cursors. Side-effect free.
+     */
+    async listReviewEvents(input = {}) {
+        if (this.store)
+            return this.store.listReviewEvents(input);
+        const query = {};
+        if (input.review_id !== undefined)
+            query.review_id = input.review_id;
+        if (input.limit !== undefined)
+            query.limit = input.limit;
+        return this.get("/v1/reviews/events", query);
+    }
+    /**
+     * 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).
+     */
+    async waitForReviewEvent(input = {}) {
+        if (this.store)
+            return this.store.waitForReviewEvent(input);
+        const query = {};
+        if (input.review_id !== undefined)
+            query.review_id = input.review_id;
+        if (input.limit !== undefined)
+            query.limit = input.limit;
+        if (input.wait_seconds !== undefined)
+            query.wait_seconds = input.wait_seconds;
+        return this.get("/v1/reviews/events/wait", query);
+    }
+    /**
+     * Ack review events (`POST /v1/reviews/events/ack`): advance per-(agent, review)
+     * cursor(s) and/or mark broadcast nudges done. Idempotent + monotonic.
+     */
+    async ackReviewEvent(input) {
+        if (this.store)
+            return this.store.ackReviewEvent(input);
+        return this.post("/v1/reviews/events/ack", {
+            acks: input.acks ?? [],
+            broadcast_ids: input.broadcast_ids ?? [],
+        });
+    }
+    // ---- Category registry (Review Loop, D9/D10) --------------------------
+    /**
+     * 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.
+     */
+    async listCategories(match) {
+        if (this.store)
+            return this.store.listCategories(match);
+        const query = {};
+        if (match !== undefined && match.trim() !== "")
+            query.match = match;
+        return this.get("/v1/categories", query);
+    }
+    /** Get one category (`GET /v1/categories/{id}`). A foreign id is 404. */
+    async getCategory(id) {
+        if (this.store)
+            return this.store.getCategory(id);
+        return this.get(`/v1/categories/${encodeURIComponent(id)}`);
+    }
+    /**
+     * 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.
+     */
+    async proposeCategory(input) {
+        if (this.store)
+            return this.store.proposeCategory(input);
+        return this.post("/v1/categories", {
+            name: input.name,
+            description: input.description,
+            scope: input.scope,
+        });
+    }
+    /**
+     * 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).
+     */
+    async updateCategory(input) {
+        if (this.store)
+            return this.store.updateCategory(input);
+        const body = {};
+        if (input.name !== undefined)
+            body.name = input.name;
+        if (input.description !== undefined)
+            body.description = input.description;
+        return this.put(`/v1/categories/${encodeURIComponent(input.id)}`, body);
+    }
+    // ---- Graduation + risk dial (Review Loop, D16/D6/D17) — agent READ + PROPOSE --
+    /**
+     * 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).
+     */
+    async getRiskDial() {
+        if (this.store)
+            return this.store.getRiskDial();
+        return this.get("/v1/risk-dial");
+    }
+    /**
+     * 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.
+     */
+    async getGraduationStatus(categoryId) {
+        if (this.store)
+            return this.store.getGraduationStatus(categoryId);
+        return this.get(`/v1/categories/${encodeURIComponent(categoryId)}/graduation-status`);
+    }
+    /**
+     * 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.
+     */
+    async proposeGraduation(categoryId, evidence) {
+        if (this.store)
+            return this.store.proposeGraduation(categoryId, evidence);
+        return this.post(`/v1/categories/${encodeURIComponent(categoryId)}/graduation-request`, {
+            evidence: evidence ?? {},
+        });
+    }
+    /**
+     * 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.
+     */
+    async getBacklogStatus(categoryId) {
+        if (this.store)
+            return this.store.getBacklogStatus(categoryId);
+        return this.get(`/v1/categories/${encodeURIComponent(categoryId)}/backlog-status`);
+    }
+    /**
+     * 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.
+     */
+    async getPacingState(categoryId) {
+        if (this.store)
+            return this.store.getPacingState(categoryId);
+        return this.get(`/v1/categories/${encodeURIComponent(categoryId)}/pacing-state`);
+    }
+    // ---- Writing rules + house-style + precedence ladder + audit/undo ------
+    /**
+     * 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.
+     */
+    async getRules(input = {}) {
+        if (this.store)
+            return this.store.getRules(input);
+        const query = {};
+        if (input.category_id)
+            query.category_id = input.category_id;
+        if (input.scope)
+            query.scope = input.scope;
+        return this.get("/v1/rules", query);
+    }
+    /**
+     * 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.
+     */
+    async saveRule(input) {
+        if (this.store)
+            return this.store.saveRule(input);
+        const body = { rule_text: input.rule_text };
+        if (input.scope)
+            body.scope = input.scope;
+        if (input.category_id)
+            body.category_id = input.category_id;
+        if (input.kind)
+            body.kind = input.kind;
+        if (input.priority !== undefined)
+            body.priority = input.priority;
+        if (input.source_review_id)
+            body.source_review_id = input.source_review_id;
+        if (input.source_turn_id)
+            body.source_turn_id = input.source_turn_id;
+        if (input.supersedes_id)
+            body.supersedes_id = input.supersedes_id;
+        if (input.scope_agent_id)
+            body.scope_agent_id = input.scope_agent_id;
+        if (input.propagate_to_pending !== undefined)
+            body.propagate_to_pending = input.propagate_to_pending;
+        if (input.suggested_batch !== undefined)
+            body.suggested_batch = input.suggested_batch;
+        return this.put("/v1/rules", body);
+    }
+    /**
+     * Promote a rule between the category and general/house-style layers
+     * (`POST /v1/rules/{id}/promote`) via a supersession.
+     */
+    async promoteRule(id, toScope) {
+        if (this.store)
+            return this.store.promoteRule(id, toScope);
+        return this.post(`/v1/rules/${encodeURIComponent(id)}/promote`, { to_scope: toScope });
+    }
+    /** Retire a rule (`POST /v1/rules/{id}/retire`) — soft delete; history survives. */
+    async retireRule(id) {
+        if (this.store)
+            return this.store.retireRule(id);
+        return this.post(`/v1/rules/${encodeURIComponent(id)}/retire`, {});
+    }
+    /**
+     * Read the rule/category change audit log (`GET /v1/rules/audit`) — read-only,
+     * agent-visible (the audit log is the shared safety net, D11).
+     */
+    async getRuleAudit(input = {}) {
+        if (this.store)
+            return this.store.getRuleAudit(input);
+        const query = {};
+        if (input.entity_kind)
+            query.entity_kind = input.entity_kind;
+        if (input.entity_id)
+            query.entity_id = input.entity_id;
+        return this.get("/v1/rules/audit", query);
+    }
+    /**
+     * 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.
+     */
+    async undoRuleChange(udoId) {
+        if (this.store)
+            return this.store.undoRuleChange(udoId);
+        return this.post(`/v1/rules/audit/${encodeURIComponent(udoId)}/undo`, {});
+    }
+    // ---- read / list / search ---------------------------------------------
+    /**
+     * 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}).
+     */
+    async listMessages(input) {
+        if (this.store) {
+            return this.store.listMessages({
+                inbox: input.inbox,
+                limit: input.limit,
+                offset: input.offset,
+                unreadOnly: input.unread_only,
+                from: input.from,
+                to: input.to,
+                subject: input.subject,
+            });
+        }
+        return this.get(`/v1/inboxes/${encodeURIComponent(input.inbox)}/messages`, {
+            limit: input.limit,
+            offset: input.offset,
+            // The server reads the native \Seen flag; `unread=true` keeps only unread.
+            unread: input.unread_only ? "true" : undefined,
+            from: input.from,
+            to: input.to,
+            subject: input.subject,
+        });
+    }
+    /** Fetch a single message by its opaque id (`GET /v1/messages/{id}`). */
+    async getMessage(id) {
+        if (this.store)
+            return this.store.getMessage(id);
+        return this.get(`/v1/messages/${encodeURIComponent(id)}`);
+    }
+    /**
+     * List a message's attachment metadata
+     * (`GET /v1/inboxes/{inbox_id}/messages/{id}/attachments` → `Page<Attachment>`).
+     */
+    async listAttachments(input) {
+        if (this.store)
+            return this.store.listAttachments(input.message_id);
+        return this.get(`/v1/inboxes/${encodeURIComponent(input.inbox)}/messages/${encodeURIComponent(input.message_id)}/attachments`);
+    }
+    /**
+     * 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."
+     */
+    async getAttachment(input) {
+        if (this.store)
+            return this.store.getAttachment(input.message_id, input.attachment_id);
+        return this.getBinary(`/v1/inboxes/${encodeURIComponent(input.inbox)}/messages/${encodeURIComponent(input.message_id)}/attachments/${encodeURIComponent(input.attachment_id)}`);
+    }
+    /**
+     * 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.
+     */
+    async markRead(input) {
+        if (this.store)
+            return this.store.markRead(input.id, input.read);
+        return this.request("PATCH", `/v1/inboxes/${encodeURIComponent(input.inbox)}/messages/${encodeURIComponent(input.id)}`, { read: input.read });
+    }
+    async listThreads(input) {
+        if (this.store)
+            return this.store.listThreads(input);
+        return this.get(`/v1/inboxes/${encodeURIComponent(input.inbox)}/threads`, {
+            limit: input.limit,
+        });
+    }
+    /**
+     * Fetch one thread (with its messages, oldest-first) by stable id, scoped to
+     * the owning inbox: `GET /v1/inboxes/{inbox_id}/threads/{id}`.
+     */
+    async getThread(input) {
+        if (this.store)
+            return this.store.getThread(input.inbox, input.thread_id);
+        return this.get(`/v1/inboxes/${encodeURIComponent(input.inbox)}/threads/${encodeURIComponent(input.thread_id)}`);
+    }
+    /**
+     * 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.
+     */
+    async deleteMessage(input) {
+        if (this.store)
+            return this.store.deleteMessage(input.inbox, input.id, input.expunge ?? false);
+        const q = input.expunge ? "?expunge=true" : "";
+        return this.del(`/v1/inboxes/${encodeURIComponent(input.inbox)}/messages/${encodeURIComponent(input.id)}${q}`);
+    }
+    /**
+     * Delete an entire thread (every message): move to Trash, or expunge when
+     * `expunge` is set (`DELETE /v1/inboxes/{inbox_id}/threads/{id}?expunge=`).
+     */
+    async deleteThread(input) {
+        if (this.store)
+            return this.store.deleteThread(input.inbox, input.thread_id, input.expunge ?? false);
+        const q = input.expunge ? "?expunge=true" : "";
+        return this.del(`/v1/inboxes/${encodeURIComponent(input.inbox)}/threads/${encodeURIComponent(input.thread_id)}${q}`);
+    }
+    /**
+     * 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.
+     */
+    async batchUpdateMessages(input) {
+        if (this.store)
+            return this.store.batchUpdateMessages(input.inbox, input.ids, input.read, input.folder);
+        const body = { ids: input.ids };
+        if (input.read !== undefined)
+            body.read = input.read;
+        if (input.folder !== undefined)
+            body.folder = input.folder;
+        return this.request("PATCH", `/v1/inboxes/${encodeURIComponent(input.inbox)}/messages/batch`, body);
+    }
+    /**
+     * 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).
+     */
+    async search(input) {
+        if (this.store)
+            return this.store.search(input);
+        const limit = input.limit ?? 20;
+        if (input.inbox) {
+            return this.get(`/v1/inboxes/${encodeURIComponent(input.inbox)}/messages/search`, { q: input.query, limit });
+        }
+        // No inbox specified: fan out across the agent's inboxes and merge.
+        const inboxes = await this.listInboxes(100);
+        const merged = [];
+        for (const ibx of inboxes.items) {
+            const page = await this.get(`/v1/inboxes/${encodeURIComponent(ibx.address)}/messages/search`, { q: input.query, limit });
+            merged.push(...page.items);
+        }
+        merged.sort((a, b) => b.date.localeCompare(a.date));
+        const items = merged.slice(0, limit);
+        return { items, total: merged.length };
+    }
+    // ---- wait_for_email (POST /v1/wait) -----------------------------------
+    async waitForEmail(input) {
+        if (this.store) {
+            return this.store.waitForEmail({
+                inbox: input.inbox,
+                from: input.from,
+                subject: input.subject,
+                regex: input.regex,
+                linkHint: input.link_hint,
+                timeoutMs: input.timeout_ms,
+            });
+        }
+        // The server blocks (IMAP poll) up to timeout_seconds; give the HTTP read a
+        // margin over it so the server, not the client, decides the no-match timeout.
+        // Field names are the canonical API ones: `match` (regex), `since_now`,
+        // `timeout_seconds`.
+        const started = Date.now();
+        const timeoutSeconds = Math.ceil(input.timeout_ms / 1000);
+        const wire = await this.post(`/v1/inboxes/${encodeURIComponent(input.inbox)}/wait`, {
+            from: input.from,
+            subject: input.subject,
+            match: input.regex,
+            link_hint: input.link_hint,
+            since_now: input.since_now,
+            timeout_seconds: timeoutSeconds,
+        }, input.timeout_ms + 5_000);
+        // Translate the canonical wire shape into the MCP tool's result shape.
+        const result = {
+            matched: !wire.timed_out,
+            waited_ms: Date.now() - started,
+        };
+        if (wire.message)
+            result.message = wire.message;
+        if (wire.extracted?.otp)
+            result.otp_code = wire.extracted.otp;
+        if (wire.extracted?.link)
+            result.verification_link = wire.extracted.link;
+        return result;
+    }
+    // ---- webhooks (CRUD; spec §6/§14) -------------------------------------
+    /**
+     * 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.
+     */
+    async registerWebhook(input) {
+        if (this.store) {
+            return this.store.registerWebhook({
+                url: input.url,
+                events: input.events,
+                inbox: input.inbox,
+                clientId: input.client_id,
+            });
+        }
+        return this.post("/v1/webhooks", {
+            url: input.url,
+            events: input.events,
+            inbox: input.inbox,
+            client_id: input.client_id,
+        }, undefined, idempotencyHeader(input.client_id));
+    }
+    /** List registered webhooks (`GET /v1/webhooks`); secrets are redacted. */
+    async listWebhooks() {
+        if (this.store)
+            return this.store.listWebhooks();
+        return this.get("/v1/webhooks");
+    }
+    /** Get one webhook by id (`GET /v1/webhooks/{id}`); secret redacted. */
+    async getWebhook(id) {
+        if (this.store)
+            return this.store.getWebhook(id);
+        return this.get(`/v1/webhooks/${encodeURIComponent(id)}`);
+    }
+    /**
+     * 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.
+     */
+    async updateWebhook(id, input) {
+        if (this.store)
+            return this.store.updateWebhook(id, input);
+        const body = {};
+        if (input.url !== undefined)
+            body.url = input.url;
+        if (input.events !== undefined)
+            body.events = input.events;
+        if (input.inbox !== undefined)
+            body.inbox = input.inbox;
+        if (input.active !== undefined)
+            body.active = input.active;
+        return this.patch(`/v1/webhooks/${encodeURIComponent(id)}`, body);
+    }
+    /** Delete a webhook by id (`DELETE /v1/webhooks/{id}`). */
+    async deleteWebhook(id) {
+        if (this.store)
+            return this.store.deleteWebhook(id);
+        await this.del(`/v1/webhooks/${encodeURIComponent(id)}`);
+        return { id, deleted: true };
+    }
+    // ---- contact allow/block lists (Slice 3) ------------------------------
+    /**
+     * 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).
+     */
+    async addContactListEntry(input) {
+        if (this.store) {
+            return this.store.addContactListEntry(input.inbox, {
+                kind: input.kind,
+                direction: input.direction,
+                pattern: input.pattern,
+            });
+        }
+        return this.post(`/v1/inboxes/${encodeURIComponent(input.inbox)}/lists`, {
+            kind: input.kind,
+            direction: input.direction,
+            pattern: input.pattern,
+        });
+    }
+    /** List the contact-list entries governing an inbox (`GET /v1/inboxes/{inbox_id}/lists`). */
+    async listContactListEntries(inbox) {
+        if (this.store)
+            return this.store.listContactListEntries(inbox);
+        return this.get(`/v1/inboxes/${encodeURIComponent(inbox)}/lists`);
+    }
+    /** Delete a contact-list entry by id (`DELETE /v1/inboxes/{inbox_id}/lists/{id}`). */
+    async deleteContactListEntry(inbox, id) {
+        if (this.store)
+            return this.store.deleteContactListEntry(inbox, id);
+        await this.del(`/v1/inboxes/${encodeURIComponent(inbox)}/lists/${encodeURIComponent(id)}`);
+        return { id, deleted: true };
+    }
+    // ---- domains (Slice 5; privileged, domain:manage scope) ---------------
+    /** List the customer's onboarded domains (`GET /v1/domains`). Canonical page envelope. */
+    async listDomains() {
+        if (this.store)
+            return this.store.listDomains();
+        return this.get("/v1/domains");
+    }
+    /** Get one domain's detail + verification status + the DNS records to set (`GET /v1/domains/{domain}`). */
+    async getDomain(domain) {
+        if (this.store)
+            return this.store.getDomain(domain);
+        return this.get(`/v1/domains/${encodeURIComponent(domain)}`);
+    }
+    /** Onboard/add a domain for the customer (`POST /v1/domains`). */
+    async onboardDomain(input) {
+        if (this.store)
+            return this.store.onboardDomain(input);
+        const body = { domain: input.domain };
+        if (input.mode !== undefined)
+            body.mode = input.mode;
+        if (input.mail_host_ip !== undefined)
+            body.mail_host_ip = input.mail_host_ip;
+        if (input.scope !== undefined)
+            body.scope = input.scope;
+        if (input.project_id !== undefined)
+            body.project_id = input.project_id;
+        return this.post("/v1/domains", body);
+    }
+    /** Trigger/refresh verification for a domain (`POST /v1/domains/{domain}/verify`). */
+    async verifyDomain(domain) {
+        if (this.store)
+            return this.store.verifyDomain(domain);
+        return this.post(`/v1/domains/${encodeURIComponent(domain)}/verify`);
+    }
+    /**
+     * 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.
+     */
+    async offboardDomain(domain) {
+        if (this.store)
+            return this.store.offboardDomain(domain);
+        const res = await this.del(`/v1/domains/${encodeURIComponent(domain)}`);
+        const jobId = res?.job_id ?? "";
+        return {
+            domain,
+            job_id: jobId,
+            status: res?.status ?? "queued",
+            status_url: res?.status_url ?? (jobId ? `/v1/jobs/${jobId}` : ""),
+        };
+    }
+    /**
+     * 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.
+     */
+    async getJob(jobId) {
+        if (this.store)
+            return this.store.getJob(jobId);
+        return this.get(`/v1/jobs/${encodeURIComponent(jobId)}`);
+    }
+    // ---- suppressions (recipient opt-outs / list-unsubscribe) -------------
+    /**
+     * 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.
+     */
+    async precheckSuppression(recipient) {
+        if (this.store)
+            return this.store.precheckSuppression(recipient);
+        // The `recipient` query param routes the server to the pre-check shape.
+        return this.get("/v1/suppressions", { recipient });
+    }
+    /**
+     * 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.
+     */
+    async listSuppressions(input = {}) {
+        if (this.store)
+            return this.store.listSuppressions(input);
+        const query = {};
+        if (input.scope)
+            query.scope = input.scope;
+        if (input.include_revoked)
+            query.include_revoked = "true";
+        if (input.limit !== undefined)
+            query.limit = input.limit;
+        if (input.cursor !== undefined)
+            query.cursor = input.cursor;
+        return this.get("/v1/suppressions", query);
+    }
+    /**
+     * 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.
+     */
+    async revokeSuppression(id, reason) {
+        if (this.store)
+            return this.store.revokeSuppression(id, reason);
+        return this.post(`/v1/suppressions/${encodeURIComponent(id)}/revoke`, {
+            reason,
+        });
+    }
+    // ---- reputation / deliverability (diverse-smtp M7) --------------------
+    /**
+     * 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.
+     */
+    async getReputation() {
+        if (this.store)
+            return this.store.getReputation();
+        return this.get("/v1/reputation");
+    }
+    /**
+     * List the caller's org deliverability findings (`GET /v1/reputation/findings`),
+     * newest-first, with optional status/severity/domain/sender filters. Read-only.
+     */
+    async listDeliverabilityFindings(input = {}) {
+        if (this.store)
+            return this.store.listDeliverabilityFindings(input);
+        const query = {};
+        if (input.status)
+            query.status = input.status;
+        if (input.severity)
+            query.severity = input.severity;
+        if (input.domain)
+            query.domain = input.domain;
+        if (input.sender)
+            query.sender = input.sender;
+        if (input.limit !== undefined)
+            query.limit = input.limit;
+        if (input.cursor !== undefined)
+            query.cursor = input.cursor;
+        return this.get("/v1/reputation/findings", query);
+    }
+    // ---- low-level HTTP ---------------------------------------------------
+    async get(path, query) {
+        return this.request("GET", path, undefined, query);
+    }
+    /**
+     * 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.
+     */
+    async getBinary(path) {
+        const url = new URL(this.config.apiBaseUrl + path);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
+        const headers = { "User-Agent": "extrovert-mcp/0.1.0" };
+        if (this.apiKey)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        let res;
+        try {
+            res = await fetch(url, { method: "GET", headers, signal: controller.signal });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new ExtrovertApiError(`Request to GET ${path} failed: ${reason}`, 0, "network_error");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            const raw = await res.text();
+            const parsed = raw ? safeJsonParse(raw) : undefined;
+            throw errorFromBody(res.status, res.statusText, parsed);
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        return {
+            filename: filenameFromDisposition(res.headers.get("content-disposition") ?? ""),
+            content_type: res.headers.get("content-type") ?? "application/octet-stream",
+            content_base64: bytesToBase64(bytes),
+        };
+    }
+    async post(path, body, timeoutMs, extraHeaders) {
+        return this.request("POST", path, body, undefined, timeoutMs, extraHeaders);
+    }
+    async del(path) {
+        return this.request("DELETE", path);
+    }
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    async put(path, body) {
+        return this.request("PUT", path, body);
+    }
+    async request(method, path, body, query, timeoutMs, extraHeaders) {
+        const url = new URL(this.config.apiBaseUrl + path);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs ?? this.config.requestTimeoutMs);
+        const headers = {
+            Accept: "application/json",
+            "User-Agent": "extrovert-mcp/0.1.0",
+        };
+        if (this.apiKey)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (extraHeaders) {
+            for (const [k, v] of Object.entries(extraHeaders)) {
+                if (v)
+                    headers[k] = v;
+            }
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new ExtrovertApiError(`Request to ${method} ${path} failed: ${reason}`, 0, "network_error");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const raw = await res.text();
+        const parsed = raw ? safeJsonParse(raw) : undefined;
+        if (!res.ok) {
+            throw errorFromBody(res.status, res.statusText, parsed);
+        }
+        return parsed;
+    }
+    setSessionKey(key) {
+        const trimmed = key?.trim();
+        if (trimmed)
+            this.apiKey = trimmed;
+    }
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Build an {@link ExtrovertApiError} from a non-2xx response body, supporting BOTH
+ * error shapes the redesigned API can return:
+ *  - RFC-9457 problem+json (the END STATE, served as application/problem+json):
+ *    `{type, title, status, detail, code, request_id, errors[]}`. `code` is the
+ *    closed machine enum clients switch on (e.g. `forbidden_scope`,
+ *    `breadth_required`, `idempotency_conflict`); the message prefers `detail`,
+ *    then `title`.
+ *  - the legacy `{error, message}` envelope (back-compat during migration): `error`
+ *    is the machine code, `message` the human detail.
+ * The opaque `request_id` (when present) is appended so an agent can quote it for
+ * support. `code` always reaches {@link ExtrovertApiError.code} so the MCP tool
+ * error text surfaces the machine code.
+ *
+ * `errors[]` is carried through VERBATIM onto the error. The server puts the full
+ * human remediation in `detail` precisely because this surface renders `err.message`
+ * — but the machine duplicate in `errors[]` is what makes a 422 `intent_required`
+ * or a 409 `stale` recoverable in ONE turn (the exact JSON to add; the current
+ * revision to re-CAS against; the verbs that ARE legal). Dropping it on the floor
+ * here is why the remediation never reached the model.
+ */
+function errorFromBody(status, statusText, parsed) {
+    const body = (parsed && typeof parsed === "object" ? parsed : undefined);
+    // problem+json carries detail/title; the legacy envelope carries message/error.
+    const message = body?.detail ??
+        body?.message ??
+        body?.title ??
+        body?.error ??
+        `${status} ${statusText}`;
+    // The machine code: problem+json `code`, else the legacy `error` code.
+    const code = body?.code ?? body?.error;
+    const withReqId = body?.request_id ? `${message} (request_id: ${body.request_id})` : message;
+    return new ExtrovertApiError(withReqId, status, code, parsed, problemFieldsOf(body?.errors));
+}
+/**
+ * Narrow an untrusted `problem.errors` value to the `{field, code, detail}` hints.
+ * Anything that is not an array of objects with string `field` + `code` is dropped
+ * rather than rendered: a malformed hint must never turn a useful error message
+ * into `[object Object]`.
+ */
+function problemFieldsOf(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const fields = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        if (typeof e.field !== "string" || typeof e.code !== "string")
+            continue;
+        fields.push({
+            field: e.field,
+            code: e.code,
+            detail: typeof e.detail === "string" ? e.detail : undefined,
+        });
+    }
+    return fields.length ? fields : undefined;
+}
+/**
+ * Build the `Idempotency-Key` header map for a client-supplied key, or undefined
+ * when none was provided. The same key name is used across Go + MCP + SDK; a
+ * mismatch silently breaks server-side dedup.
+ */
+function idempotencyHeader(clientId) {
+    const key = clientId?.trim();
+    return key ? { "Idempotency-Key": key } : undefined;
+}
+/** Runtime-agnostic base64 of a byte array (no Buffer dependency). */
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    if (typeof btoa === "function")
+        return btoa(binary);
+    const g = globalThis;
+    if (g.Buffer)
+        return g.Buffer.from(binary, "binary").toString("base64");
+    throw new Error("No base64 encoder available in this runtime.");
+}
+/** Pull a filename out of a Content-Disposition header value. */
+function filenameFromDisposition(disposition) {
+    const m = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(disposition);
+    return m ? decodeURIComponent(m[1].trim()) : "";
+}
+export { NotFoundError };
+//# sourceMappingURL=client.js.map