@jclvsh/iris 0.2.3 → 0.2.4

package/README.md

@@ -1,32 +1,108 @@
 # @jclvsh/iris
 
-MCP server for the [Iris](https://iris-ai.dev) API — AI-powered messaging assistant for automated multi-channel outreach campaigns.
+MCP server and CLI for the [Iris](https://iris-ai.dev) API — AI-powered messaging assistant for automated multi-channel outreach campaigns. Lets AI agents (Claude Code, Cursor) and humans manage campaigns, contacts, conversations, AI generations, discovery, channels, and webhooks.
 
-## Install
+## Installation
 
-The package ships two binaries: `iris-mcp` (the MCP server, used in MCP host configs below) and `iris` (the CLI, for terminal use). One-shot run:
+```bash
+npm install -g @jclvsh/iris
+```
+
+This installs two binaries:
+
+- `iris` — CLI for terminal use
+- `iris-mcp` — MCP server for AI agents
+
+Or run one-shot without installing:
 
 ```bash
 npx -y -p @jclvsh/iris iris-mcp
 ```
 
-## Configuration
+## CLI
+
+```bash
+# set your API key
+export IRIS_API_KEY=is_live_...
+
+# manage campaigns
+iris campaigns list
+iris campaigns create -n "spring outreach" -o product_promotion --product-name "acme widgets"
+iris campaigns analyze <id>
+iris campaigns usage <id>
+
+# manage contacts
+iris contacts list --campaign-id <id>
+iris contacts create --campaign-id <id> -e jane@example.com --full-name "Jane Doe" --company-name "Acme"
+
+# review the AI approval queue
+iris messages pending --campaign-id <id>
+iris messages approve <id>
+iris messages reject <id> --reason "off-topic"
+iris messages bulk -a approve --ids id1,id2,id3
+
+# manage webhooks
+iris webhooks create -u https://example.com/hook -e campaign.created,message.delivered
+iris webhooks test <id>
+iris webhooks deliveries <id>
+
+# check your key
+iris keys me
+
+# table output
+iris --format table campaigns list
+
+# full help
+iris --help
+iris campaigns --help
+```
+
+### CLI Commands
+
+| Group | Alias | Commands | Count |
+| --- | --- | --- | --- |
+| campaigns | `c` | list, get, create, update, delete, usage, analyze | 7 |
+| contacts | `ct` | list, get, create, update, delete, usage | 6 |
+| messages | `m` | pending, approve, reject, retry, feedback, bulk | 6 |
+| conversations | `conv` | list, get, messages, read | 4 |
+| discovery | `d` | search, search-campaign, sources, job | 4 |
+| ai | — | generate, generate-campaign, analyze, usage, suggestions | 5 |
+| keys | `k` | me, list, create, rename, revoke | 5 |
+| webhooks | `w` | list, create, get, update, delete, test, deliveries | 7 |
+| notifications | `n` | list, update, delete, read-all | 4 |
+| analytics | `a` | overview, campaign, performance, response-time, contact-types | 5 |
+| billing | `b` | plans | 1 |
+| channels | `ch` | accounts, availability, send | 3 |
+| credits | `cr` | balance, buy | 2 |
+
+## MCP Server Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `IRIS_API_KEY` | Yes | API key (must start with `is_live_`) |
+| `IRIS_API_URL` | No | API base URL (default: `https://iris-ai.dev/api/v1`) |
+
+> **Note:** the args use `-p @jclvsh/iris iris-mcp` to explicitly select the MCP-server bin. The package ships two binaries (`iris` for the CLI, `iris-mcp` for the MCP server), so a bare `npx @jclvsh/iris` would launch the CLI by default.
+
+Get your API key at [iris-ai.dev/settings/api-keys](https://iris-ai.dev/settings/api-keys).
 
 ### Claude Code
 
-Add to your Claude Code settings:
+Add to your `.claude/settings.json`:
 
 ```json
 {
-  "mcpServers": {
-    "iris": {
-      "command": "npx",
-      "args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
-      "env": {
-        "IRIS_API_KEY": "is_live_..."
-      }
-    }
-  }
+	"mcpServers": {
+		"iris": {
+			"command": "npx",
+			"args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
+			"env": {
+				"IRIS_API_KEY": "is_live_your_key_here"
+			}
+		}
+	}
 }
 ```
 
@@ -36,45 +112,306 @@ Add to `.cursor/mcp.json`:
 
 ```json
 {
-  "mcpServers": {
-    "iris": {
-      "command": "npx",
-      "args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
-      "env": {
-        "IRIS_API_KEY": "is_live_..."
-      }
-    }
-  }
+	"mcpServers": {
+		"iris": {
+			"command": "npx",
+			"args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
+			"env": {
+				"IRIS_API_KEY": "is_live_your_key_here"
+			}
+		}
+	}
 }
 ```
 
-## Environment Variables
+## Available Tools
 
-| 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`) |
+### Campaigns
 
-Get your API key at [iris-ai.dev/settings/api-keys](https://iris-ai.dev/settings/api-keys).
+| Tool | Description |
+| --- | --- |
+| `list_campaigns` | List campaigns with optional status filter |
+| `create_campaign` | Create a new outreach campaign |
+| `get_campaign` | Get a campaign by ID with stats |
+| `update_campaign` | Update a campaign's name, status, or follow-up settings |
+| `delete_campaign` | Soft-delete a campaign (sets status to `deleted`) |
+| `list_campaign_contacts` | List contacts in a campaign with optional status filter |
+| `get_campaign_usage` | Get usage limits and current counts for a campaign |
+| `analyze_campaign` | Trigger AI analysis to generate target profiles |
+| `list_target_profiles` | List target profiles for a campaign |
+| `create_target_profile` | Create a target profile for a campaign |
+| `delete_target_profile` | Delete a target profile from a campaign |
 
-## Available Tools
+#### `create_campaign` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string (1-100) | Yes | Campaign name |
+| `objective_type` | enum | Yes | `venue_dj`, `venue_host`, `product_promotion`, `custom` |
+| `product_name` | string (≤200) | No | Product name (for `product_promotion`) |
+| `product_url` | string (URL) | No | Product URL (for `product_promotion`) |
+| `product_description` | string (≤2000) | No | Product description (for `product_promotion`) |
+
+#### `update_campaign` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string (UUID) | Yes | Campaign ID |
+| `name` | string (1-100) | No | New campaign name |
+| `status` | enum | No | `draft`, `active`, `paused`, `completed`, `deleted` |
+| `follow_up_enabled` | boolean | No | Enable follow-up emails |
+| `follow_up_max_count` | number (0-10) | No | Max follow-up count |
+| `follow_up_delay_days` | number (1-30) | No | Days between follow-ups |
+
+#### `create_target_profile` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string (UUID) | Yes | Campaign ID |
+| `name` | string (1-200) | Yes | Profile name |
+| `profile_type` | enum | Yes | `local_business`, `content_creator`, `influencer`, `b2b_professional`, `ecommerce`, `saas_company`, `agency`, `freelancer`, `other` |
+| `job_titles` | string[] | No | Target job titles |
+| `industries` | string[] | No | Target industries |
+| `discovery_keywords` | string[] | No | Keywords for contact discovery |
+| `recommended_channels` | string[] | No | `email`, `instagram`, `twitter`, `linkedin` |
+
+### Contacts
+
+| Tool | Description |
+| --- | --- |
+| `list_contacts` | List contacts with search |
+| `create_contact` | Create a new contact |
+| `get_contact` | Get a contact by ID |
+| `update_contact` | Update a contact's details |
+| `delete_contact` | Soft-delete a contact |
+| `bulk_import_contacts` | Import up to 500 contacts at once |
+| `get_contact_usage` | Get usage limits for the billing period |
+| `list_contact_conversations` | List conversations for a specific contact |
+
+#### `create_contact` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `email` | string (email) | Yes | Contact email address |
+| `first_name` | string (≤100) | No | First name |
+| `last_name` | string (≤100) | No | Last name |
+| `company_name` | string (≤200) | No | Company name |
+| `job_title` | string (≤200) | No | Job title |
+| `phone` | string (≤50) | No | Phone number |
+| `website` | string (URL) | No | Website URL |
+| `tags` | string[] | No | Tags for categorization |
+
+#### `bulk_import_contacts` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `contacts` | object[] (1-500) | Yes | Array of contacts (`email`, `first_name?`, `last_name?`, `company_name?`, `job_title?`, `tags?`) |
+| `campaign_id` | string (UUID) | No | Campaign to add contacts to |
+
+### Messages
+
+| Tool | Description |
+| --- | --- |
+| `list_pending_messages` | List messages pending approval |
+| `approve_message` | Approve a single pending message |
+| `reject_message` | Reject a single pending message |
+| `retry_message` | Retry a failed message send |
+| `submit_message_feedback` | Submit feedback to improve future AI generations |
+| `bulk_message_action` | Bulk approve or reject pending messages |
 
-| 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) |
+### Conversations
+
+| Tool | Description |
+| --- | --- |
+| `list_conversations` | List conversations with optional channel/status filters |
+| `get_conversation` | Get a conversation by ID |
+| `get_conversation_messages` | List messages in a conversation |
+| `mark_conversation_read` | Mark a conversation as read |
+| `get_engagement_metrics` | Get engagement metrics across conversations |
+
+### AI
+
+| Tool | Description |
+| --- | --- |
+| `generate_content` | Generate AI content for a contact conversation (initial email, follow-up, reply) |
+| `generate_campaign_content` | Generate campaign-level content (email templates, subject lines, briefs) |
+| `analyze_response` | Analyze inbound message sentiment, intent, and suggested action |
+| `get_ai_usage` | Get AI generation usage limits |
+| `get_ai_suggestions` | Get AI-powered suggestions for a conversation |
+
+#### `generate_content` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `contact_id` | string (UUID) | Yes | Contact ID |
+| `conversation_id` | string (UUID) | Yes | Conversation ID |
+| `generation_type` | enum | Yes | `initial_email`, `follow_up`, `reply` |
+| `context` | string (≤2000) | No | Additional context for the AI |
+
+### Discovery
+
+| Tool | Description |
+| --- | --- |
+| `search_contacts` | Search for contacts by criteria (location, keywords, sources) |
+| `search_campaign_contacts` | Run discovery scoped to a campaign's target profiles |
+| `get_discovery_job` | Get the status of a discovery job |
+| `list_discovery_sources` | List available discovery sources (Google Maps, social) |
+
+### Channels
+
+| Tool | Description |
+| --- | --- |
+| `list_connected_accounts` | List your connected social accounts (Twitter, Instagram, LinkedIn) |
+| `check_channel_availability` | Check which channels are reachable for a contact |
+| `send_channel_message` | Send a message via a specific channel |
+
+### Analytics
+
+| Tool | Description |
+| --- | --- |
+| `get_analytics_overview` | Account-level analytics overview |
+| `get_campaign_analytics` | Per-campaign performance metrics |
+| `get_performance_metrics` | Aggregate performance across campaigns |
+| `get_response_time` | Response time distribution |
+| `get_contact_types` | Engagement broken down by contact type |
+
+### Notifications
+
+| Tool | Description |
+| --- | --- |
+| `list_notifications` | List your notifications |
+| `update_notification` | Mark a notification as read or update its state |
+| `delete_notification` | Delete a notification |
+| `mark_all_notifications_read` | Mark every unread notification as read |
+
+### Billing
+
+| Tool | Description |
+| --- | --- |
+| `get_billing_plans` | List available subscription plans |
+
+### API Keys
+
+| Tool | Description |
+| --- | --- |
+| `get_current_api_key` | Get details about the currently authenticated key |
+| `list_api_keys` | List all API keys for the account |
+| `create_api_key` | Create a new API key (raw key returned once) |
+| `revoke_api_key` | Revoke (delete) an API key |
+
+#### `create_api_key` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string (1-100) | Yes | Key name for identification |
+| `scopes` | string[] | No | Permission scopes (defaults to all scopes) — see [Scopes](#api-key--scopes) |
+| `expires_at` | string (ISO 8601) | No | Expiration date |
+
+### Webhooks
+
+| Tool | Description |
+| --- | --- |
+| `list_webhooks` | List all configured webhooks |
+| `create_webhook` | Create a new webhook endpoint |
+| `get_webhook` | Get a webhook by ID |
+| `update_webhook` | Update a webhook's URL, events, or active status |
+| `delete_webhook` | Delete a webhook |
+| `test_webhook` | Send a test event to a webhook URL |
+| `rotate_webhook_secret` | Rotate the signing secret (new secret returned once) |
+| `list_webhook_deliveries` | List delivery history for a webhook |
+
+#### `create_webhook` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `url` | string (HTTPS URL) | Yes | Webhook endpoint URL — HTTPS only |
+| `events` | string[] (≥1) | Yes | Events to subscribe to — see [Webhook Events](#webhook-events) |
+| `description` | string (≤500) | No | Webhook description |
+
+#### `update_webhook` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string (UUID) | Yes | Webhook ID |
+| `url` | string (HTTPS URL) | No | New endpoint URL |
+| `events` | string[] (≥1) | No | New events to subscribe to |
+| `active` | boolean | No | Enable or disable the webhook |
+
+### Agent Credits
+
+> Credits apply only to agents authenticating via x402 (USDC on Base) or MPP (Stripe). API key users do not need credits.
+
+| Tool | Description |
+| --- | --- |
+| `get_credit_balance` | Check the agent credit balance |
+| `purchase_credit_pack` | Purchase a 5-credit pack via MPP ($12.00) |
+
+## API Key & Scopes
+
+Generate an API key at [iris-ai.dev/settings/api-keys](https://iris-ai.dev/settings/api-keys).
+
+API keys support fine-grained scopes per resource:
+
+| Scope | Access |
+| --- | --- |
+| `campaigns:read` / `campaigns:write` | Read or modify campaigns |
+| `contacts:read` / `contacts:write` | Read or modify contacts |
+| `conversations:read` / `conversations:write` | Read conversations or send messages |
+| `messages:read` / `messages:write` | Read the queue, approve/reject/send |
+| `ai:read` / `ai:write` | Read AI usage or trigger generations |
+| `discovery:read` / `discovery:write` | Read sources or run discovery jobs |
+| `analytics:read` | Read analytics dashboards |
+| `billing:read` | Read billing plans |
+| `channels:read` / `channels:write` | Read connected accounts or send via channels |
+| `notifications:read` / `notifications:write` | Read or modify notifications |
+| `webhooks:read` / `webhooks:write` | Read or manage webhook subscriptions |
+| `keys:read` / `keys:write` | Read or manage API keys |
+
+### Recommended Scopes by Use Case
+
+| Use Case | Recommended Scopes |
+| --- | --- |
+| AI agents / MCP | `campaigns:read`, `campaigns:write`, `contacts:read`, `contacts:write`, `messages:read`, `messages:write`, `ai:read`, `ai:write`, `conversations:read`, `conversations:write` |
+| Read-only monitoring | `*:read` scopes only |
+| Webhook management | `webhooks:read`, `webhooks:write` |
+| Discovery automation | `discovery:read`, `discovery:write`, `contacts:write`, `campaigns:read` |
+
+## Webhook Events
+
+| Event | Description |
+| --- | --- |
+| `campaign.created` | New campaign created |
+| `campaign.updated` | Campaign details changed |
+| `campaign.deleted` | Campaign soft-deleted |
+| `contact.created` | New contact added |
+| `contact.updated` | Contact details changed |
+| `contact.deleted` | Contact soft-deleted |
+| `conversation.created` | New conversation started |
+| `conversation.reply_received` | Inbound reply received |
+| `message.sent` | Outbound message sent |
+| `message.delivered` | Message confirmed delivered |
+| `message.opened` | Email opened (filtered for bots) |
+| `message.bounced` | Message bounced |
+| `message.approved` | Message approved in the queue |
+| `message.rejected` | Message rejected in the queue |
+| `discovery.completed` | Discovery job finished successfully |
+| `discovery.failed` | Discovery job failed |
+
+Webhook deliveries are signed with HMAC-SHA256 using the secret returned from `create_webhook` / `rotate_webhook_secret`. Verify the signature in the `X-Iris-Signature` header before trusting the payload.
 
 ## Documentation
 
-Full API documentation: [iris-ai.dev/docs](https://iris-ai.dev/docs)
+Full API reference: [iris-ai.dev/docs](https://iris-ai.dev/docs)
+
+## Development
+
+```bash
+# install dependencies
+npm install
+
+# build
+npm run build
+
+# run the MCP server
+IRIS_API_KEY=is_live_... npm start
+```

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { Command } from "commander";
 import { IrisClient } from "./client.js";
 import { handleError } from "./cli-utils.js";
+const pkg = createRequire(import.meta.url)("../package.json");
 import { registerCampaignCommands } from "./commands/campaigns.js";
 import { registerContactCommands } from "./commands/contacts.js";
 import { registerMessageCommands } from "./commands/messages.js";
@@ -18,7 +20,7 @@ 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")
+    .version(pkg.version)
     .option("--json", "output as JSON (default)")
     .option("--format <fmt>", "output format: json, table", "json");
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/iris",
-	"version": "0.2.3",
+	"version": "0.2.4",
 	"description": "MCP server for the Iris API",
 	"type": "module",
 	"main": "dist/index.js",