@paychainly/cli 1.0.3 → 1.1.0

package/bin/paychainly.js

@@ -1,28 +1,60 @@
 #!/usr/bin/env node
 'use strict';
 const [,, cmd, ...argv] = process.argv;
+
+if (cmd === '--version' || cmd === '-V') {
+  console.log(require('../package.json').version);
+  process.exit(0);
+}
+
 if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  const v = require('../package.json').version;
   console.log(`
-  Paychainly CLI
+  Paychainly CLI v${v}
 
   Commands:
-    listen    Relay webhooks to your local server
+    listen    Relay live webhooks to your local server
+    status    Check API key validity and server connectivity
+    replay    Replay saved webhook events to your local server
 
   Usage:
-    paychainly listen --api-key <key> --port <port>
     paychainly listen --api-key <key> --forward-to http://localhost:3000/webhook
+    paychainly listen --api-key <key> --port 3000 --verbose
+    paychainly listen --api-key <key> --filter deposit_detected --log events.jsonl
+    paychainly status --api-key <key>
+    paychainly replay --log events.jsonl --forward-to http://localhost:3000/webhook
 
-  Options:
+  Options (listen):
     --api-key      Your Paychainly API key (pk_live_... or pk_test_...)
     --port         Local port to forward webhooks to (default: 3000)
     --forward-to   Full local URL to forward webhooks to
-    --host         Paychainly server URL (default: http://localhost:3002)
+    --host         Paychainly server URL (default: https://api.paychainly.com)
     --secret       Webhook secret to verify incoming signatures
+    --verbose      Print full webhook payload as pretty JSON
+    --filter       Only relay events matching this name (e.g. deposit_detected)
+    --log          Append all received events to a JSONL file for later replay
+
+  Options (status):
+    --api-key      Your Paychainly API key
+    --host         Paychainly server URL (default: https://api.paychainly.com)
+
+  Options (replay):
+    --log          JSONL file produced by --log (required)
+    --forward-to   Local URL to forward to (default: http://localhost:3000/webhook)
+    --port         Local port shorthand
+    --filter       Only replay events matching this name
+    --delay        Milliseconds between replayed events (default: 500)
+    --verbose      Print full payload for each replayed event
   `);
   process.exit(0);
 }
