@jclvsh/iris 0.22.0 → 0.23.0

package/README.md

@@ -19,6 +19,8 @@ Or run one-shot without installing:
 npx -y -p @jclvsh/iris iris-mcp
 ```
 
+Imported as a library, the package resolves only through its `exports` map (`.`, `./hosted`, `./tool-policy`, `./policy`, `./package.json`); deep imports of `dist/*` are not supported.
+
 ## CLI
 
 ```bash

package/dist/client.d.ts

@@ -1,11 +1,31 @@
+export interface IrisClientOptions {
+    /** API key to send. Defaults to the IRIS_API_KEY environment variable. */
+    apiKey?: string;
+    /** REST base URL. Defaults to IRIS_API_URL, then https://api.iris-ai.dev. */
+    baseUrl?: string;
+}
 export declare class IrisClient {
     private apiKey;
     private baseUrl;
-    constructor();
+    /** True when the base URL was injected; the network-error hint then names no URL or env var. */
+    private hasInjectedBaseUrl;
+    constructor(options?: IrisClientOptions);
     get<T>(path: string, params?: Record<string, string>): Promise<T>;
     post<T>(path: string, body?: unknown): Promise<T>;
     patch<T>(path: string, body: unknown): Promise<T>;
     delete(path: string): Promise<void>;
+    /**
+     * POST with an Idempotency-Key. The API answers a repeat of the same key within 24 hours
+     * with the original response and `Idempotent-Replayed: true`; `replayed` surfaces that so
+     * the caller can say "nothing new was created".
+     */
+    postIdempotent<T>(path: string, body: unknown, idempotencyKey: string): Promise<{
+        result: T;
+        replayed: boolean;
+    }>;
     private request;
+    /** Read a JSON body; a timeout while the body streams gets the same message as one during fetch. */
+    private readJson;
+    private send;
     private handleError;
 }

package/dist/client.js

