@jclvsh/iris 0.2.0

package/README.md

@@ -0,0 +1,78 @@
+# @jclvsh/iris
+
+MCP server for the [Iris](https://iris-ai.dev) API — AI-powered messaging assistant for automated multi-channel outreach campaigns.
+
+## Install
+
+```bash
+npx @jclvsh/iris
+```
+
+## Configuration
+
+### Claude Code
+
+Add to your Claude Code settings:
+
+```json
+{
+  "mcpServers": {
+    "iris": {
+      "command": "npx",
+      "args": ["-y", "@jclvsh/iris"],
+      "env": {
+        "IRIS_API_KEY": "is_live_..."
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "iris": {
+      "command": "npx",
+      "args": ["-y", "@jclvsh/iris"],
+      "env": {
+        "IRIS_API_KEY": "is_live_..."
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `IRIS_API_KEY` | Yes | API key (must start with `is_live_`) |
+| `IRIS_API_URL` | No | Base URL (default: `https://iris-ai.dev/api/v1`) |
+
+Get your API key at [iris-ai.dev/settings/api-keys](https://iris-ai.dev/settings/api-keys).
+
+## Available Tools
+
+| Category | Tools |
+|----------|-------|
+| Campaigns | list, create, get, update, delete, contacts, usage, analyze, target profiles |
+| Contacts | list, create, get, update, delete, bulk import, usage, conversations |
+| Conversations | list, get, messages, mark read, engagement metrics |
+| Messages | list pending, approve, reject, retry, feedback, bulk action |
+| AI | generate content, campaign content, analyze response, usage, suggestions |
+| Discovery | search contacts, campaign search, job status, sources |
+| Analytics | overview, campaign analytics, performance, response time, contact types |
+| Billing | plans |
+| Channels | connected accounts, availability, send message |
+| Notifications | list, update, delete, mark all read |
+| API Keys | current key, list, create, revoke |
+| Webhooks | list, create, get, update, delete, test, deliveries |
+| Agent Credits | balance, purchase pack (x402/MPP only) |
+
+## Documentation
+
+Full API documentation: [iris-ai.dev/docs](https://iris-ai.dev/docs)

package/dist/cli-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function formatOutput(data: unknown, format?: string): void;
+export declare function handleError(error: unknown): never;
+export declare function getFormat(opts: Record<string, unknown>): string;
+export declare function parseList(value: string): string[];

package/dist/cli-utils.js

@@ -0,0 +1,31 @@
+export function formatOutput(data, format = "json") {
+    if (format === "table" && typeof data === "object" && data !== null) {
+        const obj = data;
+        if (Array.isArray(obj.data)) {
+            console.table(obj.data);
+            if (obj.pagination) {
+                const p = obj.pagination;
+                console.error(`\npage ${p.page}/${p.total_pages} (${p.total} total)`);
+            }
+            return;
+        }
+        if (obj.data && typeof obj.data === "object") {
+            console.log(JSON.stringify(obj.data, null, 2));
+            return;
+        }
+    }
+    console.log(JSON.stringify(data, null, 2));
+}
+export function handleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`error: ${message}`);
+    process.exit(1);
+}
+export function getFormat(opts) {
+    if (opts.json)
+        return "json";
+    return opts.format || "json";
+}
+export function parseList(value) {
+    return value.split(",").map((s) => s.trim()).filter(Boolean);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { IrisClient } from "./client.js";
+import { handleError } from "./cli-utils.js";
+import { registerCampaignCommands } from "./commands/campaigns.js";
+import { registerContactCommands } from "./commands/contacts.js";
+import { registerMessageCommands } from "./commands/messages.js";
+import { registerConversationCommands } from "./commands/conversations.js";
+import { registerDiscoveryCommands } from "./commands/discovery.js";
+import { registerAICommands } from "./commands/ai.js";
+import { registerKeyCommands } from "./commands/keys.js";
+import { registerWebhookCommands } from "./commands/webhooks.js";
+import { registerNotificationCommands } from "./commands/notifications.js";
+import { registerAnalyticsCommands } from "./commands/analytics.js";
+import { registerBillingCommands } from "./commands/billing.js";
+import { registerChannelCommands } from "./commands/channels.js";
+import { registerCreditCommands } from "./commands/credits.js";
+const program = new Command()
+    .name("iris")
+    .description("iris CLI - manage campaigns, contacts, messages, and outreach")
+    .version("0.2.0")
+    .option("--json", "output as JSON (default)")
+    .option("--format <fmt>", "output format: json, table", "json");
+try {
+    const client = new IrisClient();
+    registerCampaignCommands(program, client);
+    registerContactCommands(program, client);
+    registerMessageCommands(program, client);
+    registerConversationCommands(program, client);
+    registerDiscoveryCommands(program, client);
+    registerAICommands(program, client);
+    registerKeyCommands(program, client);
+    registerWebhookCommands(program, client);
+    registerNotificationCommands(program, client);
+    registerAnalyticsCommands(program, client);
+    registerBillingCommands(program, client);
+    registerChannelCommands(program, client);
+    registerCreditCommands(program, client);
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    handleError(error);
+}

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+export declare class IrisClient {
+    private apiKey;
+    private baseUrl;
+    constructor();
+    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>;
+    private request;
+    private handleError;
+}

package/dist/client.js

@@ -0,0 +1,100 @@
+export class IrisClient {
+    apiKey;
+    baseUrl;
+    constructor() {
+        const 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_'. " +
+                "Get a valid API key from https://iris-ai.dev/settings/api-keys");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (process.env.IRIS_API_URL || "https://iris-ai.dev/api/v1").replace(/\/+$/, "");
+    }
+    async get(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined && value !== "") {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        return this.request(url.toString(), { method: "GET" });
+    }
+    async post(path, body) {
+        return this.request(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async patch(path, body) {
+        return this.request(`${this.baseUrl}${path}`, {
+            method: "PATCH",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    async delete(path) {
+        await this.request(`${this.baseUrl}${path}`, { method: "DELETE" });
+    }
+    async request(url, init) {
+        try {
+            const response = await fetch(url, {
+                ...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 error;
+        }
+    }
+    async handleError(response) {
+        let message;
+        try {
+            const body = await response.json();
+            if (body?.error) {
+                const parts = [body.error.message || "unknown error"];
+                if (body.error.code)
+                    parts.unshift(`[${body.error.code}]`);
+                if (body.error.field)
+                    parts.push(`(field: ${body.error.field})`);
+                message = parts.join(" ");
+            }
+            else {
+                message = `HTTP ${response.status}: ${response.statusText}`;
+            }
+        }
+        catch {
+            message = `HTTP ${response.status}: ${response.statusText}`;
+        }
+        if (response.status === 429) {
+            const retryAfter = response.headers.get("Retry-After");
+            if (retryAfter) {
+                message += ` — retry after ${retryAfter}s`;
+            }
+        }
+        throw new Error(message);
+    }
+}

package/dist/commands/ai.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { IrisClient } from "../client.js";
+export declare function registerAICommands(program: Command, client: IrisClient): void;

package/dist/commands/ai.js

@@ -0,0 +1,97 @@
+import { formatOutput, handleError, getFormat, parseList } from "../cli-utils.js";
+export function registerAICommands(program, client) {
+    const ai = program.command("ai").description("AI content generation and analysis");
+    ai
+        .command("generate")
+        .description("generate AI content (email draft, subject line, etc.)")
+        .requiredOption("-t, --generation-type <type>", "generation type (e.g. email_draft, subject_line)")
+        .requiredOption("--tone <tone>", "tone (e.g. professional, casual, friendly)")
+        .option("--contact-id <id>", "contact ID for personalization")
+        .option("--campaign-id <id>", "campaign ID for context")
+        .option("--prompt <text>", "free-form prompt context")
+        .action(async (opts) => {
+        try {
+            const body = {
+                generation_type: opts.generationType,
+                tone: opts.tone,
+            };
+            if (opts.contactId)
+                body.contact_id = opts.contactId;
+            if (opts.campaignId)
+                body.campaign_id = opts.campaignId;
+            if (opts.prompt)
+                body.prompt = opts.prompt;
+            const result = await client.post("/ai/generate", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    ai
+        .command("generate-campaign")
+        .description("generate campaign-level content (email sequence, templates)")
+        .requiredOption("-n, --campaign-name <name>", "campaign name")
+        .requiredOption("-o, --objective <text>", "campaign objective")
+        .requiredOption("--target-audience <text>", "target audience description")
+        .requiredOption("--key-benefits <list>", "comma-separated key benefits", parseList)
+        .requiredOption("--tone <tone>", "tone (e.g. professional, casual)")
+        .action(async (opts) => {
+        try {
+            const body = {
+                campaign_name: opts.campaignName,
+                objective: opts.objective,
+                target_audience: opts.targetAudience,
+                key_benefits: opts.keyBenefits,
+                tone: opts.tone,
+            };
+            const result = await client.post("/ai/generate/campaign", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    ai
+        .command("analyze")
+        .description("analyze a response in a conversation")
+        .requiredOption("--conversation-id <id>", "conversation ID")
+        .requiredOption("--email-content <text>", "email content to analyze")
+        .action(async (opts) => {
+        try {
+            const result = await client.post("/ai/analyze", {
+                conversation_id: opts.conversationId,
+                email_content: opts.emailContent,
+            });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    ai
+        .command("usage")
+        .description("get AI generation usage stats for the current billing period")
+        .action(async () => {
+        try {
+            const result = await client.get("/ai/usage");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    ai
+        .command("suggestions")
+        .description("get AI-suggested replies for a conversation")
+        .requiredOption("--conversation-id <id>", "conversation ID")
+        .action(async (opts) => {
+        try {
+            const result = await client.get("/ai/suggestions", { conversation_id: opts.conversationId });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/analytics.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { IrisClient } from "../client.js";
+export declare function registerAnalyticsCommands(program: Command, client: IrisClient): void;

package/dist/commands/analytics.js

@@ -0,0 +1,75 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerAnalyticsCommands(program, client) {
+    const analytics = program.command("analytics").alias("a").description("campaign performance and message metrics");
+    analytics
+        .command("overview")
+        .description("high-level overview of all campaign analytics")
+        .action(async () => {
+        try {
+            const result = await client.get("/analytics/overview");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    analytics
+        .command("campaign <id>")
+        .description("detailed analytics for a specific campaign")
+        .action(async (id) => {
+        try {
+            const result = await client.get(`/analytics/campaigns/${id}`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    analytics
+        .command("performance")
+        .description("email performance metrics over time")
+        .option("--days <n>", "time window in days (1–90, default 30)", "30")
+        .option("--campaign-id <id>", "filter by campaign")
+        .action(async (opts) => {
+        try {
+            const params = {};
+            if (opts.days)
+                params.days = opts.days;
+            if (opts.campaignId)
+                params.campaign_id = opts.campaignId;
+            const result = await client.get("/analytics/performance", params);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    analytics
+        .command("response-time")
+        .description("average response time analytics")
+        .option("--campaign-id <id>", "filter by campaign")
+        .action(async (opts) => {
+        try {
+            const params = {};
+            if (opts.campaignId)
+                params.campaign_id = opts.campaignId;
+            const result = await client.get("/analytics/response-time", params);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    analytics
+        .command("contact-types")
+        .description("breakdown of contacts by type/source")
+        .action(async () => {
+        try {
+            const result = await client.get("/analytics/contact-types");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/billing.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { IrisClient } from "../client.js";
+export declare function registerBillingCommands(program: Command, client: IrisClient): void;

package/dist/commands/billing.js

@@ -0,0 +1,16 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerBillingCommands(program, client) {
+    const billing = program.command("billing").alias("b").description("billing plans and pricing");
+    billing
+        .command("plans")
+        .description("list all available billing plans with pricing and feature limits")
+        .action(async () => {
+        try {
+            const result = await client.get("/billing/plans");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/campaigns.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { IrisClient } from "../client.js";
+export declare function registerCampaignCommands(program: Command, client: IrisClient): void;

package/dist/commands/campaigns.js

@@ -0,0 +1,123 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerCampaignCommands(program, client) {
+    const campaigns = program.command("campaigns").alias("c").description("manage campaigns");
+    campaigns
+        .command("list")
+        .description("list campaigns with pagination")
+        .option("-p, --page <n>", "page number", "1")
+        .option("-s, --page-size <n>", "items per page (max 100)", "50")
+        .option("--status <status>", "filter by status: draft, active, paused, completed")
+        .action(async (opts) => {
+        try {
+            const params = {};
+            if (opts.page)
+                params.page = opts.page;
+            if (opts.pageSize)
+                params.page_size = opts.pageSize;
+            if (opts.status)
+                params.status = opts.status;
+            const result = await client.get("/campaigns", params);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("get <id>")
+        .description("get a campaign by ID")
+        .action(async (id) => {
+        try {
+            const result = await client.get(`/campaigns/${id}`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("create")
+        .description("create a new campaign")
+        .requiredOption("-n, --name <name>", "campaign name")
+        .requiredOption("-o, --objective <type>", "objective type: venue_dj, venue_host, product_promotion, custom")
+        .option("-d, --description <text>", "goal description")
+        .option("--product-name <name>", "product name (for product_promotion)")
+        .option("--product-description <text>", "product description (for product_promotion)")
+        .action(async (opts) => {
+        try {
+            const body = {
+                name: opts.name,
+                objective_type: opts.objective,
+            };
+            if (opts.description)
+                body.goal_description = opts.description;
+            if (opts.productName)
+                body.product_name = opts.productName;
+            if (opts.productDescription)
+                body.product_description = opts.productDescription;
+            const result = await client.post("/campaigns", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("update <id>")
+        .description("update a campaign")
+        .option("-n, --name <name>", "campaign name")
+        .option("--status <status>", "status: draft, scheduled, active, paused, completed, deleted")
+        .option("-d, --description <text>", "goal description")
+        .action(async (id, opts) => {
+        try {
+            const body = {};
+            if (opts.name)
+                body.name = opts.name;
+            if (opts.status)
+                body.status = opts.status;
+            if (opts.description)
+                body.goal_description = opts.description;
+            const result = await client.patch(`/campaigns/${id}`, body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("delete <id>")
+        .description("delete a campaign")
+        .action(async (id) => {
+        try {
+            await client.delete(`/campaigns/${id}`);
+            console.log("campaign deleted");
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("usage <id>")
+        .description("get campaign usage stats")
+        .action(async (id) => {
+        try {
+            const result = await client.get(`/campaigns/${id}/usage`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("analyze <id>")
+        .description("run AI analysis on a campaign to generate target profiles")
+        .action(async (id) => {
+        try {
+            const result = await client.post(`/campaigns/${id}/analyze`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/channels.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { IrisClient } from "../client.js";
+export declare function registerChannelCommands(program: Command, client: IrisClient): void;

package/dist/commands/channels.js

@@ -0,0 +1,53 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerChannelCommands(program, client) {
+    const channels = program.command("channels").alias("ch").description("manage outreach channels and connected accounts");
+    channels
+        .command("accounts")
+        .description("list connected social accounts")
+        .action(async () => {
+        try {
+            const result = await client.get("/channels/accounts");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    channels
+        .command("availability")
+        .description("check which outreach channels are available and configured")
+        .action(async () => {
+        try {
+            const result = await client.get("/channels/availability");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    channels
+        .command("send")
+        .description("send a message through a specific channel in a conversation")
+        .requiredOption("--channel <channel>", "channel: email, instagram, twitter, linkedin")
+        .requiredOption("--conversation-id <id>", "conversation ID")
+        .requiredOption("--recipient-id <id>", "recipient (email for email channel; platform handle/ID for social)")
+        .requiredOption("-c, --content <text>", "message content")
+        .option("-s, --subject <text>", "subject (email only)")
+        .action(async (opts) => {
+        try {
+            const body = {
+                channel: opts.channel,
+                conversation_id: opts.conversationId,
+                recipient_id: opts.recipientId,
+                content: opts.content,
+            };
+            if (opts.subject)
+                body.subject = opts.subject;
+            const result = await client.post("/channels/send", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/contacts.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { IrisClient } from "../client.js";
+export declare function registerContactCommands(program: Command, client: IrisClient): void;