@jclvsh/iris 0.7.0 → 0.9.0

package/dist/cli-utils.d.ts

@@ -1,4 +1,58 @@
+/**
+ * Shared CLI + MCP output helpers.
+ *
+ * The CLI consumes these for terminal output (table / JSON / structured exit
+ * codes). MCP tools consume `formatMcpError` so error responses surface the
+ * structured `{success, error: {code, message}}` envelope to the LLM instead
+ * of a flattened message string — lets the model branch on `error.code`
+ * without regex-extracting the bracketed prefix.
+ */
 export declare function formatOutput(data: unknown, format?: string): void;
+/**
+ * Map an iris error-code prefix to a CLI exit code.
+ *
+ * Convention so shell scripts can branch on failure type without parsing stderr:
+ * - 0: success (not handled here)
+ * - 1: generic / unknown
+ * - 2: input / validation (SERVER_VALIDATION_FAILED, SERVER_BAD_REQUEST)
+ * - 3: rate limit
+ * - 4: auth (AUTH_*, APIKEY_*)
+ * - 5: payment / billing (PAYMENT_*, BILLING_*)
+ * - 6: not found (any *_NOT_FOUND)
+ *
+ * Domain-specific codes (CAMP_001, CONTACT_001, etc.) are categorized by their
+ * suffix shape — *_NOT_FOUND maps to 6, others fall through to 1.
+ */
+export declare function exitCodeForMessage(message: string): number;
 export declare function handleError(error: unknown): never;
+/**
+ * Parse the `[CODE] message (field: x)` string format that IrisClient.handleError
+ * builds, recovering the structured fields.
+ *
+ * Returns `{code, message, field?}`. Falls back to `{code: "UNKNOWN_ERROR", message}`
+ * when no bracketed code is present (shouldn't happen for API errors, but safe
+ * for client-side throws like network timeouts).
+ */
+export declare function parseErrorMessage(raw: string): {
+    code: string;
+    message: string;
+    field?: string;
+};
+/**
+ * Format an error caught in an MCP tool handler as the structured response
+ * the MCP SDK returns to the model.
+ *
+ * Returns the canonical iris error envelope `{success: false, error: {code, message, field?}}`
+ * as JSON text inside the MCP `content` block, plus `isError: true` so the SDK
+ * surfaces it as an error to the model. Lets the LLM read `error.code`
+ * structurally instead of regexing it out of a flattened message.
+ */
+export declare function formatMcpError(error: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
 export declare function getFormat(opts: Record<string, unknown>): string;
 export declare function parseList(value: string): string[];

package/dist/cli-utils.js

@@ -1,3 +1,12 @@
+/**
+ * Shared CLI + MCP output helpers.
+ *
+ * The CLI consumes these for terminal output (table / JSON / structured exit
+ * codes). MCP tools consume `formatMcpError` so error responses surface the
+ * structured `{success, error: {code, message}}` envelope to the LLM instead
+ * of a flattened message string — lets the model branch on `error.code`
+ * without regex-extracting the bracketed prefix.
+ */
 export function formatOutput(data, format = "json") {
     if (format === "table" && typeof data === "object" && data !== null) {
         const obj = data;
@@ -16,10 +25,94 @@ export function formatOutput(data, format = "json") {
     }
     console.log(JSON.stringify(data, null, 2));
 }
+/**
+ * Map an iris error-code prefix to a CLI exit code.
+ *
+ * Convention so shell scripts can branch on failure type without parsing stderr:
+ * - 0: success (not handled here)
+ * - 1: generic / unknown
+ * - 2: input / validation (SERVER_VALIDATION_FAILED, SERVER_BAD_REQUEST)
+ * - 3: rate limit
+ * - 4: auth (AUTH_*, APIKEY_*)
+ * - 5: payment / billing (PAYMENT_*, BILLING_*)
+ * - 6: not found (any *_NOT_FOUND)
+ *
+ * Domain-specific codes (CAMP_001, CONTACT_001, etc.) are categorized by their
+ * suffix shape — *_NOT_FOUND maps to 6, others fall through to 1.
+ */
+export function exitCodeForMessage(message) {
+    const codeMatch = message.match(/\[([A-Z]+)_(\d+|[A-Z_]+)\]/);
+    if (!codeMatch)
+        return 1;
+    const prefix = codeMatch[1];
+    const suffix = codeMatch[2];
+    // Suffix-based: *_NOT_FOUND → 6 regardless of prefix
+    if (suffix.includes("NOT_FOUND"))
+        return 6;
+    switch (prefix) {
+        case "AUTH":
+        case "APIKEY":
+            return 4;
+        case "RATE":
+            return 3;
+        case "PAYMENT":
+        case "BILLING":
+            return 5;
+        case "SERVER":
+            // SERVER_002/005 = validation; SERVER_003 = not found; rest = generic
+            if (suffix === "002" || suffix === "005")
+                return 2;
+            if (suffix === "003")
+                return 6;
+            return 1;
+        default:
+            return 1;
+    }
+}
 export function handleError(error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`error: ${message}`);
-    process.exit(1);
+    process.exit(exitCodeForMessage(message));
+}
+/**
+ * Parse the `[CODE] message (field: x)` string format that IrisClient.handleError
+ * builds, recovering the structured fields.
+ *
+ * Returns `{code, message, field?}`. Falls back to `{code: "UNKNOWN_ERROR", message}`
+ * when no bracketed code is present (shouldn't happen for API errors, but safe
+ * for client-side throws like network timeouts).
+ */
+export function parseErrorMessage(raw) {
+    // Format: "[CODE] message (field: x)" — code optional, field optional
+    const match = raw.match(/^\[([A-Z_0-9]+)\]\s+(.*?)(?:\s+\(field:\s+([^)]+)\))?$/);
+    if (!match)
+        return { code: "UNKNOWN_ERROR", message: raw };
+    return {
+        code: match[1],
+        message: match[2],
+        ...(match[3] && { field: match[3] }),
+    };
+}
+/**
+ * Format an error caught in an MCP tool handler as the structured response
+ * the MCP SDK returns to the model.
+ *
+ * Returns the canonical iris error envelope `{success: false, error: {code, message, field?}}`
+ * as JSON text inside the MCP `content` block, plus `isError: true` so the SDK
+ * surfaces it as an error to the model. Lets the LLM read `error.code`
+ * structurally instead of regexing it out of a flattened message.
+ */
+export function formatMcpError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const parsed = parseErrorMessage(raw);
+    const envelope = {
+        success: false,
+        error: parsed,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+        isError: true,
+    };
 }
 export function getFormat(opts) {
     if (opts.json)

package/dist/commands/keys.js

@@ -62,4 +62,15 @@ export function registerKeyCommands(program, client) {
             handleError(error);
         }
     });
