@jclvsh/iris 0.2.0

package/dist/tools/webhooks.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+const WEBHOOK_EVENTS = [
+    "campaign.created",
+    "campaign.updated",
+    "campaign.deleted",
+    "campaign.activated",
+    "campaign.completed",
+    "contact.created",
+    "contact.updated",
+    "contact.deleted",
+    "conversation.created",
+    "conversation.updated",
+    "message.sent",
+    "message.delivered",
+    "message.opened",
+    "message.clicked",
+    "message.replied",
+    "message.bounced",
+    "message.failed",
+];
+export function registerWebhookTools(server, client) {
+    server.tool("list_webhooks", "list all configured webhooks. requires webhooks:read scope.", {
+        page: z.number().int().positive().optional().describe("page number (default 1)"),
+        page_size: z.number().int().min(1).max(100).optional().describe("items per page (default 50, max 100)"),
+    }, async ({ page, page_size }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = String(page);
+            if (page_size !== undefined)
+                params.page_size = String(page_size);
+            const result = await client.get("/webhooks", params);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("create_webhook", "create a new webhook endpoint. requires webhooks:write scope.", {
+        url: z
+            .string()
+            .url()
+            .refine((u) => u.startsWith("https://"), { message: "webhook URL must use HTTPS" })
+            .describe("webhook endpoint URL (must be HTTPS)"),
+        events: z.array(z.enum(WEBHOOK_EVENTS)).min(1).describe("events to subscribe to"),
+        description: z.string().max(500).optional().describe("webhook description"),
+    }, async (args) => {
+        try {
+            const result = await client.post("/webhooks", args);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_webhook", "get a webhook by ID. requires webhooks:read scope.", {
+        id: z.string().uuid().describe("webhook ID"),
+    }, async ({ id }) => {
+        try {
+            const result = await client.get(`/webhooks/${id}`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("update_webhook", "update a webhook's configuration. requires webhooks:write scope.", {
+        id: z.string().uuid().describe("webhook ID"),
+        url: z
+            .string()
+            .url()
+            .refine((u) => u.startsWith("https://"), { message: "webhook URL must use HTTPS" })
+            .optional()
+            .describe("new endpoint URL (must be HTTPS)"),
+        events: z.array(z.enum(WEBHOOK_EVENTS)).min(1).optional().describe("new events to subscribe to"),
+        active: z.boolean().optional().describe("enable or disable the webhook"),
+    }, async ({ id, ...body }) => {
+        try {
+            const result = await client.patch(`/webhooks/${id}`, body);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("delete_webhook", "delete a webhook. requires webhooks:write scope.", {
+        id: z.string().uuid().describe("webhook ID"),
+    }, async ({ id }) => {
+        try {
+            await client.delete(`/webhooks/${id}`);
+            return { content: [{ type: "text", text: `webhook ${id} deleted` }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("test_webhook", "send a test event to a webhook endpoint to verify it's working. requires webhooks:write scope.", {
+        id: z.string().uuid().describe("webhook ID"),
+    }, async ({ id }) => {
+        try {
+            const result = await client.post(`/webhooks/${id}/test`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("rotate_webhook_secret", "rotate the signing secret for a webhook. the new secret is returned in the response. requires webhooks:write scope.", {
+        id: z.string().uuid().describe("webhook ID"),
+    }, async ({ id }) => {
+        try {
+            const result = await client.post(`/webhooks/${id}/rotate-secret`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("list_webhook_deliveries", "list delivery history for a webhook. requires webhooks:read scope.", {
+        id: z.string().uuid().describe("webhook ID"),
+        page: z.number().int().positive().optional().describe("page number (default 1)"),
+        page_size: z.number().int().min(1).max(100).optional().describe("items per page (default 50, max 100)"),
+    }, async ({ id, page, page_size }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = String(page);
+            if (page_size !== undefined)
+                params.page_size = String(page_size);
+            const result = await client.get(`/webhooks/${id}/deliveries`, params);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,256 @@
+export interface PaginatedResponse<T> {
+    success: true;
+    data: T[];
+    meta: {
+        pagination: {
+            page: number;
+            page_size: number;
+            total: number;
+            total_pages: number;
+        };
+    };
+}
+export interface DataResponse<T> {
+    success: true;
+    data: T;
+}
+export interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        field?: string;
+        requestId?: string;
+    };
+}
+export interface Campaign {
+    id: string;
+    user_id: string;
+    name: string;
+    status: string;
+    objective_type: string;
+    product_name: string | null;
+    product_url: string | null;
+    product_description: string | null;
+    follow_up_enabled: boolean;
+    follow_up_max_count: number;
+    follow_up_delay_days: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface CampaignWithStats extends Campaign {
+    contacts_count?: number;
+    conversations_count?: number;
+    emails_sent?: number;
+    emails_opened?: number;
+    emails_replied?: number;
+}
+export interface CampaignUsage {
+    campaign_id: string;
+    contacts_count: number;
+    contacts_limit: number;
+    emails_sent: number;
+    emails_limit: number;
+    discovery_runs: number;
+    discovery_limit: number;
+}
+export interface TargetProfile {
+    id: string;
+    campaign_id: string;
+    name: string;
+    profile_type: string;
+    fit_score: number | null;
+    job_titles: string[];
+    industries: string[];
+    pain_points: string[];
+    buying_signals: string[];
+    discovery_keywords: string[];
+    recommended_channels: string[];
+    created_at: string;
+    updated_at: string;
+}
+export interface Contact {
+    id: string;
+    user_id: string;
+    email: string | null;
+    first_name: string | null;
+    last_name: string | null;
+    company_name: string | null;
+    job_title: string | null;
+    phone: string | null;
+    website: string | null;
+    tags: string[];
+    enrichment_data: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+export interface ContactUsage {
+    contacts_count: number;
+    contacts_limit: number;
+    period_start: string;
+    period_end: string;
+}
+export interface Conversation {
+    id: string;
+    campaign_id: string | null;
+    contact_id: string;
+    user_id: string;
+    channel: string;
+    status: string;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ConversationWithDetails extends Conversation {
+    contact?: Contact;
+    campaign?: Campaign;
+    last_message?: Message;
+    unread_count?: number;
+}
+export interface Message {
+    id: string;
+    conversation_id: string;
+    direction: string;
+    channel: string;
+    content: string;
+    status: string;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface EngagementMetrics {
+    total_conversations: number;
+    active_conversations: number;
+    response_rate: number;
+    avg_response_time_hours: number;
+}
+export interface AiUsage {
+    generations_count: number;
+    generations_limit: number;
+    period_start: string;
+    period_end: string;
+}
+export interface AiSuggestion {
+    type: string;
+    content: string;
+    confidence: number;
+}
+export interface DiscoveryJob {
+    id: string;
+    campaign_id: string | null;
+    status: string;
+    source: string;
+    query: string;
+    results_count: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface DiscoverySource {
+    id: string;
+    name: string;
+    type: string;
+    description: string;
+    is_available: boolean;
+}
+export interface AnalyticsOverview {
+    total_campaigns: number;
+    active_campaigns: number;
+    total_contacts: number;
+    total_conversations: number;
+    emails_sent: number;
+    emails_opened: number;
+    emails_replied: number;
+    response_rate: number;
+}
+export interface CampaignAnalytics {
+    campaign_id: string;
+    contacts_count: number;
+    emails_sent: number;
+    emails_delivered: number;
+    emails_opened: number;
+    emails_clicked: number;
+    emails_replied: number;
+    emails_bounced: number;
+    open_rate: number;
+    click_rate: number;
+    reply_rate: number;
+    bounce_rate: number;
+}
+export interface PerformanceMetrics {
+    period: string;
+    emails_sent: number;
+    emails_opened: number;
+    emails_replied: number;
+    open_rate: number;
+    reply_rate: number;
+}
+export interface BillingPlan {
+    id: string;
+    name: string;
+    tier: string;
+    price_monthly: number;
+    price_yearly: number;
+    features: Record<string, unknown>;
+    limits: Record<string, number>;
+}
+export interface ConnectedAccount {
+    id: string;
+    user_id: string;
+    platform: string;
+    platform_user_id: string;
+    platform_username: string | null;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ChannelAvailability {
+    channel: string;
+    available: boolean;
+    account_id: string | null;
+    reason: string | null;
+}
+export interface Notification {
+    id: string;
+    user_id: string;
+    type: string;
+    title: string;
+    message: string;
+    read: boolean;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+export interface ApiKey {
+    id: string;
+    user_id: string;
+    name: string;
+    key_prefix: string;
+    scopes: string[];
+    expires_at: string | null;
+    last_used_at: string | null;
+    created_at: string;
+}
+export interface Webhook {
+    id: string;
+    user_id: string;
+    url: string;
+    events: string[];
+    description: string | null;
+    active: boolean;
+    secret: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateApiKeyResponse extends ApiKey {
+    key: string;
+}
+export interface WebhookDelivery {
+    id: string;
+    webhook_id: string;
+    event: string;
+    status: string;
+    status_code: number | null;
+    request_body: Record<string, unknown>;
+    response_body: string | null;
+    created_at: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// --- Response wrappers ---
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@jclvsh/iris",
+	"version": "0.2.0",
+	"description": "MCP server for the Iris API",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"bin": {
+		"iris-mcp": "dist/index.js",
+		"iris": "dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc",
+		"start": "node dist/index.js"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.11.0",
+		"commander": "^14.0.3",
+		"zod": "^3.24.0"
+	},
+	"devDependencies": {
+		"typescript": "^5.7.0",
+		"@types/node": "^22.0.0"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"license": "MIT"
+}