+
 if (cmd === 'listen') {
   require('../src/listen.js')(argv);
+} else if (cmd === 'status') {
+  require('../src/status.js')(argv);
+} else if (cmd === 'replay') {
+  require('../src/replay.js')(argv);
 } else {
   console.error(`Unknown command: ${cmd}. Run "paychainly help" for usage.`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paychainly/cli",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Paychainly CLI — relay webhooks to your localhost during development",
   "keywords": [
     "paychainly",
@@ -14,8 +14,7 @@
   "homepage": "https://paychainly.com",
   "license": "MIT",
   "bin": {
-    "paychainly": "bin/paychainly.js",
-    "paychainly-cli": "bin/paychainly.js"
+    "paychainly": "bin/paychainly.js"
   },
   "files": [
     "bin/",

package/src/listen.js

@@ -4,20 +4,20 @@ const { io } = require('socket.io-client');
 const http = require('http');
 const https = require('https');
 const crypto = require('crypto');
+const fs = require('fs');
 
-// ── ANSI colours ──────────────────────────────────────────────────────────────
 const c = {
-  reset:  '\x1b[0m',
-  bold:   '\x1b[1m',
-  dim:    '\x1b[2m',
-  green:  '\x1b[32m',
-  cyan:   '\x1b[36m',
-  yellow: '\x1b[33m',
-  red:    '\x1b[31m',
-  magenta:'\x1b[35m',
-  blue:   '\x1b[34m',
-  white:  '\x1b[37m',
-  gray:   '\x1b[90m',
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  green:   '\x1b[32m',
+  cyan:    '\x1b[36m',
+  yellow:  '\x1b[33m',
+  red:     '\x1b[31m',
+  magenta: '\x1b[35m',
+  blue:    '\x1b[34m',
+  white:   '\x1b[37m',
+  gray:    '\x1b[90m',
 };
 
 function parseArgs(argv) {
@@ -65,7 +65,7 @@ function postToLocal(url, payload) {
       headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
     }, (res) => {
       let data = '';
-      res.on('data', c => data += c);
+      res.on('data', ch => data += ch);
       res.on('end', () => resolve({ statusCode: res.statusCode, body: data, ms: Date.now() - start }));
     });
     req.on('error', (err) => resolve({ statusCode: 0, body: err.message, ms: Date.now() - start }));
@@ -80,26 +80,41 @@ function now() {
 }
 
 function eventColor(event) {
-  if (event?.includes('deposit')) return c.green;
-  if (event?.includes('sweep')) return c.cyan;
+  if (event?.includes('deposit'))    return c.green;
+  if (event?.includes('sweep'))      return c.cyan;
   if (event?.includes('withdrawal')) return c.blue;
-  if (event?.includes('address')) return c.magenta;
+  if (event?.includes('address'))    return c.magenta;
   return c.white;
 }
 
+function prettyJson(obj) {
+  return JSON.stringify(obj, null, 2)
+    .split('\n')
+    .map(l => '  ' + l)
+    .join('\n');
+}
+
 module.exports = function listen(argv) {
-  const args = parseArgs(argv);
-  const apiKey = args['api-key'] || process.env.PAYCHAINLY_API_KEY;
-  const host   = args['host'] || process.env.PAYCHAINLY_HOST || 'http://localhost:3002';
-  const secret = args['secret'] || process.env.PAYCHAINLY_WEBHOOK_SECRET || '';
+  const args     = parseArgs(argv);
+  const apiKey   = args['api-key']    || process.env.PAYCHAINLY_API_KEY;
+  const host     = args['host']       || process.env.PAYCHAINLY_HOST || 'https://api.paychainly.com';
+  const secret   = args['secret']     || process.env.PAYCHAINLY_WEBHOOK_SECRET || '';
   const forwardTo = args['forward-to'] || (args['port'] ? `http://localhost:${args['port']}/webhook` : 'http://localhost:3000/webhook');
+  const verbose  = !!args['verbose'];
+  const filter   = args['filter'] || null;
+  const logPath  = args['log']    || null;
 
   if (!apiKey) {
     console.error(`${c.red}✗ Missing --api-key. Run: paychainly listen --api-key <pk_live_...>${c.reset}`);
     process.exit(1);
   }
 
-  // ── Header ────────────────────────────────────────────────────────────────
+  let logStream = null;
+  if (logPath) {
+    logStream = fs.createWriteStream(logPath, { flags: 'a' });
+    logStream.on('error', (err) => console.error(`${c.red}✗ Log file error: ${err.message}${c.reset}`));
+  }
+
   console.log(`
 ${c.bold}${c.cyan}  ╔═══════════════════════════════════════╗
   ║       Paychainly  CLI  Relay          ║
@@ -107,11 +122,15 @@ ${c.bold}${c.cyan}  ╔═══════════════════
 `);
   console.log(`  ${c.gray}Server  :${c.reset} ${host}`);
   console.log(`  ${c.gray}Forward :${c.reset} ${c.cyan}${forwardTo}${c.reset}`);
-  if (secret) console.log(`  ${c.gray}Secret  :${c.reset} ${c.green}✓ signature verification enabled${c.reset}`);
+  if (filter)  console.log(`  ${c.gray}Filter  :${c.reset} ${c.yellow}${filter}${c.reset}`);
+  if (logPath) console.log(`  ${c.gray}Log     :${c.reset} ${logPath}`);
+  if (verbose) console.log(`  ${c.gray}Mode    :${c.reset} ${c.cyan}verbose${c.reset}`);
+  if (secret)  console.log(`  ${c.gray}Secret  :${c.reset} ${c.green}✓ signature verification enabled${c.reset}`);
   console.log(`  ${c.gray}API key :${c.reset} ${apiKey.slice(0, 12)}${'•'.repeat(8)}\n`);
 
   let connected = false;
   let eventCount = 0;
+  const eventStats = {};
 
   function connect() {
     const socket = io(`${host}/relay`, {
@@ -137,7 +156,7 @@ ${c.bold}${c.cyan}  ╔═══════════════════
       console.log(`\n  ${c.yellow}⚠ Replaced by a newer connection.${c.reset}`);
     });
 
-    socket.on('connect_error', (err) => {
+    socket.on('connect_error', () => {
       if (!connected) {
         process.stdout.write(`  ${c.yellow}⟳ Connecting to ${host}...${c.reset}\r`);
       }
@@ -156,16 +175,34 @@ ${c.bold}${c.cyan}  ╔═══════════════════
     });
 
     socket.on('webhook', async ({ relayId, payload, targetUrl }) => {
+      // Skip events that don't match the filter (ack silently)
+      if (filter && payload?.event !== filter) {
+        socket.emit('webhook_response', { relayId, statusCode: 200, body: '' });
+        return;
+      }
+
       eventCount++;
-      const target = forwardTo || targetUrl;
+      const evtName = payload?.event || 'unknown';
+      eventStats[evtName] = (eventStats[evtName] || 0) + 1;
+
+      const target   = forwardTo || targetUrl;
       const sigValid = secret ? verifySignature(payload, secret) : null;
-      const ec = eventColor(payload?.event);
-      const divider = c.gray + '  ' + '─'.repeat(56) + c.reset;
+      const ec       = eventColor(payload?.event);
+      const divider  = c.gray + '  ' + '─'.repeat(56) + c.reset;
 
       console.log(divider);
-      console.log(`  ${c.bold}${ec}${payload?.event || 'unknown'}${c.reset}  ${c.gray}${now()}${c.reset}  ${c.gray}#${eventCount}${c.reset}`);
+      console.log(`  ${c.bold}${ec}${evtName}${c.reset}  ${c.gray}${now()}${c.reset}  ${c.gray}#${eventCount}${c.reset}`);
+
       if (sigValid === true)  console.log(`  ${c.green}🔐 Signature valid${c.reset}`);
       if (sigValid === false) console.log(`  ${c.red}🔐 Signature INVALID${c.reset}`);
+
+      if (verbose) {
+        console.log(`\n${c.gray}${prettyJson(payload)}${c.reset}\n`);
+      }
+
+      // Write to log file before forwarding
+      if (logStream) logStream.write(JSON.stringify(payload) + '\n');
+
       console.log(`  ${c.gray}→${c.reset} ${target}`);
 
       const result = await postToLocal(target, payload);
@@ -176,7 +213,8 @@ ${c.bold}${c.cyan}  ╔═══════════════════
       } else if (result.statusCode === 0) {
         console.log(`  ${c.red}✗ Connection refused — is your local server running?${c.reset}`);
       } else {
-        console.log(`  ${c.red}✗ ${result.statusCode}  ${result.ms}ms${c.reset}  ${c.gray}${result.body?.slice(0, 80)}${c.reset}`);
+        console.log(`  ${c.red}✗ ${result.statusCode}  ${result.ms}ms${c.reset}`);
+        if (result.body) console.log(`  ${c.gray}  ${result.body.slice(0, 200)}${c.reset}`);
       }
 
       socket.emit('webhook_response', {
@@ -194,7 +232,15 @@ ${c.bold}${c.cyan}  ╔═══════════════════
   process.on('SIGINT', () => {
     console.log(`\n\n  ${c.gray}Closing relay...${c.reset}`);
     socket.disconnect();
-    console.log(`  ${c.green}✓ ${eventCount} event(s) relayed${c.reset}\n`);
+    if (logStream) logStream.end();
+    console.log(`  ${c.green}✓ ${eventCount} event(s) relayed${c.reset}`);
+    if (eventCount > 0) {
+      Object.entries(eventStats).forEach(([evt, count]) => {
+        console.log(`  ${c.gray}  ${evt}: ${count}${c.reset}`);
+      });
+      if (logPath) console.log(`  ${c.gray}  saved → ${logPath}${c.reset}`);
+    }
+    console.log();
     process.exit(0);
   });
 };

package/src/replay.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const fs    = require('fs');
+const http  = require('http');
+const https = require('https');
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', green: '\x1b[32m', cyan: '\x1b[36m',
+  red: '\x1b[31m', gray: '\x1b[90m', yellow: '\x1b[33m', white: '\x1b[37m',
+  magenta: '\x1b[35m', blue: '\x1b[34m',
+};
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      args[key] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+    }
+  }
+  return args;
+}
+
+function postToLocal(url, payload) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify(payload);
+    const parsed = new URL(url);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const start = Date.now();
+    const req = lib.request({
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+    }, (res) => {
+      let data = '';
+      res.on('data', ch => data += ch);
+      res.on('end', () => resolve({ statusCode: res.statusCode, body: data, ms: Date.now() - start }));
+    });
+    req.on('error', (err) => resolve({ statusCode: 0, body: err.message, ms: Date.now() - start }));
+    req.setTimeout(30_000, () => { req.destroy(); resolve({ statusCode: 0, body: 'timeout', ms: Date.now() - start }); });
+    req.write(body);
+    req.end();
+  });
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+function eventColor(event) {
+  if (event?.includes('deposit'))    return c.green;
+  if (event?.includes('sweep'))      return c.cyan;
+  if (event?.includes('withdrawal')) return c.blue;
+  if (event?.includes('address'))    return c.magenta;
+  return c.white;
+}
+
+function prettyJson(obj) {
+  return JSON.stringify(obj, null, 2).split('\n').map(l => '  ' + l).join('\n');
+}
+
+module.exports = async function replay(argv) {
+  const args      = parseArgs(argv);
+  const logFile   = args['log'];
+  const forwardTo = args['forward-to'] || (args['port'] ? `http://localhost:${args['port']}/webhook` : 'http://localhost:3000/webhook');
+  const filter    = args['filter'] || null;
+  const delay     = parseInt(args['delay'] || '500', 10);
+  const verbose   = !!args['verbose'];
+
+  if (!logFile) {
+    console.error(`${c.red}✗ Missing --log <file>. Run: paychainly replay --log events.jsonl${c.reset}`);
+    process.exit(1);
+  }
+
+  let lines;
+  try {
+    lines = fs.readFileSync(logFile, 'utf8').split('\n').filter(Boolean);
+  } catch {
+    console.error(`${c.red}✗ Cannot read file: ${logFile}${c.reset}`);
+    process.exit(1);
+  }
+
+  const events   = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  const toReplay = filter ? events.filter(e => e.event === filter) : events;
+
+  console.log(`
+${c.bold}${c.cyan}  ╔═══════════════════════════════════════╗
+  ║       Paychainly  CLI  Replay         ║
+  ╚═══════════════════════════════════════╝${c.reset}
+`);
+  console.log(`  ${c.gray}File    :${c.reset} ${logFile}`);
+  console.log(`  ${c.gray}Forward :${c.reset} ${c.cyan}${forwardTo}${c.reset}`);
+  console.log(`  ${c.gray}Events  :${c.reset} ${toReplay.length}${filter ? `  ${c.yellow}(filter: ${filter})${c.reset}` : ''}`);
+  console.log(`  ${c.gray}Delay   :${c.reset} ${delay}ms between events\n`);
+
+  if (toReplay.length === 0) {
+    console.log(`  ${c.yellow}No events to replay.${c.reset}\n`);
+    return;
+  }
+
+  let ok = 0, fail = 0;
+
+  for (let i = 0; i < toReplay.length; i++) {
+    const payload = toReplay[i];
+    const evtName = payload?.event || 'unknown';
+    const ec      = eventColor(evtName);
+    const divider = c.gray + '  ' + '─'.repeat(56) + c.reset;
+
+    console.log(divider);
+    console.log(`  ${c.bold}${ec}${evtName}${c.reset}  ${c.gray}#${i + 1}/${toReplay.length}${c.reset}`);
+
+    if (verbose) {
+      console.log(`\n${c.gray}${prettyJson(payload)}${c.reset}\n`);
+    }
+
+    console.log(`  ${c.gray}→${c.reset} ${forwardTo}`);
+
+    const result = await postToLocal(forwardTo, payload);
+    const isOk   = result.statusCode >= 200 && result.statusCode < 300;
+
+    if (isOk) {
+      ok++;
+      console.log(`  ${c.green}✓ ${result.statusCode}  ${result.ms}ms${c.reset}`);
+    } else if (result.statusCode === 0) {
+      fail++;
+      console.log(`  ${c.red}✗ Connection refused — is your local server running?${c.reset}`);
+    } else {
+      fail++;
+      console.log(`  ${c.red}✗ ${result.statusCode}  ${result.ms}ms${c.reset}`);
+      if (result.body) console.log(`  ${c.gray}  ${result.body.slice(0, 200)}${c.reset}`);
+    }
+
+    if (i < toReplay.length - 1) await sleep(delay);
+  }
+
+  const divider = c.gray + '  ' + '─'.repeat(56) + c.reset;
+  console.log(divider);
+  console.log(`\n  ${c.green}✓ ${ok} delivered${c.reset}${fail ? `  ${c.red}✗ ${fail} failed${c.reset}` : ''}\n`);
+};

package/src/status.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const { io } = require('socket.io-client');
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', green: '\x1b[32m',
+  cyan: '\x1b[36m', red: '\x1b[31m', gray: '\x1b[90m', yellow: '\x1b[33m',
+};
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      args[key] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+    }
+  }
+  return args;
+}
+
+module.exports = function status(argv) {
+  const args   = parseArgs(argv);
+  const apiKey = args['api-key'] || process.env.PAYCHAINLY_API_KEY;
+  const host   = args['host']    || process.env.PAYCHAINLY_HOST || 'https://api.paychainly.com';
+
+  if (!apiKey) {
+    console.error(`${c.red}✗ Missing --api-key${c.reset}`);
+    process.exit(1);
+  }
+
+  console.log(`\n  ${c.bold}${c.cyan}Paychainly Status Check${c.reset}\n`);
+  console.log(`  ${c.gray}Server  :${c.reset} ${host}`);
+  console.log(`  ${c.gray}API key :${c.reset} ${apiKey.slice(0, 12)}${'•'.repeat(8)}\n`);
+
+  process.stdout.write(`  ${c.yellow}⟳ Connecting...${c.reset}\r`);
+
+  const socket = io(`${host}/relay`, {
+    auth: { apiKey },
+    transports: ['websocket'],
+    reconnection: false,
+    timeout: 10000,
+  });
+
+  socket.on('relay_connected', ({ userId, mode }) => {
+    process.stdout.write(' '.repeat(40) + '\r');
+    console.log(`  ${c.green}✓ API key valid${c.reset}`);
+    console.log(`  ${c.gray}User ID :${c.reset} ${userId}`);
+    console.log(`  ${c.gray}Mode    :${c.reset} ${mode}\n`);
+    socket.disconnect();
+    process.exit(0);
+  });
+
+  socket.on('relay_error', ({ message }) => {
+    process.stdout.write(' '.repeat(40) + '\r');
+    console.error(`  ${c.red}✗ ${message}${c.reset}\n`);
+    socket.disconnect();
+    process.exit(1);
+  });
+
+  socket.on('connect_error', (err) => {
+    process.stdout.write(' '.repeat(40) + '\r');
+    console.error(`  ${c.red}✗ Cannot reach server: ${err.message}${c.reset}\n`);
+    process.exit(1);
+  });
+
+  setTimeout(() => {
+    console.error(`\n  ${c.red}✗ Timed out after 10s — server unreachable${c.reset}\n`);
+    process.exit(1);
+  }, 10000);
+};

package/README.md

@@ -1,98 +0,0 @@
-# @paychainly/cli
-
-Relay Paychainly webhooks to your local development server. No public URL or tunneling service required.
-
-## The Problem
-
-When you add a webhook URL like `http://localhost:3000/webhook` in the Paychainly dashboard, the Paychainly server cannot reach your machine — it's behind NAT/firewall. This CLI solves that by opening an outbound WebSocket connection from your machine to Paychainly and forwarding incoming webhooks locally.
-
-## Installation
-
-No install needed — use `npx`:
-
-```bash
-npx @paychainly/cli listen --api-key <your-api-key> --port 3000
-```
-
-Or install globally:
-
-```bash
-npm install -g @paychainly/cli
-paychainly listen --api-key <your-api-key> --port 3000
-```
-
-## Usage
-
-```
-paychainly listen [options]
-
-Options:
-  --api-key      Your Paychainly API key (pk_live_... or pk_test_...)  [required]
-  --port         Local port to forward webhooks to (default: 3000)
-  --forward-to   Full local URL to forward webhooks to (overrides --port)
-  --host         Paychainly server URL (default: https://api.paychainly.com)
-  --secret       Webhook signing secret to verify HMAC-SHA256 signatures
-```
-
-### Basic — forward to port 3000
-
-```bash
-npx @paychainly/cli listen \
-  --api-key pk_live_xxxxxxxxxxxxxxxxxxxx \
-  --port 3000
-```
-
-### Custom path
-
-```bash
-npx @paychainly/cli listen \
-  --api-key pk_live_xxxxxxxxxxxxxxxxxxxx \
-  --forward-to http://localhost:4000/api/webhook
-```
-
-### With signature verification
-
-If you set a webhook secret in the Paychainly dashboard, pass it here to verify every incoming signature:
-
-```bash
-npx @paychainly/cli listen \
-  --api-key pk_live_xxxxxxxxxxxxxxxxxxxx \
-  --port 3000 \
-  --secret whsec_xxxxxxxxxxxxxxxxxxxx
-```
-
-## How It Works
-
-1. The CLI connects to Paychainly via WebSocket using your API key.
-2. Paychainly detects that your webhook URL points to `localhost` and routes events through the relay instead of making a direct HTTP call.
-3. The CLI receives each event, POSTs it to your local server, and returns the response back to Paychainly.
-
-Your local server handles webhooks exactly as it would in production — same headers, same payload, same HMAC signature.
-
-## Webhook Payload
-
-Paychainly sends a signed `POST` with `Content-Type: application/json`. The `X-Paychainly-Signature` header contains an HMAC-SHA256 signature you can verify:
-
-```js
-const crypto = require('crypto')
-
-function verifySignature(rawBody, signature, secret) {
-  const expected = crypto
-    .createHmac('sha256', secret)
-    .update(rawBody)
-    .digest('hex')
-  return crypto.timingSafeEqual(
-    Buffer.from(signature),
-    Buffer.from(expected)
-  )
-}
-```
-
-## Requirements
-
-- Node.js 18 or later
-- A Paychainly account with an API key
-
-## License
-
-MIT