@anonymilyhq/cli 1.2.0 → 1.3.0

package/README.md

@@ -14,17 +14,19 @@
 
 ## 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.
+The Anonymily CLI connects to your webhook endpoint 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. It also captures your server's response and streams it back to the dashboard in real time, so you can see status codes, latency, and error bodies without leaving the UI.
 
-**No tunnels. No signup. No account required.** Just one command.
+**No account required for the free tier. One command.**
 
-> **Want more?** Upgrade to Pro (₹750/month) to claim persistent hooks and unlock 500 requests + 30-day retention. Visit [anonymily.com/upgrade](https://anonymily.com/upgrade) to subscribe.
+```bash
+npx @anonymilyhq/cli listen 3000
+```
 
 ---
 
 ## Installation
 
-**Run instantly via npx (no install required):**
+**Run instantly via npx (no install):**
 ```bash
 npx @anonymilyhq/cli listen 3000
 ```
@@ -38,31 +40,26 @@ npm install -g @anonymilyhq/cli
 
 ## Quick Start
 
-**No account or signup required** — works immediately with free tier (random ID, 50 requests, 24h retention).
-
 ```bash
-# Start listening — generates a random 8-char 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
-# Tier: 🆓 FREE | Storage: 0/50 | Retention: 24 hours
-# 💡 Upgrade to Pro for custom endpoint IDs + 500 req/30d at https://anonymily.com/upgrade
-# Waiting for requests to arrive...
+# Anonymily CLI is running!
+# Forwarding: https://api.anonymily.com/h/xk92bzte  →  http://127.0.0.1:3000
+# Tier: FREE | Storage: 0/200 | Retention: 48 hours
+# Waiting for requests...
 ```
 
 Send a test payload:
 ```bash
 curl -X POST https://api.anonymily.com/h/xk92bzte \
   -H "Content-Type: application/json" \
-  -d '{"event": "payment.success"}'
+  -d '{"event": "payment.succeeded", "amount": 9900}'
 ```
 
-You'll see in the CLI:
+CLI output:
 ```
-[12:01:45] ⚡ Incoming POST request...
-  └─ Forwarded to localhost | Status: 200
+[12:01:45] Incoming POST  →  localhost:3000  |  200 OK  |  11ms
 ```
 
 ---
@@ -71,170 +68,147 @@ You'll see in the CLI:
 
 ### `listen <port>`
 
-Listen for incoming webhooks and forward them to a local port.
+Listen for incoming webhooks and forward them to your local port.
 
 ```bash
-anonymily listen <port> [options]
+npx @anonymilyhq/cli listen <port> [options]
 ```
 
 | Option | Description |
-|--------|-------------|
-| `<port>` | **Required.** Local port to forward to (e.g. `3000`, `8080`) |
-| `-i, --id <id>` | **Pro only.** Use a custom endpoint ID (e.g. `stripe-test`) instead of a random one. Requires Pro subscription (₹750/month). |
+|---|---|
+| `<port>` | **Required.** Local port to forward to (e.g. `3000`) |
+| `-i, --id <id>` | **Pro.** Use a named endpoint ID (e.g. `stripe-test`) instead of a random one. |
+| `-t, --token <token>` | **Pro.** Personal Access Token — authenticates to claimed endpoints. Also readable from `ANONYMILY_TOKEN` env var. |
 
 **Examples:**
+
 ```bash
-# Random endpoint ID (Free tier: 50 requests, 24h retention)
+# Free tier — random endpoint, no auth
 npx @anonymilyhq/cli listen 3000
 
-# Custom named endpoint (Pro only: requires subscription + claiming via dashboard)
-npx @anonymilyhq/cli listen 3000 --id stripe-dev
+# Pro — named endpoint with PAT
+npx @anonymilyhq/cli listen 3000 --id stripe-dev --token pat_example123
 
-# Use your Pro-claimed endpoint (500 requests, 30 days)
-npx @anonymilyhq/cli listen 3000 --id my-claimed-hook
+# PAT via env var
+export ANONYMILY_TOKEN=pat_example123
+npx @anonymilyhq/cli listen 3000 --id stripe-dev
 ```
 
----
+### `replay <hookId> <requestId>`
 
-### `feedback <rating> [message]`
-
-Submit feedback about the Anonymily CLI directly from your terminal.
+Re-fire a previously captured request back through your hook endpoint. Requires a PAT and Pro subscription (free users are rate-limited to 5 replays/day, enforced server-side).
 
 ```bash
-anonymily feedback <rating> [message]
+npx @anonymilyhq/cli replay <hookId> <requestId> [options]
 ```
 
-| Parameter | Description |
-|-----------|-------------|
-| `<rating>` | **Required.** Rating from 1-5 (1=Poor, 5=Excellent) |
-| `[message]` | Optional feedback message |
+| Option | Description |
+|---|---|
+| `<hookId>` | **Required.** The hook ID that captured the request. |
+| `<requestId>` | **Required.** The request ID to replay (visible in the dashboard). |
+| `-t, --token <token>` | **Required.** PAT — or set `ANONYMILY_TOKEN`. |
+| `-m, --method <method>` | Override the HTTP method (e.g. `POST`, `GET`). |
+| `-b, --body <json>` | Override the request body (JSON string). |
+| `--resign` | Re-sign the payload using the hook's stored secret. |
 
 **Examples:**
-```bash
-# Quick rating
-anonymily feedback 5
 
-# Rating with message
-anonymily feedback 4 "Great tool! Would love to see request filtering."
+```bash
+# Basic replay
+npx @anonymilyhq/cli replay stripe-dev abc-123 --token pat_example123
 
-# Detailed feedback
-anonymily feedback 5 "The SSE reconnection works perfectly. No issues so far!"
+# Replay with body override and re-signing
+npx @anonymilyhq/cli replay stripe-dev abc-123 \
+  --body '{"amount":5000}' --resign --token pat_example123
 ```
 
-Your feedback helps us improve Anonymily. All submissions are anonymous unless you're logged in via the web dashboard.
-
----
-
-## Upgrading to Pro (₹750/month)
-
-**What Pro gives you:**
-- **Custom named endpoints** - Use memorable IDs like `stripe-prod` or `github-webhooks`
-- **Claim & manage** - Link endpoints to your account permanently via dashboard
-- **500 requests** per endpoint (vs 50 for Free random IDs)
-- **30-day retention** (vs 24 hours for Free tier)
+### `feedback <rating> [message]`
 
-**How to upgrade and use custom endpoints:**
-1. Subscribe to Pro at [anonymily.com/upgrade](https://anonymily.com/upgrade) (₹750/month)
-2. Log in to your dashboard at [anonymily.com/dashboard](https://anonymily.com/dashboard)
-3. Enter your custom endpoint ID (e.g. `my-webhook`) and click "Claim"
-4. Run the CLI with your claimed hook ID:
-   ```bash
-   npx @anonymilyhq/cli listen 3000 --id my-webhook
-   ```
-5. Enjoy Pro limits — 500 requests, 30-day history
+Submit feedback from the terminal.
 
-**Important:** Custom endpoint IDs are a **Pro-only feature**. Free users can only use randomly-generated 8-character IDs with 50 requests and 24h retention.
+```bash
+npx @anonymilyhq/cli feedback 5 "Works perfectly with Shopify webhooks"
+```
 
 ---
 
 ## How It Works
 
 ```
-External Service (Stripe, GitHub, etc.)
+External Service (Stripe, GitHub, Shopify, …)
         │
         │  POST https://api.anonymily.com/h/<hookId>
         ▼
-  Anonymily Backend (NestJS + Redis + Supabase)
+  Anonymily Backend — captures, verifies signature, stores in Redis
         │
         │  SSE broadcast via /stream/<hookId>
         ▼
   @anonymilyhq/cli  ──forward──►  http://localhost:<port>
+        │
+        │  Response (status, latency, body) streamed back to dashboard
+        ▼
+  Anonymily Dashboard — shows full exchange in real time
 ```
 
-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
+1. The CLI opens a persistent SSE connection to the backend.
+2. When a webhook arrives, it is broadcast instantly.
+3. The CLI re-issues the exact HTTP request to your local port, preserving method, headers, query params, and body.
+4. The local response (status code, latency, body) is captured and streamed back to the dashboard so you can see the full exchange without leaving the UI.
 
 ---
 
-## Tier Comparison
+## Tiers
 
 | Feature | Free | Pro |
-|---------|------|-----|
-| Endpoint ID format | Random 8-char (e.g. `xk92bzte`) | Custom named (e.g. `stripe-prod`) |
-| Requests stored per hook | 50 | 500 |
-| History retention | 24 hours | 30 days |
-| Hook claiming & management | ❌ | ✅ |
-| Dashboard access | ✅ | ✅ |
-| Price | Free | ₹750/month |
-
-**Note:** Custom endpoint IDs (via `--id` flag) are a **Pro-only feature**. Free users receive randomly-generated IDs.
+|---|---|---|
+| Endpoint ID | Random 8-char | Custom named (`--id`) |
+| Requests per hook | 200 | 2,000 |
+| History retention | 48 hours | 30 days |
+| Named (persistent) endpoints | — | Unlimited |
+| Replay (`replay` command) | 5/day | Unlimited |
+| Signature verification UI | — | ✓ |
+| AI diagnosis + handler gen | — | ✓ (dashboard) |
+| AI edge-case events | — | ✓ (dashboard) |
+| Price | Free | $9 / ₹750 per month |
+
+Upgrade at [anonymily.com/upgrade](https://anonymily.com/upgrade).
 
 ---
 
-## Testing Locally
-
-A sample target server is included to test forwarding without a real local app:
+## MCP Server
 
-```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
-```
+If you use Claude Code, you can drive Anonymily entirely from your AI assistant using the `@anonymilyhq/mcp-server` package. See the [MCP Server README](../../packages/mcp-server/README.md) for setup.
 
 ---
 
 ## Troubleshooting
 
 **`Connection refused` when forwarding:**
-- Make sure your local server is actually running on the specified port
-- Test with: `curl http://localhost:<port>`
+Ensure your local server is 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
+**Requests arrive but server returns errors:**
+Check your server logs. The CLI shows `Status: 5xx` — look at the response body in the dashboard for the error detail.
 
 **CLI doesn't reconnect after network drop:**
-- The CLI uses `eventsource` which auto-reconnects on drops
-- You'll see: `[Network] Connection dropped. Automatically reconnecting...`
+The CLI uses `eventsource` which auto-reconnects. You'll see: `Connection dropped. Reconnecting...`
+
+**401 on stream connection:**
+Named endpoints require a valid PAT. Pass `--token <your-pat>` or set `ANONYMILY_TOKEN`.
 
-**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
+**403 when using `--id` on a free account:**
+Custom named endpoint IDs (`--id`) are a Pro feature. Remove `--id` to use a random free endpoint, or upgrade at [anonymily.com/upgrade](https://anonymily.com/upgrade).
 
 ---
 
 ## Environment Variables
 
 | Variable | Description |
-|----------|-------------|
+|---|---|
+| `ANONYMILY_TOKEN` | Personal Access Token for named endpoint authentication |
 | `ANONYMILY_API_URL` | Override the backend URL (default: `https://api.anonymily.com`) |
 
 ---
 
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
-
-## Contributing
-
-Issues and pull requests are welcome. Open an issue first to discuss any significant changes.
-
 ## License
 
 MIT © [Anonymily](https://anonymily.com)

package/bin/cli.js

@@ -6,6 +6,7 @@ import { generateHookId } from '../lib/utils.js';
 import { startForwarding } from '../lib/forwarder.js';
 import { logger } from '../lib/logger.js';
 import { submitFeedback } from '../lib/feedback.js';
+import { listEvents, fireEvent, printEventList } from '../lib/trigger.js';
 
 // Point this to your live production backend URL
 const API_URL = process.env.ANONYMILY_API_URL || 'https://api.anonymily.com';
@@ -22,13 +23,179 @@ 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>', '[Pro only] Use a custom endpoint ID instead of random (requires ₹750/month subscription)')
+  .option('-i, --id <id>', '[Pro] Use a custom named endpoint ID (requires Pro subscription — anonymily.com/upgrade)')
+  // CLI-001: Accept a Personal Access Token for authenticating Pro hook streams
+  .option('-t, --token <token>', '[Pro only] Personal Access Token for authenticating to private hooks (or set ANONYMILY_TOKEN env var)')
   .action(async (port, options) => {
     const hookId = options.id || generateHookId();
-    startForwarding(API_URL, hookId, parseInt(port, 10));
+    // CLI-001: Resolve token from --token flag or ANONYMILY_TOKEN env var
+    const token = options.token || process.env.ANONYMILY_TOKEN || null;
+    startForwarding(API_URL, hookId, parseInt(port, 10), token);
   });
 
 
+// ---------------------------------------------------------------------------
+// trigger
+// ---------------------------------------------------------------------------
+program
+  .command('trigger')
+  .description('[Pro] Fire a synthetic provider event at your webhook endpoint')
+  .argument('[provider]', 'Provider name (e.g. github, stripe, shopify, razorpay, slack)')
+  .argument('[event]',    'Event name (e.g. push, payment_intent.succeeded, order.created)')
+  .option('-i, --hook <hookId>', 'Target hook ID (defaults to a random ID)')
+  .option('-t, --token <token>', 'Personal Access Token (or set ANONYMILY_TOKEN env var)')
+  .option('-l, --list', 'List all available provider/event combinations and exit')
+  .action(async (provider, event, options) => {
+    const token = options.token || process.env.ANONYMILY_TOKEN || null;
+
+    // --list: show all available events
+    if (options.list || (!provider && !event)) {
+      const events = await listEvents(API_URL);
+      if (events) printEventList(events);
+      return;
+    }
+
+    if (!provider || !event) {
+      logger.error('Usage: anonymily trigger <provider> <event> --hook <hookId> [--token <pat>]');
+      logger.dim('       anonymily trigger --list');
+      process.exit(1);
+    }
+
+    const hookId = options.hook || null;
+    if (!hookId) {
+      logger.error('Specify a hook ID with --hook <hookId>. Example: --hook abc12345');
+      process.exit(1);
+    }
+
+    if (!token) {
+      logger.error('A Personal Access Token is required for the trigger command.');
+      logger.dim('  Use --token <pat> or set the ANONYMILY_TOKEN environment variable.');
+      logger.dim('  Generate a PAT from your dashboard at https://anonymily.com/account');
+      process.exit(1);
+    }
+
+    logger.dim(`Firing ${pc.bold(provider)} ${pc.bold(event)} at ${pc.cyan(`${API_URL}/h/${hookId}`)}...`);
+
+    try {
+      const result = await fireEvent(API_URL, hookId, provider, event, token);
+      logger.success(`\n✅ Event fired successfully!`);
+      logger.raw(`   Provider:  ${pc.bold(provider)}`);
+      logger.raw(`   Event:     ${pc.bold(event)}`);
+      logger.raw(`   Hook:      ${pc.cyan(`${API_URL}/h/${hookId}`)}`);
+      if (result.signatureAdded) {
+        logger.raw(`   Signature: ${pc.green('✓ computed and attached')}`);
+      } else {
+        logger.dim(`   Signature: not added (no signing secret configured for this hook)`);
+      }
+      logger.raw('');
+    } catch (err) {
+      logger.error(`\n❌ Failed to fire event: ${err.message}`);
+      if (err.message?.includes('Pro')) {
+        logger.dim('  Upgrade to Pro at https://anonymily.com/upgrade to use the trigger command.');
+      }
+      process.exit(1);
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// replay
+// ---------------------------------------------------------------------------
+program
+  .command('replay')
+  .description('[Pro] Re-fire a previously captured request back through your hook endpoint')
+  .argument('<hookId>', 'The hook ID that captured the request')
+  .argument('<requestId>', 'The request ID to replay (from the dashboard or anonymily requests <hookId>)')
+  .option('-t, --token <token>', 'Personal Access Token (or set ANONYMILY_TOKEN env var)')
+  .option('-m, --method <method>', 'Override the HTTP method (e.g. POST, GET)')
+  .option('-b, --body <json>', 'Override the request body (JSON string)')
+  .option('--resign', "Re-sign the payload with the hook's stored secret")
+  .action(async (hookId, requestId, options) => {
+    const token = options.token || process.env.ANONYMILY_TOKEN || null;
+    if (!token) {
+      logger.error('A Personal Access Token is required for the replay command.');
+      logger.dim('  Use --token <pat> or set the ANONYMILY_TOKEN environment variable.');
+      logger.dim('  Generate a PAT from your dashboard at https://anonymily.com/account');
+      process.exit(1);
+    }
+
+    let body;
+    if (options.body) {
+      try {
+        body = JSON.parse(options.body);
+      } catch {
+        logger.error("--body must be valid JSON. Example: --body '{\"event\":\"payment\"}'");
+        process.exit(1);
+      }
+    }
+
+    logger.dim(`Replaying request ${pc.bold(requestId)} on hook ${pc.cyan(`${API_URL}/h/${hookId}`)}...`);
+
+    // BUG-022: Look up the original captured request so we can replay its actual
+    // method/body/headers. Without this, the replay POST body was empty.
+    let originalReq = null;
+    try {
+      const reqRes = await fetch(`${API_URL}/v1/hooks/${hookId}/requests/${requestId}`, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (reqRes.ok) {
+        originalReq = await reqRes.json();
+      } else {
+        logger.warn(`⚠️  Could not load original request (${reqRes.status}) — replay may have empty body.`);
+      }
+    } catch (fetchErr) {
+      logger.warn(`⚠️  Could not load original request: ${fetchErr.message} — replay may have empty body.`);
+    }
+
+    // CLI flags override stored values; stored values serve as defaults.
+    const replayMethod  = options.method ?? originalReq?.method ?? undefined;
+    const replayBody    = body !== undefined ? body : (originalReq?.body ?? undefined);
+    const replayHeaders = originalReq?.headers ?? undefined;
+
+    try {
+      const res = await fetch(`${API_URL}/v1/hooks/${hookId}/replay`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({
+          ...(replayMethod           ? { method:  replayMethod }  : {}),
+          ...(replayBody !== undefined ? { body: replayBody }    : {}),
+          ...(replayHeaders          ? { headers: replayHeaders } : {}),
+          resign: !!options.resign,
+        }),
+      });
+
+      if (res.status === 401) {
+        logger.error('❌ Unauthorized: Invalid or expired Personal Access Token.');
+        process.exit(1);
+      }
+      if (res.status === 403) {
+        const data = await res.json().catch(() => ({}));
+        logger.error(`❌ ${data.message ?? 'Free tier allows 5 replays per day. Upgrade to Pro for unlimited replays.'}`);
+        logger.dim('  Upgrade at https://anonymily.com/upgrade');
+        process.exit(1);
+      }
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        logger.error(`❌ Replay failed: ${data.message ?? res.statusText}`);
+        process.exit(1);
+      }
+
+      const result = await res.json();
+      logger.success(`\n✅ Request replayed successfully!`);
+      logger.raw(`   Hook:    ${pc.cyan(`${API_URL}/h/${hookId}`)}`);
+      logger.raw(`   Request: ${requestId}`);
+      if (result.signatureAdded) {
+        logger.raw(`   Signature: ${pc.green('✓ re-signed with hook secret')}`);
+      }
+      logger.raw('');
+    } catch (err) {
+      logger.error(`\n❌ Failed to replay request: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
 // ---------------------------------------------------------------------------
 // feedback
 // ---------------------------------------------------------------------------

package/lib/forwarder.js

@@ -33,56 +33,163 @@ function ensureContentType(headers, body) {
     return headers;
 }
 
+/**
+ * P1-05: Fetch the stable signing secret for a claimed hook.
+ * Requires a valid PAT (token). Returns null on any error.
+ */
+async function fetchSigningSecret(apiUrl, hookId, token) {
+    try {
+        const res = await fetch(`${apiUrl}/users/hooks/${hookId}/secret`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) return null;
+        const { secret } = await res.json();
+        return secret ?? null;
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Fetch tier information for a hook ID from the backend.
+ * Limits (maxRequests, retention) are derived from the live /pricing endpoint
+ * so the CLI stays in sync with server-side config without a reinstall.
  */
-async function fetchTierInfo(apiUrl, hookId) {
+async function fetchTierInfo(apiUrl, hookId, token) {
     try {
-        const response = await fetch(`${apiUrl}/history/${hookId}`);
-        if (!response.ok) return null;
-
-        const data = await response.json();
-        return {
-            tier: data.tier || 'free',
-            requestCount: data.requests?.length || 0,
-            maxRequests: data.tier === 'pro' ? 500 : 50,
-            retention: data.tier === 'pro' ? '30 days' : '24 hours',
-        };
+        // 1. Fetch hook history for current request count + tier.
+        //    Custom hooks require auth after BUG-003 fix.
+        const historyHeaders = { 'Content-Type': 'application/json' };
+        if (token) historyHeaders['Authorization'] = `Bearer ${token}`;
+
+        const historyRes = await fetch(`${apiUrl}/history/${hookId}`, { headers: historyHeaders });
+        if (!historyRes.ok) return null;
+        const data = await historyRes.json();
+
+        // History returns a plain array; _tier is written per-item by the API.
+        const requestCount = Array.isArray(data) ? data.length : 0;
+        let tier = (Array.isArray(data) && data.length > 0 && data[0]._tier) || 'free';
+
+        // When history is empty, _tier can't be read from requests — fall back to /users/me
+        if (tier === 'free' && token && requestCount === 0) {
+            try {
+                const meRes = await fetch(`${apiUrl}/users/me`, {
+                    headers: { Authorization: `Bearer ${token}` },
+                });
+                if (meRes.ok) {
+                    const me = await meRes.json();
+                    if (me.isPro) tier = 'pro';
+                }
+            } catch { /* keep 'free' as safe fallback */ }
+        }
+
+        // 2. Fetch live limits from /pricing endpoint
+        let maxRequests    = tier === 'pro' ? 2000 : 200;  // conservative fallback
+        let retention      = tier === 'pro' ? '30 days' : '48 hours';
+        let proMaxRequests = 2000;  // used in upgrade messaging
+
+        try {
+            const pricingRes = await fetch(`${apiUrl}/pricing`);
+            if (pricingRes.ok) {
+                const pricing = await pricingRes.json();
+                proMaxRequests = pricing.pro?.features?.requestCap ?? proMaxRequests;
+                if (tier === 'pro') {
+                    maxRequests = proMaxRequests;
+                    const hours = pricing.pro?.features?.retentionHours ?? 720;
+                    retention   = `${hours / 24} days`;
+                } else {
+                    maxRequests = pricing.free?.features?.requestCap ?? maxRequests;
+                    const hours = pricing.free?.features?.retentionHours ?? 48;
+                    retention   = `${hours} hours`;
+                }
+            }
+        } catch { /* silently keep fallback values */ }
+
+        return { tier, requestCount, maxRequests, retention, proMaxRequests };
     } catch {
         return null;
     }
 }
 
-export async function startForwarding(apiUrl, hookId, port) {
+
+/**
+ * CLI-001: Build EventSource constructor options from an optional PAT.
+ *
+ * Returns an options object with an `Authorization: Bearer <token>` header
+ * when `token` is a non-empty string, or an empty object otherwise.
+ * Exported for unit testing.
+ *
+ * @param {string|null} token - Personal Access Token, or null/undefined.
+ * @returns {object} EventSource options (may have a `headers` field).
+ */
+export function buildEventSourceOptions(token) {
+    if (token) {
+        return { headers: { Authorization: `Bearer ${token}` } };
+    }
+    return {};
+}
+
+/**
+ * CLI-001: Start forwarding webhooks from the Anonymily SSE stream to a local port.
+ *
+ * @param {string} apiUrl   - Base URL of the Anonymily backend API.
+ * @param {string} hookId   - The webhook endpoint ID to listen on.
+ * @param {number} port     - Local port to forward received requests to.
+ * @param {string|null} token - Optional Personal Access Token for Pro hook authentication.
+ *                              When provided, sent as `Authorization: Bearer <token>`.
+ *                              Required for privately-claimed Pro hooks; optional for public hooks.
+ */
+export async function startForwarding(apiUrl, hookId, port, token = null) {
     const webhookUrl = `${apiUrl}/h/${hookId}`;
     const localUrl = `http://127.0.0.1:${port}`;
 
     logger.success(pc.bold(`\n🚀 Anonymily CLI is running!`));
     logger.raw(`\nForwarding: ${pc.cyan(webhookUrl)}  ➔  ${pc.cyan(localUrl)}`);
 
+    // CLI-001: Inform user about authentication status
+    if (token) {
+        logger.dim(`🔐 Authenticated with Personal Access Token`);
+    }
+
+    // P1-05: Display stable signing secret for claimed (custom) hooks
+    const isCustomEndpoint = !/^[a-z0-9]{8}$/.test(hookId);
+    if (token && isCustomEndpoint) {
+        const secret = await fetchSigningSecret(apiUrl, hookId, token);
+        if (secret) {
+            logger.raw(`\n${pc.bold('Signing Secret')} (use in your app to verify requests):`);
+            logger.raw(`  ${pc.cyan(`whsec_${secret}`)}\n`);
+        }
+    }
+
     // Fetch and display tier information
-    const tierInfo = await fetchTierInfo(apiUrl, hookId);
+    const tierInfo = await fetchTierInfo(apiUrl, hookId, token);
     if (tierInfo) {
         const tierColor = tierInfo.tier === 'pro' ? pc.green : pc.yellow;
         const tierBadge = tierInfo.tier === 'pro' ? '✨ PRO' : '🆓 FREE';
         logger.raw(`Tier: ${tierColor(pc.bold(tierBadge))} | Storage: ${tierInfo.requestCount}/${tierInfo.maxRequests} | Retention: ${tierInfo.retention}`);
 
         if (tierInfo.tier === 'free') {
-            logger.dim(`\n💡 Upgrade to Pro for custom endpoint IDs + 500 req/30d at https://anonymily.com/upgrade`);
+            logger.dim(`\n💡 Upgrade to Pro for custom endpoint IDs + ${tierInfo.maxRequests} req/${tierInfo.retention} at https://anonymily.com/upgrade`);
         }
     }
 
     logger.dim(`Waiting for requests to arrive...`);
     logger.dim(`💬 Enjoying the CLI? Run 'anonymily feedback 5' to let us know!\n`);
 
-    const es = new EventSourceConstructor(`${apiUrl}/stream/${hookId}`);
+    // CLI-001: Build EventSource options — attach Authorization header when token is provided
+    const esOptions = buildEventSourceOptions(token);
+
+    const es = new EventSourceConstructor(`${apiUrl}/stream/${hookId}`, esOptions);
 
     let requestCount = tierInfo?.requestCount || 0;
     const maxRequests = tierInfo?.maxRequests || 50;
+    const proMaxRequests = tierInfo?.proMaxRequests ?? 2000;
 
     es.onmessage = async (event) => {
         try {
             const reqData = JSON.parse(event.data);
+            // Skip internal SSE events (e.g. response_update from P1-03 capture)
+            if (reqData._type) return;
             const { method, headers, query, body } = reqData;
 
             // Strip hop-by-hop headers that must not be forwarded
@@ -105,30 +212,97 @@ export async function startForwarding(apiUrl, hookId, port) {
 
             logger.warn(`[${new Date().toLocaleTimeString()}] ⚡ Incoming ${method} request ${progressColor(progress)}...`);
 
-            const response = await fetch(fullLocalUrl, {
-                method,
-                headers: finalHeaders,
-                body: serializedBody,
-            });
+            const t0 = Date.now();
+            let response;
+            let captureError = null;
+            try {
+                response = await fetch(fullLocalUrl, {
+                    method,
+                    headers: finalHeaders,
+                    body: serializedBody,
+                    signal: AbortSignal.timeout(30_000),
+                });
+            } catch (fetchErr) {
+                captureError = fetchErr.name === 'TimeoutError' ? 'timeout' : 'unreachable';
+            }
+            const latencyMs = Date.now() - t0;
+
+            if (captureError) {
+                logger.error(`  └─ ${captureError === 'timeout' ? 'Timeout' : 'Unreachable'} after ${latencyMs}ms. Make sure your local server is running on port ${port}\n`);
+                // P1-03: report connection failure
+                if (reqData.id) {
+                    fetch(`${apiUrl}/response/${reqData.id}`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ error: captureError, latencyMs }),
+                    }).catch(() => {});
+                }
+            } else {
+                const statusColor = response.ok ? pc.green : pc.red;
+                logger.raw(`  └─ Forwarded to localhost | Status: ${statusColor(response.status)} | ${latencyMs}ms\n`);
+
+                // P1-03: capture response details and send back to API
+                if (reqData.id) {
+                    let responseBody = '';
+                    try {
+                        const clone = response.clone();
+                        const buf = await clone.arrayBuffer();
+                        const bytes = buf.byteLength;
+                        if (bytes <= 100_000) {
+                            const ct = response.headers.get('content-type') ?? '';
+                            responseBody = ct.includes('text') || ct.includes('json')
+                                ? await response.text()
+                                : `[binary ${bytes} bytes]`;
+                        } else {
+                            responseBody = `[truncated — ${bytes} bytes]`;
+                        }
+                    } catch {}
 
-            const statusColor = response.ok ? pc.green : pc.red;
-            logger.raw(`  └─ Forwarded to localhost | Status: ${statusColor(response.status)}\n`);
+                    const responseHeaders = {};
+                    response.headers.forEach((v, k) => { responseHeaders[k] = v; });
+
+                    fetch(`${apiUrl}/response/${reqData.id}`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            status: response.status,
+                            headers: responseHeaders,
+                            body: responseBody,
+                            latencyMs,
+                        }),
+                    }).catch(() => {});
+                }
+            }
 
             // Warn when approaching tier limit
             if (requestCount === maxRequests) {
                 logger.warn(`⚠️  Tier limit reached (${maxRequests} requests). Older requests will be purged.\n`);
             } else if (requestCount === Math.floor(maxRequests * 0.9)) {
-                logger.warn(`⚠️  90% of tier limit reached. Upgrade to Pro for 500 requests at https://anonymily.com/upgrade\n`);
+                logger.warn(`⚠️  90% of tier limit reached. Upgrade to Pro for ${proMaxRequests} requests at https://anonymily.com/upgrade\n`);
             }
         } catch (err) {
-            logger.error(`  └─ Error forwarding: ${err.message}`);
-            logger.dim(`     Make sure your local server is actually running on port ${port}\n`);
+            logger.error(`  └─ Unexpected error: ${err.message}\n`);
         }
     };
 
-    es.onerror = () => {
+    es.onerror = (err) => {
+        // eventsource v4 uses err.code for HTTP status, not err.status
+        if (err && err.code === 401) {
+            logger.error(`\n❌ Unauthorized: This hook requires a valid Personal Access Token.`);
+            logger.dim(`   Use --token <your-pat> or set the ANONYMILY_TOKEN environment variable.`);
+            logger.dim(`   Generate a PAT from your dashboard at https://anonymily.com/account\n`);
+            es.close();
+            process.exit(1);
+        }
+        if (err && err.code === 403) {
+            logger.error(`\n❌ Forbidden: Custom endpoint IDs require a Pro subscription.`);
+            logger.dim(`   Remove --id to use a random free endpoint, or upgrade at https://anonymily.com/upgrade\n`);
+            es.close();
+            process.exit(1);
+        }
         logger.dim(`\n[Network] Connection dropped. Automatically reconnecting...`);
     };
 
     return es;
 }
+

package/lib/trigger.js

@@ -0,0 +1,76 @@
+import pc from 'picocolors';
+import { logger } from './logger.js';
+
+/**
+ * P2-02: List available synthetic event templates from the API.
+ * @returns {Promise<Array<{provider: string, event: string, description: string}>>}
+ */
+export async function listEvents(apiUrl) {
+  try {
+    const res = await fetch(`${apiUrl}/trigger/events`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+  } catch (err) {
+    logger.error(`Failed to fetch event list: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * P2-02: Fire a synthetic event at a hook endpoint.
+ * @param {string} apiUrl
+ * @param {string} hookId
+ * @param {string} provider   e.g. 'github'
+ * @param {string} event      e.g. 'push'
+ * @param {string|null} token PAT for Pro auth
+ */
+export async function fireEvent(apiUrl, hookId, provider, event, token) {
+  const res = await fetch(`${apiUrl}/trigger/${hookId}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: JSON.stringify({ provider, event }),
+    signal: AbortSignal.timeout(20_000),
+  });
+
+  if (!res.ok) {
+    let errMsg = `HTTP ${res.status}`;
+    try {
+      const body = await res.json();
+      errMsg = body.message ?? errMsg;
+    } catch {}
+    throw new Error(errMsg);
+  }
+
+  return res.json();
+}
+
+/**
+ * Pretty-print the event list in a table grouped by provider.
+ */
+export function printEventList(events) {
+  if (!events || events.length === 0) {
+    logger.error('No events available.');
+    return;
+  }
+
+  // Group by provider
+  const byProvider = {};
+  for (const e of events) {
+    (byProvider[e.provider] ??= []).push(e);
+  }
+
+  logger.raw(`\n${pc.bold('Available synthetic events')}\n`);
+  logger.raw(`  Usage: ${pc.cyan('anonymily trigger <provider> <event> --hook <hookId> --token <pat>')}\n`);
+
+  for (const [provider, evts] of Object.entries(byProvider)) {
+    logger.raw(`  ${pc.bold(pc.green(provider))}`);
+    for (const e of evts) {
+      const paddedEvent = e.event.padEnd(36);
+      logger.raw(`    ${pc.cyan(paddedEvent)}  ${pc.dim(e.description)}`);
+    }
+    logger.raw('');
+  }
+}

package/lib/utils.js

@@ -1,3 +1,8 @@
 export function generateHookId() {
-    return Math.random().toString(36).substring(2, 10);
+    const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let id = '';
+    for (let i = 0; i < 8; i++) {
+        id += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return id;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anonymilyhq/cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "CLI for Anonymily platform",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "start": "node ./bin/cli.js",
+    "build": "echo 'CLI built successfully' && ls ./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"
   },