+    keys.command("rotate <id>")
+        .description("rotate an API key — revokes the old key and returns a new one with the same name and scopes (requires admin scope; cannot rotate the key being used for this call). The new raw key is shown once — store it immediately.")
+        .action(async (id) => {
+        try {
+            const result = await client.post(`/keys/${id}/rotate`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/tools/agent-credits.js

@@ -1,3 +1,4 @@
+import { formatMcpError } from "../cli-utils.js";
 /**
  * Agent credit tools.
  *
@@ -12,15 +13,7 @@ export function registerAgentCreditTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("purchase_credit_pack", "purchase a 5-credit pack via MPP ($12.00 USD). x402 agents use per-campaign pricing instead. API key users do not need credits.", {}, async () => {
@@ -29,15 +22,7 @@ export function registerAgentCreditTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
 }

package/dist/tools/ai.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatMcpError } from "../cli-utils.js";
 export function registerAiTools(server, client) {
     server.tool("generate_content", "generate AI content for a specific contact conversation (email draft, follow-up, reply). requires generate scope.", {
         contact_id: z.string().uuid().describe("contact ID"),
@@ -11,15 +12,7 @@ export function registerAiTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("generate_campaign_content", "generate campaign-level outreach content (email sequence, templates) from a campaign brief. content-first: takes the strategy inline, not a campaign id. requires generate scope.", {
@@ -34,15 +27,7 @@ export function registerAiTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("analyze_response", "analyze an inbound message using AI to determine sentiment, intent, and suggested actions. requires generate scope.", {
@@ -54,15 +39,7 @@ export function registerAiTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("get_ai_usage", "get AI generation usage limits and current counts for the billing period. requires read scope.", {}, async () => {
@@ -71,15 +48,7 @@ export function registerAiTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
 }

package/dist/tools/analytics.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatMcpError } from "../cli-utils.js";
 export function registerAnalyticsTools(server, client) {
     server.tool("get_analytics_overview", "get a high-level overview of all campaign analytics. requires read scope.", {}, async () => {
         try {
@@ -6,15 +7,7 @@ export function registerAnalyticsTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("get_campaign_analytics", "get detailed analytics for a specific campaign. requires read scope.", {
@@ -25,15 +18,7 @@ export function registerAnalyticsTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("get_performance_metrics", "get email performance metrics over time. requires read scope.", {
@@ -50,15 +35,7 @@ export function registerAnalyticsTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("get_response_time", "get average response time analytics. requires read scope.", {
@@ -72,15 +49,7 @@ export function registerAnalyticsTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("get_contact_types", "get breakdown of contacts by type/source. requires read scope.", {}, async () => {
@@ -89,12 +58,7 @@ export function registerAnalyticsTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
 }

package/dist/tools/billing.js

@@ -1,3 +1,4 @@
+import { formatMcpError } from "../cli-utils.js";
 export function registerBillingTools(server, client) {
     server.tool("get_billing_plans", "get all available billing plans with pricing and feature limits. requires read scope.", {}, async () => {
         try {
@@ -5,15 +6,7 @@ export function registerBillingTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
 }

package/dist/tools/campaigns.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatMcpError } from "../cli-utils.js";
 const CAMPAIGN_STATUSES = ["draft", "active", "paused", "completed", "deleted"];
 const OBJECTIVE_TYPES = ["venue_dj", "venue_host", "product_promotion", "custom"];
 const TARGET_PROFILE_TYPES = [
@@ -30,15 +31,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("create_campaign", "create a new outreach campaign. requires write scope.", {
@@ -57,15 +50,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("get_campaign", "get a campaign by ID with stats. requires read scope.", {
@@ -76,15 +61,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("update_campaign", "update a campaign's details. requires write scope.", {
@@ -100,15 +77,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("delete_campaign", "soft-delete a campaign (sets status to deleted). requires write scope.", {
@@ -119,15 +88,7 @@ export function registerCampaignTools(server, client) {
             return { content: [{ type: "text", text: `campaign ${id} deleted` }] };
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `error: ${error instanceof Error ? error.message : String(error)}`,
-                    },
-                ],
-                isError: true,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("list_campaign_contacts", "list contacts in a campaign with optional status filter. requires read scope.", {
@@ -151,15 +112,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("get_campaign_usage", "get usage limits and current counts for a campaign. requires read scope.", {
@@ -170,15 +123,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("analyze_campaign", "trigger AI analysis of a campaign to generate target profiles and recommendations. requires write scope.", {
@@ -189,15 +134,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("list_target_profiles", "list target profiles for a campaign. requires read scope.", {
@@ -208,15 +145,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("create_target_profile", "create a target profile for a campaign. requires write scope.", {
@@ -236,15 +165,7 @@ export function registerCampaignTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("delete_target_profile", "delete a target profile from a campaign. requires write scope.", {
@@ -256,15 +177,7 @@ export function registerCampaignTools(server, client) {
             return { content: [{ type: "text", text: `target profile ${profile_id} deleted` }] };
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `error: ${error instanceof Error ? error.message : String(error)}`,
-                    },
-                ],
-                isError: true,
-            };
+            return formatMcpError(error);
         }
     });
 }

package/dist/tools/channels.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatMcpError } from "../cli-utils.js";
 const CHANNELS = ["email", "instagram", "twitter"];
 export function registerChannelTools(server, client) {
     server.tool("list_connected_accounts", "list all connected social media accounts. requires read scope.", {}, async () => {
@@ -7,15 +8,7 @@ export function registerChannelTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("check_channel_availability", "check which outreach channels are available and configured. requires read scope.", {}, async () => {
@@ -24,15 +17,7 @@ export function registerChannelTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
     server.tool("send_channel_message", "send a message through a specific channel in a conversation. requires send scope.", {
@@ -50,15 +35,7 @@ export function registerChannelTools(server, client) {
             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,
-            };
+            return formatMcpError(error);
         }
     });
 }