close-crm-cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,566 @@
+# AI Agent Guide — Close CRM CLI
+
+> This file helps AI agents (Claude, GPT, Gemini, open-source models) install, authenticate, and use the Close CRM CLI to manage leads, contacts, opportunities, activities, pipelines, sequences, and the full Close CRM API.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g close-crm-cli
+
+# Authenticate (non-interactive — best for agents)
+export CLOSE_API_KEY="your-api-key-here"
+
+# Verify it works
+close users me
+```
+
+**Requirements:** Node.js 18+
+
+## Authentication
+
+Close CRM uses API key auth (HTTP Basic Auth under the hood). Provide your key via:
+
+```bash
+# 1. Environment variable (recommended for agents)
+export CLOSE_API_KEY="your-api-key-here"
+
+# 2. Per-command flag
+close leads list --api-key "your-api-key-here"
+
+# 3. Interactive login (stores in ~/.close/config.json)
+close login
+```
+
+Get your API key: https://app.close.com/settings/api
+
+## Output Format
+
+All commands output **JSON to stdout** by default:
+
+```bash
+# Default: compact JSON
+close leads list
+
+# Pretty-printed JSON
+close leads list --pretty
+
+# Select specific fields
+close leads list --fields id,display_name,status_label
+
+# Suppress output (exit code only)
+close leads list --quiet
+```
+
+**Exit codes:** 0 = success, 1 = error. Errors go to stderr as JSON:
+```json
+{"error":"No API key found.","code":"AUTH_ERROR"}
+```
+
+## Discovering Commands
+
+```bash
+# List all command groups
+close --help
+
+# List subcommands in a group
+close leads --help
+
+# Get help for a specific subcommand
+close leads create --help
+```
+
+## All Command Groups & Subcommands
+
+### leads
+Manage CRM leads (companies/prospects).
+```
+list           List leads (with query support)
+get            Get a lead by ID
+create         Create a new lead (with optional contacts/opportunities)
+update         Update a lead
+delete         Delete a lead
+merge          Merge two leads (source → destination)
+search         Advanced search using Close query DSL
+```
+
+### contacts
+Manage contacts (people) within leads.
+```
+list    List contacts (filter by --lead-id)
+get     Get a contact by ID
+create  Create a contact on a lead
+update  Update a contact
+delete  Delete a contact
+```
+
+### opportunities
+Manage sales opportunities in pipelines.
+```
+list    List opportunities (filter by lead, pipeline, status, user)
+get     Get an opportunity by ID
+create  Create an opportunity on a lead
+update  Update an opportunity (move stages, update value, set close date)
+delete  Delete an opportunity
+```
+
+### tasks
+Manage tasks and follow-ups.
+```
+list         List tasks (filter by lead, assignee, type, completion)
+get          Get a task by ID
+create       Create a task on a lead
+update       Update a task
+delete       Delete a task
+bulk-update  Bulk update tasks (e.g. mark multiple complete)
+```
+
+### activities
+Unified activity stream.
+```
+list   List all activity types (Call, Email, Note, SMS, Meeting, etc.)
+```
+
+### calls
+Log and manage call activities.
+```
+list    List call activities
+get     Get a call by ID
+create  Log a call
+update  Update a call
+delete  Delete a call
+```
+
+### notes
+Manage note activities.
+```
+list    List notes
+get     Get a note by ID
+create  Create a note on a lead
+update  Update a note
+delete  Delete a note
+```
+
+### emails
+Manage email activities (send/log emails).
+```
+list    List email activities
+get     Get an email by ID
+create  Send or log an email
+update  Update an email
+delete  Delete an email
+```
+
+### sms
+Manage SMS activities.
+```
+list    List SMS activities
+get     Get an SMS by ID
+create  Send or log an SMS
+delete  Delete an SMS
+```
+
+### meetings
+Manage meeting activities.
+```
+list    List meetings
+get     Get a meeting by ID
+update  Update a meeting
+delete  Delete a meeting
+```
+
+### users
+Manage users.
+```
+me            Get current authenticated user
+list          List all users
+get           Get a user by ID
+availability  Get dialer availability status for all users
+```
+
+### pipelines
+Manage sales pipelines.
+```
+list    List pipelines
+get     Get a pipeline by ID
+create  Create a pipeline
+update  Update a pipeline
+delete  Delete a pipeline
+```
+
+### lead-statuses
+Manage lead status labels.
+```
+list    List lead statuses
+get     Get a lead status by ID
+create  Create a lead status
+update  Update a lead status
+delete  Delete a lead status
+```
+
+### opportunity-statuses
+Manage opportunity status stages.
+```
+list    List opportunity statuses
+get     Get an opportunity status by ID
+create  Create an opportunity status (tied to a pipeline)
+update  Update an opportunity status
+delete  Delete an opportunity status
+```
+
+### custom-fields
+Manage custom fields for all object types.
+```
+list-lead          List custom fields for leads
+get-lead           Get a lead custom field by ID
+create-lead        Create a lead custom field
+update-lead        Update a lead custom field
+delete-lead        Delete a lead custom field
+
+list-contact       (same pattern for contact)
+get-contact
+create-contact
+update-contact
+delete-contact
+
+list-opportunity   (same for opportunity)
+get-opportunity
+create-opportunity
+update-opportunity
+delete-opportunity
+
+list-activity      (same for activity)
+get-activity
+create-activity
+update-activity
+delete-activity
+
+list-shared        (same for shared fields)
+get-shared
+create-shared
+update-shared
+delete-shared
+```
+
+### webhooks
+Subscribe to real-time events.
+```
+list    List webhook subscriptions
+get     Get a webhook by ID
+create  Create a webhook (specify events array)
+update  Update a webhook
+delete  Delete a webhook
+```
+
+**Available webhook events:** `created.lead`, `updated.lead`, `deleted.lead`, `created.contact`, `updated.contact`, `deleted.contact`, `created.opportunity`, `updated.opportunity`, `deleted.opportunity`, `created.note`, `created.call`, `completed.call`, `created.email`, `created.sms`, `created.task`, `completed.task`
+
+### sequences
+Manage automated outreach sequences.
+```
+list               List sequences
+get                Get a sequence by ID
+create             Create a sequence
+update             Update a sequence
+delete             Delete a sequence
+subscribe          Subscribe a contact to a sequence
+list-subscriptions List sequence subscriptions
+```
+
+### email-templates
+Manage reusable email templates.
+```
+list    List email templates
+get     Get a template by ID
+create  Create an email template
+update  Update a template
+delete  Delete a template
+render  Render a template with lead/contact variable substitution
+```
+
+### sms-templates
+Manage SMS templates.
+```
+list    List SMS templates
+get     Get a template by ID
+create  Create an SMS template
+update  Update a template
+delete  Delete a template
+```
+
+### smart-views
+Manage smart views (saved filtered views).
+```
+list    List smart views
+get     Get a smart view by ID
+create  Create a smart view
+update  Update a smart view
+delete  Delete a smart view
+```
+
+### reports
+Sales analytics and reporting.
+```
+activity-metrics  Get activity metrics for a date range
+activity-report   Get detailed activity report (POST)
+funnel            Get pipeline funnel totals
+```
+
+### phone-numbers
+Manage provisioned phone numbers.
+```
+list    List phone numbers
+get     Get a phone number by ID
+update  Update a phone number
+delete  Delete a phone number
+```
+
+### connected-accounts
+Manage connected email accounts.
+```
+list  List connected accounts
+get   Get a connected account by ID
+```
+
+### organizations
+Manage the organization (top-level account).
+```
+get     Get organization by ID
+update  Update organization settings
+```
+
+### groups
+Manage user groups (teams).
+```
+list    List groups
+get     Get a group by ID
+create  Create a group
+update  Update a group
+delete  Delete a group
+```
+
+### roles
+Manage user roles.
+```
+list  List roles
+get   Get a role by ID
+```
+
+### exports
+Async data exports.
+```
+list                 List exports
+get                  Get export status and download URL
+create-lead          Start a lead export
+create-opportunity   Start an opportunity export
+```
+
+### unsubscribe
+Manage email unsubscribe list.
+```
+list    List unsubscribed emails
+add     Add an email to the unsubscribe list
+delete  Remove an email from the unsubscribe list
+```
+
+---
+
+## Common Workflows for Agents
+
+### Create and qualify a lead
+```bash
+# 1. Create the lead
+close leads create --name "Acme Corp" --url "https://acme.com"
+# → {"id":"lead_abc123","display_name":"Acme Corp",...}
+
+# 2. Add a contact
+close contacts create --lead-id lead_abc123 --name "Jane Doe" \
+  --emails '[{"email":"jane@acme.com","type":"office"}]' \
+  --phones '[{"phone":"+14155551234","type":"mobile"}]'
+
+# 3. Create an opportunity
+close opportunities create --lead-id lead_abc123 \
+  --note "Enterprise deal" --value 50000 --value-period one_time \
+  --confidence 40 --close-date "2025-06-30"
+
+# 4. Add a note
+close notes create --lead-id lead_abc123 --note "Intro call went well, demo scheduled"
+```
+
+### Log a call and create follow-up task
+```bash
+# Log the call
+close calls create --lead-id lead_abc123 --direction outbound \
+  --duration 1800 --note "Discussed pricing and timeline"
+
+# Create follow-up task
+close tasks create --lead-id lead_abc123 \
+  --text "Send proposal" --type email \
+  --due-date "2025-04-07T09:00:00"
+```
+
+### Move a deal through the pipeline
+```bash
+# Check current pipeline stages
+close opportunity-statuses list
+
+# Move opportunity to next stage
+close opportunities update oppo_abc123 --status-id "stat_demo_scheduled"
+
+# Won it!
+close opportunities update oppo_abc123 --status-id "stat_won" --confidence 100
+```
+
+### Set up a webhook for real-time events
+```bash
+# Create webhook
+close webhooks create \
+  --url "https://your-endpoint.com/close-hook" \
+  --events '["created.lead","updated.opportunity","created.call"]'
+
+# List active webhooks
+close webhooks list
+```
+
+### Enroll a contact in a sequence
+```bash
+# List available sequences
+close sequences list
+
+# Subscribe the contact
+close sequences subscribe \
+  --sequence-id seq_abc123 \
+  --contact-id cont_abc123
+```
+
+### Advanced lead search
+```bash
+# Find all leads with status "Potential"
+close leads list --query "status:Potential" --limit 100
+
+# Advanced search with full query DSL
+close leads search --query '{
+  "type": "and",
+  "queries": [
+    {
+      "type": "field",
+      "field": {"type": "regular", "field_name": "status_label"},
+      "negate": false,
+      "condition": {"type": "text", "mode": "equals", "value": "Potential"}
+    }
+  ]
+}'
+```
+
+### Export leads to CSV
+```bash
+# Start the export
+close exports create-lead --format csv
+# → {"id":"export_abc123","status":"pending",...}
+
+# Poll until ready
+close exports get export_abc123
+# → {"id":"export_abc123","status":"completed","download_url":"https://..."}
+
+# Download
+curl -o leads.csv "https://..."
+```
+
+### Check pipeline health
+```bash
+# Get funnel report
+close reports funnel --pipeline-id pipe_abc123 --date-range this_month
+
+# Get activity metrics for the team
+close reports activity-metrics --date-range this_week
+```
+
+---
+
+## Pagination
+
+List commands support offset-based pagination:
+
+```bash
+# First page (25 items)
+close leads list --limit 25
+
+# Next page
+close leads list --limit 25 --skip 25
+
+# Third page
+close leads list --limit 25 --skip 50
+```
+
+---
+
+## Custom Fields
+
+Close CRM supports per-object custom fields. Set them using the `--custom` option with a JSON object where keys are custom field IDs:
+
+```bash
+# Set custom fields on create
+close leads create --name "Acme Corp" --custom '{"cf_budget":"500000","cf_industry":"SaaS"}'
+
+# Update custom fields
+close leads update lead_abc123 --custom '{"cf_budget":"750000"}'
+
+# List available custom fields to find their IDs
+close custom-fields list-lead
+```
+
+---
+
+## MCP Server (for Claude, Cursor, VS Code)
+
+The CLI includes a built-in MCP server exposing all commands as tools:
+
+```bash
+close mcp
+```
+
+MCP config for Claude Desktop / Cursor:
+```json
+{
+  "mcpServers": {
+    "close": {
+      "command": "npx",
+      "args": ["close-crm-cli", "mcp"],
+      "env": {
+        "CLOSE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+```json
+{
+  "mcpServers": {
+    "close": {
+      "command": "close",
+      "args": ["mcp"],
+      "env": {
+        "CLOSE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tips for AI Agents
+
+1. **Always use `--help`** on a group before guessing subcommand names
+2. **Parse JSON output** directly — it's machine-readable by default
+3. **Check exit codes** — 0 means success, 1 means error
+4. **Use `--fields`** to reduce output size (e.g. `--fields id,display_name`)
+5. **Use `--quiet`** when you only care about success/failure
+6. **Use `--pretty`** for human-readable JSON
+7. **Lead IDs** look like `lead_abc123`, contact IDs like `cont_abc123`, etc.
+8. **Custom field values** are set using `--custom '{"cf_fieldid":"value"}'`
+9. **Rate limits** are handled automatically with exponential backoff
+10. **All activity commands** share the same endpoint patterns: `/activity/call/`, `/activity/note/`, `/activity/email/`, `/activity/sms/`, `/activity/meeting/`
+11. **Sequence subscriptions** connect a contact to a sequence; check status with `sequences list-subscriptions --contact-id <id>`
+12. **Exports are async** — poll `exports get <id>` until `status === "completed"`, then download from `download_url`

package/CLAUDE.md

@@ -0,0 +1,148 @@
+# CLAUDE.md — Developer Guide for close-crm-cli
+
+## Architecture Overview
+
+This project follows the **CommandDefinition** pattern used across all bcharleson CLI tools:
+
+- **One `CommandDefinition` object** = one CLI subcommand + one MCP tool
+- All commands live in `src/commands/` grouped by resource
+- `src/commands/index.ts` is the single registry — add commands here
+- The MCP server (`src/mcp/server.ts`) auto-registers all commands from `allCommands[]`
+- CLI registration (`registerAllCommands()`) also loops over `allCommands[]`
+
+## Adding a New Command
+
+1. Create `src/commands/{group}/{subcommand}.ts`
+2. Export a `CommandDefinition` object
+3. Import and add it to `allCommands[]` in `src/commands/index.ts`
+
+That's it — the command automatically appears in both the CLI and the MCP server.
+
+### Command Template
+
+```typescript
+import { z } from 'zod';
+import type { CommandDefinition } from '../../core/types.js';
+import { executeCommand } from '../../core/handler.js';
+
+export const resourceActionCommand: CommandDefinition = {
+  name: 'resource_action',          // snake_case, unique MCP tool name
+  group: 'resource',                // CLI group name (kebab-case)
+  subcommand: 'action',             // CLI subcommand name
+  description: 'What this does.',   // Used in --help and MCP
+
+  inputSchema: z.object({
+    id: z.string().describe('Resource ID'),
+    name: z.string().optional().describe('Name'),
+  }),
+
+  cliMappings: {
+    args: [{ field: 'id', name: 'id', required: true }],  // positional args
+    options: [
+      { field: 'name', flags: '--name <name>', description: 'Name' },
+    ],
+  },
+
+  endpoint: { method: 'PUT', path: '/resource/{id}/' },
+
+  fieldMappings: {
+    id: 'path',    // goes in URL path
+    name: 'body',  // goes in request body
+    // 'query' → goes in query string
+  },
+
+  handler: (input, client) => executeCommand(resourceActionCommand, input, client),
+};
+```
+
+For handlers with complex logic (like applying defaults), use an async function directly:
+
+```typescript
+handler: async (input, client) => {
+  const body: Record<string, any> = { required_field: input.required_field };
+  if (input.optional) body.optional = input.optional;
+  return client.post('/resource/', body);
+},
+```
+
+## Close CRM API Specifics
+
+- **Base URL:** `https://api.close.com/api/v1`
+- **Auth:** HTTP Basic Auth — `Authorization: Basic base64("apikey:")` (implemented in `CloseClient`)
+- **HTTP methods:** GET, POST, PUT, DELETE (no PATCH)
+- **Pagination:** `_limit` + `_skip` params, response has `data[]` + `has_more`
+- **Rate limits:** 429 → read `rate_reset` header (Unix timestamp), sleep until reset
+- **Custom fields:** Set as `custom.{FIELD_ID}` in request body
+
+## Project Structure
+
+```
+src/
+  index.ts             CLI entry point (Commander.js)
+  mcp.ts               MCP server entry point
+  core/
+    types.ts            CommandDefinition, CloseClient, GlobalOptions interfaces
+    client.ts           HTTP client (Basic Auth, retry, rate limiting)
+    config.ts           ~/.close/config.json management
+    auth.ts             API key resolution (flag > env > config)
+    errors.ts           Typed error classes
+    output.ts           JSON output formatting
+    handler.ts          executeCommand() — builds HTTP requests from CommandDefinitions
+  mcp/
+    server.ts           MCP server (loops allCommands[], registers as MCP tools)
+  commands/
+    index.ts            allCommands[] registry + registerAllCommands()
+    auth/               login, logout (special — no API client)
+    mcp/                mcp command registration
+    leads/              list, get, create, update, delete, merge, search
+    contacts/           list, get, create, update, delete
+    opportunities/      list, get, create, update, delete
+    tasks/              list, get, create, update, delete, bulk-update
+    activities/         list (unified stream)
+    calls/              list, get, create, update, delete
+    notes/              list, get, create, update, delete
+    emails/             list, get, create, update, delete
+    sms/                list, get, create, delete
+    meetings/           list, get, update, delete
+    users/              me, list, get, availability
+    pipelines/          list, get, create, update, delete
+    lead-statuses/      list, get, create, update, delete
+    opportunity-statuses/ list, get, create, update, delete
+    custom-fields/      index.ts (factory-generated, 25 commands)
+    webhooks/           list, get, create, update, delete
+    sequences/          list, get, create, update, delete, subscribe, list-subscriptions
+    email-templates/    list, get, create, update, delete, render
+    sms-templates/      list, get, create, update, delete
+    smart-views/        list, get, create, update, delete
+    reports/            activity-metrics, activity-report, funnel
+    phone-numbers/      list, get, update, delete
+    connected-accounts/ list, get
+    organizations/      get, update
+    groups/             list, get, create, update, delete
+    roles/              list, get
+    exports/            list, get, create-lead, create-opportunity
+    unsubscribe/        list, add, delete
+```
+
+## Build & Dev
+
+```bash
+npm install
+npm run dev -- leads list          # Run CLI in dev mode
+npm run dev:mcp                    # Run MCP server in dev mode
+npm run build                      # Build to dist/
+npm run typecheck                  # TypeScript type check
+```
+
+## Zod Version Note
+
+This project uses Zod v3 (`"zod": "^3.24.0"`). The `inputSchema.shape` property is used in the MCP server to extract the Zod shape for tool registration. Do not upgrade to Zod v4 without testing the MCP server registration.
+
+## Conventions
+
+- Use `z.preprocess()` for JSON array/object fields (handles both string-encoded and parsed values)
+- Use `z.coerce.number()` for numeric CLI options (Commander.js passes everything as strings)
+- Boolean CLI flags: use `z.preprocess()` with `v === 'true'` → `true` pattern
+- All `handler` functions must return `Promise<unknown>`
+- Use `encodeURIComponent()` for path parameters in custom handlers
+- Keep command descriptions concise but complete — they appear in MCP tool descriptions seen by AI models