@paychainly/cli 1.1.3 → 1.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @paychainly/cli
 
-> Relay live Paychainly webhooks to your local server during development — no public URL needed.
+> Relay live Paychainly webhooks to your local server during development — no public URL, no tunneling tool needed.
 
 [![npm version](https://img.shields.io/npm/v/@paychainly/cli)](https://www.npmjs.com/package/@paychainly/cli)
 [![license](https://img.shields.io/npm/l/@paychainly/cli)](LICENSE)
@@ -21,7 +21,7 @@ npm install -g @paychainly/cli
 paychainly listen --api-key pk_live_... --forward-to http://localhost:3000/webhook
 ```
 
-Webhooks fired on [api.paychainly.com](https://api.paychainly.com) are forwarded in real time to your local server.
+Webhooks fired on [api.paychainly.com](https://api.paychainly.com) are forwarded in real time to your local server. **You do not need a webhook URL configured in your Paychainly account** — the CLI relay works independently.
 
 ---
 
@@ -47,7 +47,7 @@ paychainly listen [options]
 **Examples**
 
 ```bash
-# Basic
+# Basic — forward to port 3000
 paychainly listen --api-key pk_live_... --port 3000
 
 # Show full payload for every event
@@ -62,6 +62,8 @@ paychainly listen --api-key pk_live_... \
 paychainly listen --api-key pk_live_... --secret whsec_...
 ```
 
+Press `Ctrl+C` to stop. A per-event-type summary is printed on exit.
+
 ---
 
 ### `status` — check API key & connectivity
@@ -70,7 +72,7 @@ paychainly listen --api-key pk_live_... --secret whsec_...
 paychainly status --api-key pk_live_...
 ```
 
-Connects to the server, validates the key, and prints the user ID and account mode. Useful for confirming your key is correct before starting a session.
+Connects to the server, validates the key, and prints your account email and mode. Exit code `0` = valid, `1` = invalid/unreachable.
 
 ---
 
@@ -104,26 +106,88 @@ paychainly replay --log events.jsonl \
 
 ---
 
+## How Relay Forwarding Works
+
+The CLI connects to `api.paychainly.com` over a persistent WebSocket. When any payment event fires, the server checks whether your CLI is connected and routes accordingly. **You do not need a webhook URL saved in your account for the CLI to receive events.**
+
+| # | Scenario | Webhook in account? | CLI connected? | What happens |
+|---|---|---|---|---|
+| 1 | **CLI only** | None | ✅ Yes | Event delivered to CLI → forwarded to `--forward-to` |
+| 2 | **`localhost` webhook + CLI** | Yes — `localhost` URL | ✅ Yes | Routed through CLI relay only — **no double-send** |
+| 3 | **Public webhook + CLI** | Yes — `https://...` URL | ✅ Yes | Public URL is called via HTTP **and** CLI relay also receives the event |
+| 4 | **Public webhook, no CLI** | Yes — `https://...` URL | ❌ No | Public URL called only, works as normal |
+| 5 | **Nothing configured** | None | ❌ No | Event fires on-chain but nothing receives it — connect the CLI or add a webhook |
+
+### Key rules
+
+- **No webhook required** — connect the CLI and events arrive immediately, zero dashboard config needed.
+- **No double-send for `localhost` webhooks** — if your saved webhook URL is a `localhost` address, the server routes it through the CLI relay and does not make a separate HTTP call.
+- **Public webhook + CLI = both receive** — your production endpoint gets the HTTP POST and the CLI relay also gets a copy so you can inspect it locally.
+- **`--forward-to` is the delivery target** — for relay-only deliveries (scenarios 1 & 3), the server sends an empty target URL and the CLI falls back to your `--forward-to` value.
+
+### Covered events
+
+All server-side events are relayed:
+
+| Event | Trigger |
+|---|---|
+| `deposit_detected` | USDT transfer confirmed at a deposit address |
+| `sweep_started` | Fund sweep initiated |
+| `sweep_completed` | Funds swept to master wallet |
+| `sweep_failed` | Sweep failed after max retries |
+| `sweep_skipped` | Sweep skipped (e.g. dust amount) |
+| `address_created` | New deposit address generated |
+| `withdrawal_pending` | Withdrawal queued |
+| `withdrawal_processing` | Withdrawal submitted on-chain |
+| `withdrawal_completed` | Withdrawal confirmed |
+| `withdrawal_failed` | Withdrawal failed |
+| `manual_drain_pending` | Manual drain queued |
+| `manual_drain_completed` | Manual drain confirmed |
+| `manual_drain_failed` | Manual drain failed |
+
+---
+
 ## Typical Developer Workflow
 
 ```bash
-# 1. Start listening and capture events to a file
-paychainly listen --api-key pk_live_... --log events.jsonl --verbose
+# 1. Start your local webhook handler
+node server.js
 
-# 2. Trigger a test payment on your dashboard
-# 3. Inspect your webhook handler logs
+# 2. In a second terminal — start the CLI relay and capture events
+paychainly listen \
+  --api-key pk_live_... \
+  --log events.jsonl \
+  --verbose
+
+# 3. Trigger a test payment from the Paychainly dashboard
+#    → event appears in the terminal, forwarded to your handler
+
+# 4. Fix a bug in your handler, restart it
 
-# 4. Fix a bug in your handler, restart your server
+# 5. Replay the exact same events — no new payment needed
+paychainly replay \
+  --log events.jsonl \
+  --filter deposit_detected
+```
+
+### Sandbox testing (no real funds)
 
-# 5. Replay the captured events — no real payment needed
-paychainly replay --log events.jsonl --filter deposit_detected
+```bash
+# Use a pk_test_... key — free, no real USDT
+paychainly listen --api-key pk_test_...
+
+# Credit test USDT to a sandbox deposit address
+curl -X POST https://api.paychainly.com/api/sandbox/credit \
+  -H "X-Api-Key: pk_test_..." \
+  -H "Content-Type: application/json" \
+  -d '{"address":"0xYOUR_DEPOSIT_ADDRESS","amount":"50"}'
 ```
 
 ---
 
 ## Environment Variables
 
-You can set these instead of passing flags every time:
+Set these to avoid passing flags every session:
 
 ```bash
 export PAYCHAINLY_API_KEY=pk_live_...
@@ -133,17 +197,6 @@ export PAYCHAINLY_WEBHOOK_SECRET=whsec_...            # optional
 
 ---
 
-## Webhook Events
-
-| Event | Description |
-|---|---|
-| `deposit_detected` | A USDT transfer to a monitored deposit address was confirmed |
-| `sweep_completed` | Funds swept from deposit address to master wallet |
-| `address_expired` | A deposit address session expired without a payment |
-| `withdrawal_completed` | A user-initiated withdrawal was processed |
-
----
-
 ## License
 
 MIT © [Paychainly](https://paychainly.com)

package/package.json

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