@anonymilyhq/cli 1.0.3 → 1.0.4

package/README.md

@@ -1,54 +1,212 @@
+<div align="center">
+
 # @anonymilyhq/cli
 
-The official CLI for [Anonymily](https://anonymily.com), a simple and powerful webhook relayer.
+**The official CLI for [Anonymily](https://anonymily.com) — forward webhooks from the cloud straight to your localhost.**
+
+[![npm version](https://img.shields.io/npm/v/@anonymilyhq/cli.svg?color=emerald&label=npm)](https://www.npmjs.com/package/@anonymilyhq/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen.svg?logo=node.js)](https://nodejs.org/)
+
+</div>
+
+---
+
+## What is it?
+
+The Anonymily CLI connects to your live webhook endpoint on `api.anonymily.com` via a Server-Sent Events (SSE) stream and forwards every incoming request — with the exact same method, headers, query params, and body — to a port on your local machine.
+
+No tunnels, no sign-ups required to start. Just one command.
+
+> **Pro tip:** Create a free account at [anonymily.com](https://anonymily.com) and claim your endpoint to keep the same URL across sessions and unlock 500 requests / 30-day history retention with a Pro subscription.
 
-With the Anonymily CLI, you can forward webhooks directly from Anonymily to your local machine, allowing you to easily test, inspect, and debug incoming webhooks in real-time.
+---
 
 ## Installation
 
-You can install the CLI globally using npm:
+**Run instantly via npx (no install required):**
+```bash
+npx @anonymilyhq/cli listen 3000
+```
 
+**Or install globally:**
 ```bash
 npm install -g @anonymilyhq/cli
 ```
 
-Alternatively, you can run it directly using `npx`:
+---
+
+## Quick Start
 
 ```bash
-npx @anonymilyhq/cli listen 8080
+# Start listening — generates a random endpoint ID automatically
+npx @anonymilyhq/cli listen 3000
+
+# Output:
+# 🚀 Anonymily CLI is running!
+# Forwarding: https://api.anonymily.com/h/xk92bzte  ➔  http://127.0.0.1:3000
+# Waiting for requests to arrive...
 ```
 
-## Usage
+Send a test payload:
+```bash
+curl -X POST https://api.anonymily.com/h/xk92bzte \
+  -H "Content-Type: application/json" \
+  -d '{"event": "payment.success"}'
+```
 
-Start listening for incoming webhooks and forward them to a specific port on your localhost:
+You'll see in the CLI:
+```
+[12:01:45] ⚡ Incoming POST request...
+  └─ Forwarded to localhost | Status: 200
+```
+
+---
+
+## Commands
+
+### `listen <port>`
+
+Listen for incoming webhooks and forward them to a local port.
+
+```bash
+anonymily listen <port> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `<port>` | **Required.** Local port to forward to (e.g. `3000`, `8080`) |
+| `-i, --id <id>` | Use a custom, memorable endpoint name (e.g. `stripe-test`) |
+| `--pro` | Register the hook as Pro-tier (legacy). Requires `--id` and a configured Pro API key |
 
+**Examples:**
 ```bash
-anonymily listen <port>
+# Random endpoint ID (ephemeral)
+npx @anonymilyhq/cli listen 3000
+
+# Custom named endpoint → api.anonymily.com/h/stripe-dev
+npx @anonymilyhq/cli listen 3000 --id stripe-dev
+
+# Pro-tier named endpoint (legacy hook-based Pro)
+npx @anonymilyhq/cli listen 3000 --id stripe-dev --pro
 ```
 
-### Example
+---
 
-To forward webhooks to your local development server running on port `3000` with a randomly generated endpoint ID:
+### `config set-key <key>`
+
+Save your Pro API key locally so you don't need to export it every session.
 
 ```bash
-anonymily listen 3000
+anonymily config set-key <your-pro-api-key>
 ```
 
-To specify a custom endpoint ID (e.g., `stripe-test`) so that your URL is consistently `api.anonymily.com/h/stripe-test`:
+The key is stored in `~/.anonymily/config.json`. You can also set it via environment variable:
 
 ```bash
-anonymily listen 3000 --id stripe-test
+export PRO_API_KEY=<your-pro-api-key>
 ```
 
-1. The CLI will output a webhook connection URL and automatically connect via Server-Sent Events.
-2. Send your webhooks to the provided URL.
-3. The CLI will receive the requests natively and forward them precisely to `http://localhost:3000`, preserving exactly the same method, body, queries, and headers.
+---
+
+## Account-Based Pro (Recommended)
+
+The modern way to get Pro limits is via an **account subscription** at [anonymily.com/upgrade](https://anonymily.com/upgrade). This gives your entire account Pro limits (₹750/month) — no per-hook configuration needed.
+
+**Workflow:**
+1. Sign up at [anonymily.com](https://anonymily.com)
+2. Subscribe to Pro at [anonymily.com/upgrade](https://anonymily.com/upgrade)
+3. Open the dashboard, copy your endpoint URL, and claim it to your account
+4. Run the CLI with the same hook ID:
+   ```bash
+   npx @anonymilyhq/cli listen 3000 --id your-claimed-hook
+   ```
+5. All Pro limits apply automatically — 500 requests, 30-day history
+
+---
+
+## How It Works
+
+```
+External Service (Stripe, GitHub, etc.)
+        │
+        │  POST https://api.anonymily.com/h/<hookId>
+        ▼
+  Anonymily Backend (NestJS + Redis + Supabase)
+        │
+        │  SSE broadcast via /stream/<hookId>
+        ▼
+  @anonymilyhq/cli  ──forward──►  http://localhost:<port>
+```
+
+1. The CLI opens a persistent SSE connection to `/stream/<hookId>`
+2. When a webhook arrives, the backend broadcasts it instantly
+3. The CLI receives the event and re-issues the exact same HTTP request to your local port
+4. Method, headers, query params, and body are all preserved 1:1
+
+---
+
+## Tier Comparison
+
+| Feature | Free | Pro |
+|---------|------|-----|
+| Requests stored per hook | 50 | 500 |
+| History retention | 24 hours | 30 days |
+| Custom endpoint ID | ✅ | ✅ |
+| Persistent history in dashboard | ✅ | ✅ |
+| Price | Free | ₹750/month |
+
+---
+
+## Testing Locally
+
+A sample target server is included to test forwarding without a real local app:
+
+```bash
+node sample-target-server.js
+# Listens on http://localhost:4000 and logs all incoming requests
+```
+
+Then in another terminal:
+```bash
+npx @anonymilyhq/cli listen 4000
+```
+
+---
+
+## Troubleshooting
+
+**`Connection refused` when forwarding:**
+- Make sure your local server is actually running on the specified port
+- Test with: `curl http://localhost:<port>`
+
+**Requests arrive in CLI but local server returns errors:**
+- Check the status code logged: `└─ Forwarded to localhost | Status: 500`
+- Review your local server logs for the underlying cause
+
+**CLI doesn't reconnect after network drop:**
+- The CLI uses `eventsource` which auto-reconnects on drops
+- You'll see: `[Network] Connection dropped. Automatically reconnecting...`
+
+**SSE stream appears stuck (no events):**
+- Confirm the hook ID exists: `curl https://api.anonymily.com/history/<hookId>`
+- Ensure you're sending requests to the correct endpoint URL shown in the CLI output
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PRO_API_KEY` | Legacy Pro API key (overrides `~/.anonymily/config.json`) |
+| `ANONYMILY_API_URL` | Override the backend URL (default: `https://api.anonymily.com`) |
 
+---
 
-## Issues
+## Contributing
 
-If you encounter a bug, please create an issue in the main repository or contact our support.
+Issues and pull requests are welcome. Open an issue first to discuss any significant changes.
 
 ## License
 
-MIT
+MIT © [Anonymily](https://anonymily.com)

package/bin/cli.js

@@ -1,25 +1,93 @@
 #!/usr/bin/env node
 
 import { program } from 'commander';
+import pc from 'picocolors';
 import { generateHookId } from '../lib/utils.js';
 import { startForwarding } from '../lib/forwarder.js';
+import { writeConfig, CONFIG_PATH } from '../lib/config.js';
+import {
+  registerProHook,
+  ProApiKeyMissingError,
+  ProApiAuthError,
+  ProApiError,
+} from '../lib/proRegister.js';
+import { logger } from '../lib/logger.js';
 
 // Point this to your live production backend URL
 const API_URL = process.env.ANONYMILY_API_URL || 'https://api.anonymily.com';
 
 program
-    .name('anonymily')
-    .description('Forward webhooks from Anonymily directly to your local machine.')
-    .version('1.0.0');
+  .name('anonymily')
+  .description('Forward webhooks from Anonymily directly to your local machine.')
+  .version('1.0.3');
 
+// ---------------------------------------------------------------------------
+// listen
+// ---------------------------------------------------------------------------
 program
-    .command('listen')
-    .description('Listen for incoming webhooks and forward them to a local port')
-    .argument('<port>', 'Local port to forward to (e.g., 8080)')
-    .option('-i, --id <id>', 'Provide a custom endpoint ID to listen to')
-    .action((port, options) => {
-        const hookId = options.id || generateHookId();
-        startForwarding(API_URL, hookId, parseInt(port, 10));
-    });
-
-program.parse();
+  .command('listen')
+  .description('Listen for incoming webhooks and forward them to a local port')
+  .argument('<port>', 'Local port to forward to (e.g., 8080)')
+  .option('-i, --id <id>', 'Provide a custom endpoint ID to listen to')
+  .option(
+    '--pro',
+    'Register the hook as Pro-tier (requires --id and PRO_API_KEY)',
+  )
+  .action(async (port, options) => {
+    // --pro requires --id
+    if (options.pro && !options.id) {
+      logger.error(
+        pc.bold(
+          '--pro requires --id to specify a persistent hook name.',
+        ),
+      );
+      process.exit(1);
+    }
+
+    const hookId = options.id || generateHookId();
+
+    if (options.pro) {
+      try {
+        await registerProHook(API_URL, hookId);
+      } catch (err) {
+        if (
+          err instanceof ProApiKeyMissingError ||
+          err instanceof ProApiAuthError ||
+          err instanceof ProApiError
+        ) {
+          logger.error(err.message);
+        } else {
+          logger.error(`Unexpected error during Pro registration: ${err.message}`);
+        }
+        process.exit(1);
+      }
+    }
+
+    startForwarding(API_URL, hookId, parseInt(port, 10));
+  });
+
+// ---------------------------------------------------------------------------
+// config
+// ---------------------------------------------------------------------------
+const configCmd = program
+  .command('config')
+  .description('Manage CLI configuration');
+
+configCmd
+  .command('set-key <key>')
+  .description(
+    'Save your Pro API key to ~/.anonymily/config.json',
+  )
+  .action((key) => {
+    if (!key || !key.trim()) {
+      logger.error('API key cannot be empty.');
+      process.exit(1);
+    }
+    writeConfig({ proApiKey: key.trim() });
+    logger.success(
+      `Pro API key saved to ${CONFIG_PATH}`,
+    );
+  });
+
+program.parse();
+

package/lib/config.js

@@ -0,0 +1,70 @@
+/**
+ * lib/config.js
+ *
+ * Read and write the Anonymily CLI config file at ~/.anonymily/config.json.
+ * The config file stores user-scoped settings such as the Pro API key.
+ *
+ * Schema:
+ *   {
+ *     "proApiKey": "<string>"   // Pro subscriber API key
+ *   }
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+/** Absolute path to the config directory. */
+export const CONFIG_DIR = join(homedir(), '.anonymily');
+
+/** Absolute path to the config JSON file. */
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+/**
+ * Read and parse the config file.
+ * Returns an empty object if the file doesn't exist yet.
+ *
+ * @returns {Record<string, unknown>}
+ */
+export function readConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    const raw = readFileSync(CONFIG_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write (merge) key-value pairs into the config file.
+ * Creates the config directory and file if they don't exist.
+ *
+ * @param {Record<string, unknown>} updates
+ */
+export function writeConfig(updates) {
+  const existing = readConfig();
+  const merged = { ...existing, ...updates };
+
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+
+  writeFileSync(CONFIG_PATH, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Retrieve the user's Pro API key.
+ *
+ * Resolution order (highest precedence first):
+ *   1. PRO_API_KEY environment variable
+ *   2. proApiKey field in ~/.anonymily/config.json
+ *
+ * @returns {string | undefined}
+ */
+export function getProApiKey() {
+  if (process.env.PRO_API_KEY) return process.env.PRO_API_KEY;
+  const cfg = readConfig();
+  return typeof cfg.proApiKey === 'string' ? cfg.proApiKey : undefined;
+}
+

package/lib/forwarder.js

@@ -2,6 +2,37 @@ import { EventSource as EventSourceConstructor } from 'eventsource';
 import pc from 'picocolors';
 import { logger } from './logger.js';
 
+/**
+ * Serialize the body for the forwarded request.
+ *
+ * The backend stores the body as a parsed JSON object (even for non-JSON
+ * payloads, it gets wrapped). We need to re-serialize appropriately:
+ *   - No body for GET/HEAD
+ *   - null/undefined body → no body sent
+ *   - Object/array body → JSON.stringify (with matching Content-Type)
+ *   - Primitive (string/number) → convert to string (e.g. plain text bodies)
+ */
+function serializeBody(method, body, headers) {
+    if (['GET', 'HEAD'].includes(method)) return undefined;
+    if (body === null || body === undefined) return undefined;
+    if (typeof body === 'string') return body;
+    if (typeof body === 'object') return JSON.stringify(body);
+    return String(body);
+}
+
+/**
+ * Ensure Content-Type is set for bodies that need it.
+ * If the original request had application/json, preserve it.
+ */
+function ensureContentType(headers, body) {
+    if (body === undefined || body === null) return headers;
+    if (headers['content-type']) return headers;
+    if (typeof body === 'object') {
+        return { ...headers, 'content-type': 'application/json' };
+    }
+    return headers;
+}
+
 export function startForwarding(apiUrl, hookId, port) {
     const webhookUrl = `${apiUrl}/h/${hookId}`;
     const localUrl = `http://127.0.0.1:${port}`;
@@ -17,10 +48,15 @@ export function startForwarding(apiUrl, hookId, port) {
             const reqData = JSON.parse(event.data);
             const { method, headers, query, body } = reqData;
 
+            // Strip hop-by-hop headers that must not be forwarded
             const forwardHeaders = { ...headers };
             delete forwardHeaders.host;
             delete forwardHeaders.connection;
             delete forwardHeaders['content-length'];
+            delete forwardHeaders['transfer-encoding'];
+
+            const serializedBody = serializeBody(method, body, forwardHeaders);
+            const finalHeaders = ensureContentType(forwardHeaders, body);
 
             const queryString = new URLSearchParams(query || {}).toString();
             const fullLocalUrl = queryString ? `${localUrl}?${queryString}` : localUrl;
@@ -28,9 +64,9 @@ export function startForwarding(apiUrl, hookId, port) {
             logger.warn(`[${new Date().toLocaleTimeString()}] ⚡ Incoming ${method} request...`);
 
             const response = await fetch(fullLocalUrl, {
-                method: method,
-                headers: forwardHeaders,
-                body: ['GET', 'HEAD'].includes(method) ? undefined : JSON.stringify(body)
+                method,
+                headers: finalHeaders,
+                body: serializedBody,
             });
 
             const statusColor = response.ok ? pc.green : pc.red;

package/lib/proRegister.js

@@ -0,0 +1,100 @@
+/**
+ * lib/proRegister.js
+ *
+ * Registers a hook ID as Pro-tier by calling the backend's
+ * POST /hooks/pro/register endpoint.
+ *
+ * Acceptance criteria (ANO-47):
+ *   - Uses the PRO_API_KEY from env or ~/.anonymily/config.json
+ *   - If the key is missing → throws ProApiKeyMissingError
+ *   - If the API returns 401 → throws ProApiAuthError
+ *   - If the API returns any other non-2xx → throws ProApiError
+ *   - On success → prints confirmation message and returns the response body
+ */
+
+import pc from 'picocolors';
+import { logger } from './logger.js';
+import { getProApiKey } from './config.js';
+
+/** Thrown when no Pro API key is configured. */
+export class ProApiKeyMissingError extends Error {
+  constructor() {
+    super(
+      'Pro API key not configured. Run: anonymily config set-key <key>',
+    );
+    this.name = 'ProApiKeyMissingError';
+  }
+}
+
+/** Thrown when the backend returns 401 Unauthorized. */
+export class ProApiAuthError extends Error {
+  constructor() {
+    super(
+      'Pro API key is invalid or revoked. Please verify your key with: anonymily config set-key <key>',
+    );
+    this.name = 'ProApiAuthError';
+  }
+}
+
+/** Thrown when the backend returns any other non-2xx status. */
+export class ProApiError extends Error {
+  /** @param {number} status @param {string} [body] */
+  constructor(status, body = '') {
+    super(`Pro registration failed (HTTP ${status}): ${body}`);
+    this.name = 'ProApiError';
+    this.status = status;
+  }
+}
+
+/**
+ * Register a hook ID as Pro-tier via the backend API.
+ *
+ * @param {string} apiUrl   Base URL, e.g. https://api.anonymily.com
+ * @param {string} hookId   The hook ID to register
+ * @returns {Promise<object>} Parsed response body from the API
+ *
+ * @throws {ProApiKeyMissingError}  No API key available
+ * @throws {ProApiAuthError}        API returned 401
+ * @throws {ProApiError}            API returned other non-2xx
+ */
+export async function registerProHook(apiUrl, hookId) {
+  const apiKey = getProApiKey();
+
+  if (!apiKey) {
+    throw new ProApiKeyMissingError();
+  }
+
+  let response;
+  try {
+    response = await fetch(`${apiUrl}/hooks/pro/register`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+      },
+      body: JSON.stringify({ hookId }),
+    });
+  } catch (networkErr) {
+    throw new Error(`Network error contacting Pro API: ${networkErr.message}`);
+  }
+
+  if (response.status === 401) {
+    throw new ProApiAuthError();
+  }
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => '');
+    throw new ProApiError(response.status, body);
+  }
+
+  const data = await response.json().catch(() => ({}));
+
+  logger.success(
+    pc.bold(
+      `[Pro] Hook registered: persists for 30 days, up to 500 requests stored.`,
+    ),
+  );
+
+  return data;
+}
+

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@anonymilyhq/cli",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "CLI for Anonymily platform",
   "type": "module",
   "bin": {
     "anonymily": "bin/cli.js"
   },
   "scripts": {
-    "start": "node ./bin/cli.js"
+    "start": "node ./bin/cli.js",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --no-coverage",
+    "test:coverage": "node --experimental-vm-modules node_modules/.bin/jest --coverage"
   },
   "keywords": [
     "cli",
@@ -27,5 +29,12 @@
     "commander": "^14.0.3",
     "eventsource": "^4.1.0",
     "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "jest": "^30.3.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {}
   }
-}
+}