sendcraft-cli 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,551 @@
+# sendcraft-cli
+
+<p align="center">
+  <img src="https://sendcraft.online/logo.png" alt="SendCraft" width="72" />
+</p>
+
+<p align="center">
+  <strong>Official CLI for <a href="https://sendcraft.online">SendCraft</a> — send emails, manage campaigns, verify domains, and more from your terminal.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sendcraft-cli"><img src="https://img.shields.io/npm/v/sendcraft-cli?color=6366f1&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/sendcraft-cli"><img src="https://img.shields.io/npm/dm/sendcraft-cli?color=10b981&label=downloads" alt="downloads" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D14-brightgreen" alt="node" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT" />
+</p>
+
+---
+
+```
+  ███████╗███████╗███╗   ██╗██████╗  ██████╗██████╗  █████╗ ███████╗████████╗
+  ██╔════╝██╔════╝████╗  ██║██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝
+  ███████╗█████╗  ██╔██╗ ██║██║  ██║██║     ██████╔╝███████║█████╗     ██║
+  ╚════██║██╔══╝  ██║╚██╗██║██║  ██║██║     ██╔══██╗██╔══██║██╔══╝     ██║
+  ███████║███████╗██║ ╚████║██████╔╝╚██████╗██║  ██║██║  ██║██║        ██║
+  ╚══════╝╚══════╝╚═╝  ╚═══╝╚═════╝  ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝
+```
+
+## Features
+
+- 📧 **Send emails** directly from the terminal
+- 📊 **View stats** — opens, clicks, bounces, delivery rates
+- 📣 **Manage campaigns** — list and send with optional scheduling
+- 👥 **Manage subscribers** — list, add, remove with tag support
+- 🌐 **Domain verification** — add domains and see DNS records to configure
+- 🔑 **API key management** — create, list, revoke with permission scopes
+- 🔥 **IP warmup status** — animated progress bar, daily limits at a glance
+- 🤖 **MCP setup** — one-command config for Claude Desktop AI agent integration
+- 🎨 **Beautiful output** — gradient colors, spinners, tables, JSON mode
+- 🖥️ **Interactive TUI** — arrow-key menu when launched with no arguments
+
+---
+
+## Installation
+
+```bash
+npm install -g sendcraft-cli
+```
+
+Or run without installing:
+
+```bash
+npx sendcraft-cli
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Log in (opens a menu — browser redirect or email+password)
+sendcraft login
+
+# 2. Send your first email
+sendcraft send --to user@example.com --subject "Hello!" --html "<h1>It works!</h1>"
+
+# 3. Check your stats
+sendcraft emails stats
+```
+
+---
+
+## Authentication
+
+```bash
+sendcraft login                              # Interactive login (browser or email+password)
+sendcraft login --browser                   # Open dashboard to copy an API key
+sendcraft login --api                       # Sign in with email & password
+sendcraft logout                            # Remove saved API key from this machine
+```
+
+### Browser flow
+`sendcraft login --browser` opens `{your-base-url}/dashboard/settings` in your default browser.
+Create or copy an existing API key from the **API Keys** tab, then paste it back in the terminal.
+The key is verified against the API before being saved.
+
+### Email & Password flow
+`sendcraft login --api` prompts for your email and password, signs you in via the API, then
+automatically creates a named **"CLI"** key with full access and saves it locally.
+
+---
+
+## Configuration
+
+```bash
+sendcraft config init                        # Interactive setup wizard
+sendcraft config set-key <apiKey>            # Set your API key manually
+sendcraft config set-url <url>               # Override API base URL (self-hosted)
+sendcraft config show                        # Print current config
+```
+
+Config is stored in `~/.sendcraft/config.json`.
+
+You can also use an environment variable — it takes precedence over the config file:
+
+```bash
+export SENDCRAFT_API_KEY=sc_live_xxxxxxxxxxxxxxxx
+```
+
+---
+
+## Commands
+
+### `sendcraft send` — Send an email
+
+```bash
+sendcraft send --to user@example.com --subject "Hello" --html "<h1>Hi</h1>"
+```
+
+| Flag | Description |
+|------|-------------|
+| `-t, --to <email>` | **Required.** Recipient email address |
+| `-s, --subject <text>` | **Required.** Email subject line |
+| `-H, --html <html>` | HTML body (required if no `--text`) |
+| `-T, --text <text>` | Plain text body (required if no `--html`) |
+| `-f, --from <email>` | From address (uses account default if omitted) |
+| `-r, --reply-to <email>` | Reply-To address |
+| `--json` | Output raw JSON response |
+
+**Examples:**
+
+```bash
+# Send HTML email
+sendcraft send -t alice@example.com -s "Welcome!" -H "<h1>Hey Alice 👋</h1>"
+
+# Send plain text
+sendcraft send -t bob@example.com -s "Quick note" -T "Hey Bob, just checking in."
+
+# Send with custom from + reply-to
+sendcraft send -t user@example.com -s "Hi" -H "<p>Hello</p>" \
+  -f hello@myapp.com -r support@myapp.com
+
+# Output JSON (good for scripting)
+sendcraft send -t user@example.com -s "Test" -T "Body" --json
+```
+
+---
+
+### `sendcraft emails` — Manage emails
+
+```bash
+sendcraft emails list                        # List recent sent emails
+sendcraft emails stats                       # Delivery stats summary
+sendcraft emails get <emailId>               # Details for a single email
+```
+
+#### `emails list`
+
+```bash
+sendcraft emails list
+sendcraft emails list --limit 50
+sendcraft emails list --status delivered
+sendcraft emails list --page 2 --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --page <n>` | Page number (default: 1) |
+| `-l, --limit <n>` | Items per page (default: 20) |
+| `--status <s>` | Filter: `sent`, `delivered`, `failed`, `scheduled` |
+| `--json` | Output raw JSON |
+
+#### `emails stats`
+
+```bash
+sendcraft emails stats
+```
+
+Shows total sent, delivered, opened, clicked, bounced, failed, open rate, and click rate.
+
+#### `emails get`
+
+```bash
+sendcraft emails get 64f2a1b3c9e4d50012345678
+sendcraft emails get 64f2a1b3c9e4d50012345678 --json
+```
+
+---
+
+### `sendcraft campaigns` — Manage campaigns
+
+```bash
+sendcraft campaigns list                     # List all campaigns
+sendcraft campaigns send <campaignId>        # Send a campaign now
+sendcraft campaigns send <campaignId> --schedule 2025-12-25T09:00:00Z
+```
+
+| Flag | Description |
+|------|-------------|
+| `--schedule <isoDate>` | Schedule for a specific time (ISO 8601) |
+| `--json` | Output raw JSON |
+
+**Examples:**
+
+```bash
+# List campaigns
+sendcraft campaigns list
+
+# Send immediately
+sendcraft campaigns send 64f2a1b3c9e4d50012345678
+
+# Schedule for Christmas morning
+sendcraft campaigns send 64f2a1b3c9e4d50012345678 \
+  --schedule 2025-12-25T09:00:00Z
+```
+
+> Create campaigns in the [dashboard](https://sendcraft.online/dashboard/campaigns) — the CLI handles sending and scheduling.
+
+---
+
+### `sendcraft subscribers` — Manage subscribers
+
+```bash
+sendcraft subscribers list                           # List all subscribers
+sendcraft subscribers add <email> --list <listId>    # Add a subscriber
+sendcraft subscribers remove <subscriberId>          # Remove a subscriber
+```
+
+#### `subscribers list`
+
+```bash
+sendcraft subscribers list
+sendcraft subscribers list --status active --limit 50
+sendcraft subscribers list --page 3 --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --page <n>` | Page number (default: 1) |
+| `-l, --limit <n>` | Items per page (default: 20) |
+| `--status <s>` | Filter: `active`, `pending`, `unsubscribed` |
+| `--json` | Output raw JSON |
+
+#### `subscribers add`
+
+```bash
+sendcraft subscribers add alice@example.com --list <listId>
+sendcraft subscribers add bob@example.com --list <listId> \
+  --first-name Bob --last-name Smith --tags "vip,beta"
+```
+
+| Flag | Description |
+|------|-------------|
+| `--list <listId>` | **Required.** Target email list ID |
+| `--first-name <name>` | First name |
+| `--last-name <name>` | Last name |
+| `--tags <tags>` | Comma-separated tags |
+| `--json` | Output raw JSON |
+
+#### `subscribers remove`
+
+```bash
+sendcraft subscribers remove 64f2a1b3c9e4d50012345678
+```
+
+---
+
+### `sendcraft domains` — Manage sender domains
+
+```bash
+sendcraft domains list                       # List all domains
+sendcraft domains add <domain>               # Add a new domain + show DNS records
+sendcraft domains verify <domainId>          # Re-check DNS verification
+sendcraft domains records <domainId>         # Show DNS records to configure
+```
+
+**Full workflow:**
+
+```bash
+# 1. Add your domain
+sendcraft domains add mail.myapp.com
+
+# Output shows DNS records to add:
+#   SPF   — TXT   _spf.mail.myapp.com
+#   DKIM  — TXT   sendcraft._domainkey.mail.myapp.com
+#   DMARC — TXT   _dmarc.mail.myapp.com
+#   BIMI  — TXT   default._bimi.mail.myapp.com (optional)
+
+# 2. Add those records in your DNS provider, then:
+sendcraft domains verify <domainId>
+
+# Check again anytime:
+sendcraft domains records <domainId>
+```
+
+> DNS propagation can take up to 48 hours.
+
+---
+
+### `sendcraft keys` — Manage API keys
+
+```bash
+sendcraft keys list                          # List all API keys
+sendcraft keys create <name>                 # Create a new key
+sendcraft keys revoke <keyId>                # Permanently revoke a key
+```
+
+#### `keys create`
+
+```bash
+# Full access key (default)
+sendcraft keys create "Production"
+
+# Send-only key (cannot manage campaigns, templates, subscribers)
+sendcraft keys create "Frontend App" --permissions sending_access
+
+# Restrict to specific sender domains
+sendcraft keys create "Marketing Tool" --domains "newsletter.myapp.com,promo.myapp.com"
+```
+
+| Flag | Description |
+|------|-------------|
+| `--permissions <type>` | `full_access` (default) or `sending_access` |
+| `--domains <list>` | Comma-separated allowed sender domains |
+| `--json` | Output raw JSON |
+
+> ⚠️ The key is shown **once only**. Copy it immediately.
+
+#### `keys revoke`
+
+```bash
+sendcraft keys revoke 64f2a1b3c9e4d50012345678
+```
+
+---
+
+### `sendcraft warmup` — IP warmup status
+
+```bash
+sendcraft warmup
+sendcraft warmup --json
+```
+
+Shows an animated progress bar, current warmup day, today's send count vs daily limit, and percentage complete.
+
+**Warmup schedule:**
+
+| Day | Daily limit |
+|-----|-------------|
+| 1   | 50 |
+| 2   | 100 |
+| 3   | 250 |
+| 4   | 500 |
+| 5   | 1,000 |
+| 7   | 3,500 |
+| 14  | 7,500 |
+| 21  | 15,000 |
+| 30  | 35,000 |
+| 45  | 75,000 |
+| 60+ | **Unlimited** |
+
+---
+
+### `sendcraft mcp` — MCP server for AI agents
+
+Connect SendCraft to **Claude Desktop** (or any MCP-compatible AI agent) so it can send emails on your behalf — no API calls needed.
+
+```bash
+sendcraft mcp info                           # Print Claude Desktop config snippet
+sendcraft mcp install                        # Install sendcraft-mcp globally
+```
+
+#### Setup in 2 steps
+
+```bash
+# 1. Install the MCP server
+sendcraft mcp install
+
+# 2. Print the config to add to Claude Desktop
+sendcraft mcp info
+```
+
+Paste the printed JSON into:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+After restarting Claude Desktop, you can say:
+
+> *"Send a welcome email to alice@example.com"*
+
+...and Claude will call `sendcraft_send_email` natively.
+
+**Available MCP tools:** `sendcraft_send_email`, `sendcraft_batch_send`, `sendcraft_list_emails`, `sendcraft_get_stats`, `sendcraft_list_campaigns`, `sendcraft_send_campaign`, `sendcraft_list_subscribers`, `sendcraft_add_subscriber`, `sendcraft_list_templates`, `sendcraft_list_domains`, `sendcraft_verify_domain`, `sendcraft_get_warmup_status`, and more.
+
+---
+
+## Interactive Mode
+
+Launch `sendcraft` with no arguments to open a full-screen arrow-key TUI:
+
+```bash
+sendcraft
+```
+
+```
+  ✦ SendCraft CLI v1.1.0
+
+  ? What would you like to do?
+  ❯ 📧  Send Email
+    📋  Emails
+    📣  Campaigns
+    👥  Subscribers
+    🌐  Domains
+    🔑  API Keys
+    🔥  IP Warmup
+    🤖  MCP Setup
+    🔐  Login
+    ⚙️   Config
+    ✗   Exit
+```
+
+Navigate with **↑ ↓** arrow keys, select with **Enter**.
+
+---
+
+## JSON Output
+
+Every command supports `--json` for machine-readable output — useful in shell scripts and CI/CD pipelines:
+
+```bash
+# Get email stats as JSON
+sendcraft emails stats --json | jq '.stats.openRate'
+
+# List campaigns as JSON
+sendcraft campaigns list --json | jq '.campaigns[].name'
+
+# Pipe email ID after sending
+ID=$(sendcraft send -t x@y.com -s "Hi" -T "Hello" --json | jq -r '.emailId')
+echo "Sent: $ID"
+```
+
+---
+
+## CI/CD Usage
+
+Use `SENDCRAFT_API_KEY` as an environment variable — no config file needed:
+
+```yaml
+# GitHub Actions example
+- name: Send deployment notification
+  env:
+    SENDCRAFT_API_KEY: ${{ secrets.SENDCRAFT_API_KEY }}
+  run: |
+    npx sendcraft-cli send \
+      --to team@myapp.com \
+      --subject "🚀 Deployed to production" \
+      --html "<p>Deploy complete. Commit: ${{ github.sha }}</p>"
+```
+
+```bash
+# Shell script
+export SENDCRAFT_API_KEY=sc_live_xxx
+
+npx sendcraft-cli send \
+  --to "$RECIPIENT" \
+  --subject "Build $BUILD_NUMBER passed" \
+  --text "All tests passed. See $BUILD_URL"
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SENDCRAFT_API_KEY` | API key — overrides config file |
+| `SENDCRAFT_API_URL` | API base URL — for self-hosted deployments |
+
+---
+
+## Self-Hosted / Custom API URL
+
+If you run your own SendCraft instance:
+
+```bash
+sendcraft config set-url https://api.myinstance.com/api
+# or
+export SENDCRAFT_API_URL=https://api.myinstance.com/api
+```
+
+---
+
+## All Commands at a Glance
+
+```
+sendcraft                                   Interactive TUI (no args)
+
+sendcraft login                             Log in (browser or email+password)
+sendcraft login --browser                   Open dashboard to copy API key
+sendcraft login --api                       Sign in with email & password
+sendcraft logout                            Remove saved API key
+
+sendcraft config init                       Interactive config wizard
+sendcraft config set-key <key>              Set API key manually
+sendcraft config set-url <url>              Set API base URL
+sendcraft config show                       Show current config
+
+sendcraft send                              Send a transactional email
+  -t <email>  -s <subject>  -H <html>
+
+sendcraft emails list                       List sent emails
+sendcraft emails stats                      Delivery stats
+sendcraft emails get <id>                   Single email details
+
+sendcraft campaigns list                    List campaigns
+sendcraft campaigns send <id>               Send / schedule a campaign
+
+sendcraft subscribers list                  List subscribers
+sendcraft subscribers add <email>           Add a subscriber
+sendcraft subscribers remove <id>           Remove a subscriber
+
+sendcraft domains list                      List domains
+sendcraft domains add <domain>              Add domain + show DNS records
+sendcraft domains verify <id>               Trigger DNS check
+sendcraft domains records <id>              Show DNS records
+
+sendcraft keys list                         List API keys
+sendcraft keys create <name>                Create API key
+sendcraft keys revoke <id>                  Revoke API key
+
+sendcraft warmup                            IP warmup status
+
+sendcraft mcp info                          Claude Desktop config snippet
+sendcraft mcp install                       Install sendcraft-mcp globally
+```
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`sendcraft-sdk`](https://www.npmjs.com/package/sendcraft-sdk) | Node.js / TypeScript SDK |
+| [`sendcraft-sdk` (PyPI)](https://pypi.org/project/sendcraft-sdk/) | Python SDK |
+| [`sendcraft-mcp`](https://www.npmjs.com/package/sendcraft-mcp) | MCP server for AI agents |
+
+---
+
+## License
+
+MIT © [SendCraft](https://sendcraft.online)

package/bin/sendcraft.js

@@ -6,12 +6,30 @@ const { program } = require('commander');
 const chalk = require('chalk');
 const pkg = require('../package.json');
 
-// Sub-commands
 program
   .name('sendcraft')
   .description('Official SendCraft CLI')
   .version(pkg.version, '-v, --version');
 
+program.addCommand(require('../lib/commands/login'));
+
+// sendcraft logout — convenience alias that clears the stored API key
+const { Command } = require('commander');
+const logoutCmd = new Command('logout')
+  .description('Remove the stored API key from this machine')
+  .action(() => {
+    const { load, save, CONFIG_FILE } = require('../lib/config');
+    const cfg = load();
+    if (!cfg.api_key) {
+      console.log(chalk.yellow('  ⚠  No API key stored — already logged out.'));
+      return;
+    }
+    delete cfg.api_key;
+    save(cfg);
+    console.log(chalk.green('  ✓ ') + chalk.bold('Logged out.') + chalk.dim(' Key removed from ' + CONFIG_FILE));
+  });
+program.addCommand(logoutCmd);
+
 program.addCommand(require('../lib/commands/config'));
 program.addCommand(require('../lib/commands/send'));
 program.addCommand(require('../lib/commands/emails'));
@@ -20,17 +38,17 @@ program.addCommand(require('../lib/commands/subscribers'));
 program.addCommand(require('../lib/commands/domains'));
 program.addCommand(require('../lib/commands/keys'));
 program.addCommand(require('../lib/commands/warmup'));
+program.addCommand(require('../lib/commands/mcp'));
 
-// Friendly error on unknown command
 program.on('command:*', (args) => {
-  console.error(chalk.red(`Unknown command: ${args[0]}`));
-  console.error('Run ' + chalk.bold('sendcraft --help') + ' to see available commands.');
+  console.error(chalk.red(`  ✗ Unknown command: ${args[0]}`));
+  console.error('  Run ' + chalk.bold('sendcraft --help') + ' for available commands.');
   process.exit(1);
 });
 
-program.parse(process.argv);
-
-// Show help if called with no args
+// Interactive mode when called with no args
 if (process.argv.length < 3) {
-  program.help();
+  require('../lib/interactive')();
+} else {
+  program.parse(process.argv);
 }

package/lib/banner.js

@@ -0,0 +1,53 @@
+/**
+ * Animated banner shown on `sendcraft` with no args.
+ */
+const figlet = require('figlet');
+const _grad = require('gradient-string'); const gradient = _grad.default || _grad;
+const _boxen = require('boxen'); const boxen = _boxen.default || _boxen;
+const chalk = require('chalk');
+
+const sendcraftGradient = gradient(['#6366f1', '#8b5cf6', '#ec4899']);
+const successGradient   = gradient(['#10b981', '#3b82f6']);
+
+function banner(version) {
+  const text = figlet.textSync('SendCraft', {
+    font: 'Big',
+    horizontalLayout: 'default',
+    verticalLayout: 'default',
+  });
+
+  console.log(sendcraftGradient.multiline(text));
+
+  const box = boxen(
+    `${chalk.bold('SendCraft CLI')}  ${chalk.dim('v' + version)}\n` +
+    `${chalk.dim('Official CLI for the SendCraft email platform')}\n\n` +
+    `${chalk.cyan('sendcraft config init')}  ${chalk.dim('→ Setup your API key')}\n` +
+    `${chalk.cyan('sendcraft send')}         ${chalk.dim('→ Send an email')}\n` +
+    `${chalk.cyan('sendcraft --help')}       ${chalk.dim('→ All commands')}`,
+    {
+      padding: 1,
+      margin: { top: 0, bottom: 1, left: 0, right: 0 },
+      borderStyle: 'round',
+      borderColor: 'magenta',
+    }
+  );
+  console.log(box);
+}
+
+function printSuccess(msg) {
+  console.log(successGradient('  ✓ ') + chalk.bold(msg));
+}
+
+function printError(msg) {
+  console.error(chalk.red('  ✗ ') + msg);
+}
+
+function printInfo(msg) {
+  console.log(chalk.blue('  ℹ ') + msg);
+}
+
+function printWarn(msg) {
+  console.log(chalk.yellow('  ⚠ ') + msg);
+}
+
+module.exports = { banner, printSuccess, printError, printInfo, printWarn, sendcraftGradient, successGradient };