@paychainly/cli 1.0.2 → 1.0.3

package/README.md

@@ -0,0 +1,98 @@
+# @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paychainly/cli",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Paychainly CLI — relay webhooks to your localhost during development",
   "keywords": [
     "paychainly",