@@ -30,23 +30,28 @@ function safeStringify(value) {
 export class IrisClient {
     apiKey;
     baseUrl;
-    constructor() {
-        const apiKey = process.env.IRIS_API_KEY;
+    /** True when the base URL was injected; the network-error hint then names no URL or env var. */
+    hasInjectedBaseUrl;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? process.env.IRIS_API_KEY;
         if (!apiKey) {
             throw new Error("IRIS_API_KEY environment variable is required. " +
                 "Get your API key from https://iris-ai.dev/settings/api-keys");
         }
         if (!apiKey.startsWith("is_live_")) {
-            throw new Error("IRIS_API_KEY must start with 'is_live_'. " +
+            // An injected key came from a hosted caller, who never set the env var.
+            const subject = options.apiKey !== undefined ? "api key" : "IRIS_API_KEY";
+            throw new Error(`${subject} must start with 'is_live_'. ` +
                 "Get a valid API key from https://iris-ai.dev/settings/api-keys");
         }
         this.apiKey = apiKey;
+        this.hasInjectedBaseUrl = Boolean(options.baseUrl);
         // Default to api.iris-ai.dev (Stripe/GitHub/OpenAI convention). The api host
         // rewrites /<resource> → /api/v1/<resource> via middleware (see iris/src/proxy.ts),
         // so callers no longer pass the /api/v1/ prefix. Override via IRIS_API_URL if needed.
         // Older versions (≤0.5.5) defaulted to https://www.iris-ai.dev/api/v1 — that host
         // still responds, but the api host is canonical going forward.
-        this.baseUrl = (process.env.IRIS_API_URL || "https://api.iris-ai.dev").replace(/\/+$/, "");
+        this.baseUrl = (options.baseUrl || process.env.IRIS_API_URL || "https://api.iris-ai.dev").replace(/\/+$/, "");
     }
     async get(path, params) {
         const url = new URL(`${this.baseUrl}${path}`);
@@ -76,33 +81,68 @@ export class IrisClient {
     async delete(path) {
         await this.request(`${this.baseUrl}${path}`, { method: "DELETE" });
     }
+    /**
+     * POST with an Idempotency-Key. The API answers a repeat of the same key within 24 hours
+     * with the original response and `Idempotent-Replayed: true`; `replayed` surfaces that so
+     * the caller can say "nothing new was created".
+     */
+    async postIdempotent(path, body, idempotencyKey) {
+        const response = await this.send(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
+            body: JSON.stringify(body),
+        });
+        return {
+            result: await this.readJson(response),
+            replayed: response.headers.get("Idempotent-Replayed") === "true",
+        };
+    }
     async request(url, init) {
+        const response = await this.send(url, init);
+        if (response.status === 204) {
+            return undefined;
+        }
+        return this.readJson(response);
+    }
+    /** Read a JSON body; a timeout while the body streams gets the same message as one during fetch. */
+    async readJson(response) {
+        try {
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error("request timed out after 30 seconds");
+            }
+            throw error;
+        }
+    }
+    async send(url, init) {
+        let response;
         try {
-            const response = await fetch(url, {
+            response = await fetch(url, {
                 ...init,
                 headers: {
-                    ...init.headers,
+                    ...(init.headers || {}),
                     Authorization: `Bearer ${this.apiKey}`,
                 },
                 signal: AbortSignal.timeout(30_000),
             });
-            if (!response.ok && response.status !== 204) {
-                await this.handleError(response);
-            }
-            if (response.status === 204) {
-                return undefined;
-            }
-            return (await response.json());
         }
         catch (error) {
             if (error instanceof Error && error.name === "TimeoutError") {
                 throw new Error("request timed out after 30 seconds");
             }
             if (error instanceof TypeError) {
-                throw new Error(`network error: ${error.message}`);
+                throw new Error(this.hasInjectedBaseUrl
+                    ? `network error reaching the api: ${error.message}`
+                    : `network error: ${error.message}. check IRIS_API_URL and your connection`);
             }
             throw error;
         }
+        if (!response.ok) {
+            await this.handleError(response);
+        }
+        return response;
     }
     async handleError(response) {
         let message;

package/dist/commands/campaigns.js

@@ -110,7 +110,7 @@ export function registerCampaignCommands(program, client) {
     });
     campaigns
         .command("analyze <id>")
-        .description("run AI analysis on a campaign to generate target profiles")
+        .description("queue AI analysis of a campaign to generate target profiles (from its product, or from its goal)")
         .action(async (id) => {
         try {
             const result = await client.post(`/campaigns/${id}/analyze`);

package/dist/hosted-transport.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Serve one MCP request over HTTP. LOCKSTEP across every apps/<app>/packages/mcp.
+ *
+ * Stateless: a fresh transport per request, no sessions, JSON responses - so it runs on
+ * serverless functions where consecutive requests from one client can land on different
+ * instances. Only POST is meaningful; the host must not route GET here (a stateless GET
+ * opens an event stream that never ends).
+ */
+export declare function serveStatelessMcp(server: McpServer, request: Request): Promise<Response>;

package/dist/hosted-transport.js

@@ -0,0 +1,17 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+/**
+ * Serve one MCP request over HTTP. LOCKSTEP across every apps/<app>/packages/mcp.
+ *
+ * Stateless: a fresh transport per request, no sessions, JSON responses - so it runs on
+ * serverless functions where consecutive requests from one client can land on different
+ * instances. Only POST is meaningful; the host must not route GET here (a stateless GET
+ * opens an event stream that never ends).
+ */
+export async function serveStatelessMcp(server, request) {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    await server.connect(transport);
+    return transport.handleRequest(request);
+}

package/dist/hosted.d.ts

@@ -0,0 +1,10 @@
+export interface HostedMcpOptions {
+    /** The caller's iris API key. The host authenticates it before calling in. */
+    apiKey: string;
+    /** REST base URL the tools call, e.g. https://api.iris-ai.dev */
+    baseUrl: string;
+    /** Reported as serverInfo.version */
+    version: string;
+}
+/** One hosted MCP request: a per-request client and server over the stateless transport. */
+export declare function handleHostedMcpRequest(request: Request, options: HostedMcpOptions): Promise<Response>;

package/dist/hosted.js

@@ -0,0 +1,9 @@
+import { IrisClient } from "./client.js";
+import { serveStatelessMcp } from "./hosted-transport.js";
+import { createIrisServer } from "./server.js";
+/** One hosted MCP request: a per-request client and server over the stateless transport. */
+export function handleHostedMcpRequest(request, options) {
+    const client = new IrisClient({ apiKey: options.apiKey, baseUrl: options.baseUrl });
+    const server = createIrisServer({ client, version: options.version, profile: "hosted" });
+    return serveStatelessMcp(server, request);
+}

package/dist/idempotency.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A content-derived Idempotency-Key for create calls.
+ *
+ * The REST API dedupes a request that repeats a key within 24 hours (per key + endpoint)
+ * and answers with the original response plus `Idempotent-Replayed: true`. Deriving the
+ * key from the arguments means a retry after a timeout - by an agent, or by a person
+ * pressing "try again" in an MCP client - returns the record that was already created
+ * instead of creating a second one.
+ */
+export declare function contentIdempotencyKey(args: unknown): Promise<string>;

package/dist/idempotency.js

@@ -0,0 +1,28 @@
+/**
+ * A content-derived Idempotency-Key for create calls.
+ *
+ * The REST API dedupes a request that repeats a key within 24 hours (per key + endpoint)
+ * and answers with the original response plus `Idempotent-Replayed: true`. Deriving the
+ * key from the arguments means a retry after a timeout - by an agent, or by a person
+ * pressing "try again" in an MCP client - returns the record that was already created
+ * instead of creating a second one.
+ */
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value !== null && typeof value === "object") {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            if (source[key] !== undefined)
+                sorted[key] = stable(source[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+export async function contentIdempotencyKey(args) {
+    const bytes = new TextEncoder().encode(JSON.stringify(stable(args)));
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/index.js

@@ -1,31 +1,10 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { IrisClient } from "./client.js";
-import { registerCampaignTools } from "./tools/campaigns.js";
-import { registerContactTools } from "./tools/contacts.js";
-import { registerConversationTools } from "./tools/conversations.js";
-import { registerMessageTools } from "./tools/messages.js";
-import { registerAiTools } from "./tools/ai.js";
-import { registerDiscoveryTools } from "./tools/discovery.js";
-import { registerAnalyticsTools } from "./tools/analytics.js";
-import { registerBillingTools } from "./tools/billing.js";
-import { registerChannelTools } from "./tools/channels.js";
-import { registerNotificationTools } from "./tools/notifications.js";
-import { registerKeyTools } from "./tools/keys.js";
-import { registerWebhookTools } from "./tools/webhooks.js";
-import { registerAgentCreditTools } from "./tools/agent-credits.js";
-import { registerUsageTools } from "./tools/usage.js";
-import { registerAutopilotTools } from "./tools/autopilot.js";
-import { registerResponderTools } from "./tools/responder.js";
-import { registerAudienceTools } from "./tools/audiences.js";
+import { createIrisServer } from "./server.js";
 const requireFromHere = createRequire(import.meta.url);
 const pkg = requireFromHere("../package.json");
-const server = new McpServer({
-    name: "iris",
-    version: pkg.version,
-});
 // Lazy client: defer the IrisClient constructor (which throws when
 // IRIS_API_KEY is missing) until a tool invocation actually issues an HTTP call.
 // MCP discovery (initialize, tools/list) never touches the proxy, so the server
@@ -40,22 +19,6 @@ const client = new Proxy({}, {
         return typeof value === "function" ? value.bind(realClient) : value;
     },
 });
-registerCampaignTools(server, client);
-registerContactTools(server, client);
-registerConversationTools(server, client);
-registerMessageTools(server, client);
-registerAiTools(server, client);
-registerDiscoveryTools(server, client);
-registerAnalyticsTools(server, client);
-registerBillingTools(server, client);
-registerChannelTools(server, client);
-registerNotificationTools(server, client);
-registerKeyTools(server, client);
-registerWebhookTools(server, client);
-registerAgentCreditTools(server, client);
-registerUsageTools(server, client);
-registerAutopilotTools(server, client);
-registerResponderTools(server, client);
-registerAudienceTools(server, client);
+const server = createIrisServer({ client, version: pkg.version, profile: "full" });
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/policy.d.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Generic tool-policy machinery. LOCKSTEP across every apps/<app>/packages/mcp
+ * (byte-identical; scripts/check-lockstep-identity.sh enforces it). The per-app
+ * table lives in tool-policy.ts next to this file.
+ *
+ * class:
+ *   read      - retrieves information; changes nothing.
+ *   write     - changes the app's own data, reversibly; nothing leaves the app.
+ *   sensitive - publishes, sends, or deletes on an external platform, deletes a record
+ *               with no user-facing restore, spends money, handles credentials, or
+ *               switches on automatic sending or posting.
+ * hosted: whether the app's hosted endpoint (api.<brand>/mcp) serves the tool.
+ * category: the documentation grouping every docs count is computed from.
+ */
+export type ToolClass = "read" | "write" | "sensitive";
+export type ToolProfile = "full" | "hosted";
+export interface ToolPolicy<Category extends string = string> {
+    class: ToolClass;
+    hosted: boolean;
+    category: Category;
+}
+export type PolicyTable<Category extends string = string> = Record<string, ToolPolicy<Category>>;
+export declare function toolPolicyFor<C extends string>(table: PolicyTable<C>, name: string): ToolPolicy<C>;
+export declare function isToolEnabledIn<C extends string>(table: PolicyTable<C>, name: string, profile: ToolProfile): boolean;
+export declare function toolAnnotationsFor<C extends string>(table: PolicyTable<C>, name: string): {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+};
+/** Tool names in a category, in table order. */
+export declare function toolsInCategoryOf<C extends string>(table: PolicyTable<C>, category: C): string[];
+/**
+ * A stand-in for McpServer that every register*Tools(server, client) function can be
+ * handed. It is the one place a tool is filtered by profile and given its annotations.
+ */
+export declare function createPolicyRegistrar<C extends string>(server: McpServer, table: PolicyTable<C>, profile: ToolProfile): McpServer;

package/dist/policy.js

@@ -0,0 +1,33 @@
+export function toolPolicyFor(table, name) {
+    const policy = table[name];
+    if (!policy) {
+        throw new Error(`tool "${name}" has no entry in tool-policy.ts - classify it before registering`);
+    }
+    return policy;
+}
+export function isToolEnabledIn(table, name, profile) {
+    const { hosted } = toolPolicyFor(table, name);
+    return profile === "full" || hosted;
+}
+export function toolAnnotationsFor(table, name) {
+    const toolClass = toolPolicyFor(table, name).class;
+    return { readOnlyHint: toolClass === "read", destructiveHint: toolClass === "sensitive" };
+}
+/** Tool names in a category, in table order. */
+export function toolsInCategoryOf(table, category) {
+    return Object.keys(table).filter((name) => table[name].category === category);
+}
+/**
+ * A stand-in for McpServer that every register*Tools(server, client) function can be
+ * handed. It is the one place a tool is filtered by profile and given its annotations.
+ */
+export function createPolicyRegistrar(server, table, profile) {
+    const registerAnnotated = server.tool.bind(server);
+    return {
+        tool(name, description, schema, handler) {
+            if (!isToolEnabledIn(table, name, profile))
+                return;
+            registerAnnotated(name, description, schema, toolAnnotationsFor(table, name), handler);
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IrisClient } from "./client.js";
+import { type ToolProfile } from "./policy.js";
+export interface CreateIrisServerOptions {
+    client: IrisClient;
+    version: string;
+    /** "full" serves every tool (stdio). "hosted" serves the tools marked hosted in tool-policy.ts. */
+    profile: ToolProfile;
+}
+export declare function createIrisServer({ client, version, profile }: CreateIrisServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,42 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createPolicyRegistrar } from "./policy.js";
+import { TOOL_POLICY } from "./tool-policy.js";
+import { registerCampaignTools } from "./tools/campaigns.js";
+import { registerContactTools } from "./tools/contacts.js";
+import { registerConversationTools } from "./tools/conversations.js";
+import { registerMessageTools } from "./tools/messages.js";
+import { registerAiTools } from "./tools/ai.js";
+import { registerDiscoveryTools } from "./tools/discovery.js";
+import { registerAnalyticsTools } from "./tools/analytics.js";
+import { registerBillingTools } from "./tools/billing.js";
+import { registerChannelTools } from "./tools/channels.js";
+import { registerNotificationTools } from "./tools/notifications.js";
+import { registerKeyTools } from "./tools/keys.js";
+import { registerWebhookTools } from "./tools/webhooks.js";
+import { registerAgentCreditTools } from "./tools/agent-credits.js";
+import { registerUsageTools } from "./tools/usage.js";
+import { registerAutopilotTools } from "./tools/autopilot.js";
+import { registerResponderTools } from "./tools/responder.js";
+import { registerAudienceTools } from "./tools/audiences.js";
+export function createIrisServer({ client, version, profile }) {
+    const server = new McpServer({ name: "iris", version });
+    const registrar = createPolicyRegistrar(server, TOOL_POLICY, profile);
+    registerCampaignTools(registrar, client);
+    registerContactTools(registrar, client);
+    registerConversationTools(registrar, client);
+    registerMessageTools(registrar, client);
+    registerAiTools(registrar, client);
+    registerDiscoveryTools(registrar, client);
+    registerAnalyticsTools(registrar, client);
+    registerBillingTools(registrar, client);
+    registerChannelTools(registrar, client);
+    registerNotificationTools(registrar, client);
+    registerKeyTools(registrar, client);
+    registerWebhookTools(registrar, client);
+    registerAgentCreditTools(registrar, client);
+    registerUsageTools(registrar, client);
+    registerAutopilotTools(registrar, client);
+    registerResponderTools(registrar, client);
+    registerAudienceTools(registrar, client);
+    return server;
+}

package/dist/tool-policy.d.ts

@@ -0,0 +1,12 @@
+import { type PolicyTable, type ToolClass, type ToolPolicy, type ToolProfile } from "./policy.js";
+export type { ToolClass, ToolPolicy, ToolProfile };
+export declare const TOOL_CATEGORIES: readonly ["campaigns", "contacts", "conversations", "messages", "channels", "discovery", "audiences", "autopilot", "responder", "ai", "analytics", "notifications", "usage", "billing", "credits", "API keys", "webhooks"];
+export type ToolCategory = (typeof TOOL_CATEGORIES)[number];
+export declare const TOOL_POLICY: PolicyTable<ToolCategory>;
+export declare const toolPolicy: (name: string) => ToolPolicy<"campaigns" | "contacts" | "usage" | "messages" | "conversations" | "discovery" | "ai" | "webhooks" | "notifications" | "analytics" | "billing" | "channels" | "credits" | "responder" | "audiences" | "autopilot" | "API keys">;
+export declare const isToolEnabled: (name: string, profile: ToolProfile) => boolean;
+export declare const toolAnnotations: (name: string) => {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+};
+export declare const toolsInCategory: (category: ToolCategory) => string[];

package/dist/tool-policy.js

@@ -0,0 +1,152 @@
+import { isToolEnabledIn, toolAnnotationsFor, toolPolicyFor, toolsInCategoryOf, } from "./policy.js";
+export const TOOL_CATEGORIES = [
+    "campaigns",
+    "contacts",
+    "conversations",
+    "messages",
+    "channels",
+    "discovery",
+    "audiences",
+    "autopilot",
+    "responder",
+    "ai",
+    "analytics",
+    "notifications",
+    "usage",
+    "billing",
+    "credits",
+    "API keys",
+    "webhooks",
+];
+const hosted = (category, toolClass) => ({
+    class: toolClass,
+    hosted: true,
+    category,
+});
+const localOnly = (category, toolClass) => ({
+    class: toolClass,
+    hosted: false,
+    category,
+});
+export const TOOL_POLICY = {
+    // campaigns
+    list_campaigns: hosted("campaigns", "read"),
+    get_campaign: hosted("campaigns", "read"),
+    list_campaign_contacts: hosted("campaigns", "read"),
+    list_campaign_chats: hosted("campaigns", "read"),
+    get_campaign_chat_messages: hosted("campaigns", "read"),
+    get_campaign_usage: hosted("campaigns", "read"),
+    list_target_profiles: hosted("campaigns", "read"),
+    create_campaign: hosted("campaigns", "write"),
+    update_campaign: hosted("campaigns", "write"),
+    add_campaign_contacts: hosted("campaigns", "write"),
+    rename_campaign_chat: hosted("campaigns", "write"),
+    analyze_campaign: hosted("campaigns", "write"),
+    create_target_profile: hosted("campaigns", "write"),
+    // soft deletes with no user-facing restore
+    delete_campaign: hosted("campaigns", "sensitive"),
+    delete_campaign_chat: hosted("campaigns", "sensitive"),
+    delete_target_profile: hosted("campaigns", "sensitive"),
+    // contacts
+    list_contacts: hosted("contacts", "read"),
+    get_contact: hosted("contacts", "read"),
+    get_contact_handles: hosted("contacts", "read"),
+    get_contact_usage: hosted("contacts", "read"),
+    list_contact_conversations: hosted("contacts", "read"),
+    create_contact: hosted("contacts", "write"),
+    update_contact: hosted("contacts", "write"),
+    bulk_import_contacts: hosted("contacts", "write"),
+    delete_contact: hosted("contacts", "sensitive"),
+    // conversations
+    list_conversations: hosted("conversations", "read"),
+    get_conversation: hosted("conversations", "read"),
+    get_conversation_messages: hosted("conversations", "read"),
+    get_engagement_metrics: hosted("conversations", "read"),
+    create_conversation: hosted("conversations", "write"),
+    mark_conversation_read: hosted("conversations", "write"),
+    update_conversation: hosted("conversations", "write"),
+    // records a message without transmitting it: any status other than pending_approval records it as sent
+    create_conversation_message: hosted("conversations", "sensitive"),
+    // messages
+    list_pending_messages: hosted("messages", "read"),
+    mark_message_sent: hosted("messages", "write"),
+    submit_message_feedback: hosted("messages", "write"),
+    // these send, or discard a draft with no restore
+    approve_message: hosted("messages", "sensitive"),
+    retry_message: hosted("messages", "sensitive"),
+    bulk_message_action: hosted("messages", "sensitive"),
+    reject_message: hosted("messages", "sensitive"),
+    // channels
+    list_connected_accounts: hosted("channels", "read"),
+    check_channel_availability: hosted("channels", "read"),
+    send_channel_message: hosted("channels", "sensitive"),
+    // discovery (spends quota and finds third parties; nothing is sent)
+    get_discovery_job: hosted("discovery", "read"),
+    list_discovery_sources: hosted("discovery", "read"),
+    search_contacts: hosted("discovery", "write"),
+    search_campaign_contacts: hosted("discovery", "write"),
+    // audiences
+    list_audiences: hosted("audiences", "read"),
+    create_audience: hosted("audiences", "write"),
+    generate_audiences: hosted("audiences", "write"),
+    attach_audience_to_campaign: hosted("audiences", "write"),
+    delete_audience: hosted("audiences", "sensitive"),
+    // autopilot (review-only: it drafts and discovers, it never sends)
+    get_autopilot_status: hosted("autopilot", "read"),
+    configure_autopilot: hosted("autopilot", "write"),
+    run_autopilot_now: hosted("autopilot", "write"),
+    // responder (auto-replies and comment-triggered DMs send without a per-message step)
+    get_responder: hosted("responder", "read"),
+    list_responder_activity: hosted("responder", "read"),
+    get_conversation_responder: hosted("responder", "read"),
+    list_responder_comment_triggers: hosted("responder", "read"),
+    list_responder_posts: hosted("responder", "read"),
+    configure_responder: hosted("responder", "sensitive"),
+    set_conversation_responder: hosted("responder", "sensitive"),
+    create_responder_comment_trigger: hosted("responder", "sensitive"),
+    update_responder_comment_trigger: hosted("responder", "sensitive"),
+    delete_responder_comment_trigger: hosted("responder", "sensitive"),
+    // ai
+    get_ai_usage: hosted("ai", "read"),
+    generate_content: hosted("ai", "write"),
+    generate_campaign_content: hosted("ai", "write"),
+    analyze_response: hosted("ai", "write"),
+    // analytics
+    get_analytics_overview: hosted("analytics", "read"),
+    get_campaign_analytics: hosted("analytics", "read"),
+    get_performance_metrics: hosted("analytics", "read"),
+    get_response_time: hosted("analytics", "read"),
+    get_contact_types: hosted("analytics", "read"),
+    // notifications
+    list_notifications: hosted("notifications", "read"),
+    update_notification: hosted("notifications", "write"),
+    mark_all_notifications_read: hosted("notifications", "write"),
+    delete_notification: hosted("notifications", "sensitive"),
+    // usage + billing
+    get_usage: hosted("usage", "read"),
+    get_changelog: hosted("usage", "read"),
+    get_billing_plans: hosted("billing", "read"),
+    // credits (agent payments: never hosted)
+    get_credit_balance: localOnly("credits", "read"),
+    purchase_credit_pack: localOnly("credits", "sensitive"),
+    // api keys (credentials: never hosted)
+    get_current_api_key: localOnly("API keys", "read"),
+    list_api_keys: localOnly("API keys", "read"),
+    rename_api_key: localOnly("API keys", "write"),
+    create_api_key: localOnly("API keys", "sensitive"),
+    revoke_api_key: localOnly("API keys", "sensitive"),
+    rotate_api_key: localOnly("API keys", "sensitive"),
+    // webhooks (developer plumbing: never hosted)
+    list_webhooks: localOnly("webhooks", "read"),
+    get_webhook: localOnly("webhooks", "read"),
+    list_webhook_deliveries: localOnly("webhooks", "read"),
+    create_webhook: localOnly("webhooks", "write"),
+    update_webhook: localOnly("webhooks", "write"),
+    test_webhook: localOnly("webhooks", "write"),
+    delete_webhook: localOnly("webhooks", "sensitive"),
+    rotate_webhook_secret: localOnly("webhooks", "sensitive"),
+};
+export const toolPolicy = (name) => toolPolicyFor(TOOL_POLICY, name);
+export const isToolEnabled = (name, profile) => isToolEnabledIn(TOOL_POLICY, name, profile);
+export const toolAnnotations = (name) => toolAnnotationsFor(TOOL_POLICY, name);
+export const toolsInCategory = (category) => toolsInCategoryOf(TOOL_POLICY, category);

package/dist/tools/campaigns.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatMcpError } from "../cli-utils.js";
+import { contentIdempotencyKey } from "../idempotency.js";
 const CAMPAIGN_STATUSES = ["draft", "active", "paused", "completed", "deleted"];
 const OBJECTIVE_TYPES = ["venue_dj", "venue_host", "product_promotion", "custom"];
 const TARGET_PROFILE_TYPES = [
@@ -46,8 +47,21 @@ export function registerCampaignTools(server, client) {
             .describe("product description (for product_promotion objective)"),
     }, async (args) => {
         try {
-            const result = await client.post("/campaigns", args);
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            // A retry after a timeout (by an agent, or a person pressing "try again") must not
+            // create a second campaign: the key is derived from the arguments, so the API replays
+            // the campaign it already created for them.
+            const { result, replayed } = await client.postIdempotent("/campaigns", args, await contentIdempotencyKey(args));
+            const text = JSON.stringify(result, null, 2);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: replayed
+                            ? `note: an identical campaign was created within the last 24 hours, so iris returned it - no new campaign was created.\n${text}`
+                            : text,
+                    },
+                ],
+            };
         }
         catch (error) {
             return formatMcpError(error);
@@ -193,7 +207,7 @@ export function registerCampaignTools(server, client) {
             return formatMcpError(error);
         }
     });
-    server.tool("analyze_campaign", "trigger AI analysis of a campaign to generate target profiles and recommendations. requires write scope.", {
+    server.tool("analyze_campaign", "queue AI analysis of a campaign to generate its target profiles: from the product for product_promotion campaigns, from goal_description for any other campaign. runs asynchronously; poll get_campaign until analysis_status is completed, then search_campaign_contacts. requires write scope.", {
         id: z.string().uuid().describe("campaign ID"),
     }, async ({ id }) => {
         try {

package/dist/types.d.ts

@@ -33,6 +33,9 @@ export interface Campaign {
     follow_up_enabled: boolean;
     follow_up_max_count: number;
     follow_up_delay_days: number;
+    goal_description?: string | null;
+    analysis_status?: "none" | "pending" | "analyzing" | "completed" | "failed";
+    analysis_error?: string | null;
     created_at: string;
     updated_at: string;
 }
@@ -43,14 +46,15 @@ export interface CampaignWithStats extends Campaign {
     emails_opened?: number;
     emails_replied?: number;
 }
+/** `GET /campaigns/{id}/usage` */
 export interface CampaignUsage {
     campaign_id: string;
-    contacts_count: number;
-    contacts_limit: number;
-    emails_sent: number;
-    emails_limit: number;
-    discovery_runs: number;
-    discovery_limit: number;
+    status: string;
+    total_contacts: number;
+    total_conversations: number;
+    delivery_status: Record<string, number>;
+    /** id of a contact search running for the campaign right now; null when none is */
+    discovery_job_id: string | null;
 }
 /** `POST /campaigns/{id}/contacts` */
 export interface AddCampaignContactsResult {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/iris",
-	"version": "0.22.0",
+	"version": "0.23.0",
 	"description": "MCP server for the Iris API",
 	"repository": {
 		"type": "git",
@@ -10,6 +10,25 @@
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./hosted": {
+			"types": "./dist/hosted.d.ts",
+			"default": "./dist/hosted.js"
+		},
+		"./policy": {
+			"types": "./dist/policy.d.ts",
+			"default": "./dist/policy.js"
+		},
+		"./tool-policy": {
+			"types": "./dist/tool-policy.d.ts",
+			"default": "./dist/tool-policy.js"
+		},
+		"./package.json": "./package.json"
+	},
 	"bin": {
 		"iris-mcp": "dist/index.js",
 		"iris": "dist/cli.js"
@@ -20,17 +39,21 @@
 	],
 	"scripts": {
 		"build": "tsc",
+		"prepare": "tsc",
 		"prepublishOnly": "npm run build",
-		"start": "node dist/index.js"
+		"start": "node dist/index.js",
+		"typecheck": "tsc -p tsconfig.test.json",
+		"test": "vitest run"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.11.0",
+		"@modelcontextprotocol/sdk": "^1.26.0",
 		"commander": "^14.0.3",
 		"zod": "^3.24.0"
 	},
 	"devDependencies": {
+		"@types/node": "^22.0.0",
 		"typescript": "^5.7.0",
-		"@types/node": "^22.0.0"
+		"vitest": "^4.0.18"
 	},
 	"engines": {
 		"node": ">=18"