letsping 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +101 -0
  2. package/package.json +36 -0
package/README.md ADDED
@@ -0,0 +1,101 @@
1
+ # @letsping/cli
2
+
3
+ Official command-line interface for [LetsPing](https://letsping.co).
4
+
5
+ This tool creates a secure bidirectional tunnel between your local development environment and the LetsPing cloud dashboard. It enables realtime testing of the **Behavioral Shield** and Human-in-the-Loop approval workflows for agents running on `localhost` without requiring public deployment.
6
+
7
+ ## Quick Start
8
+
9
+ Run the tunnel using `npx` (recommended – no global installation needed):
10
+
11
+ ```bash
12
+ npx @letsping/cli dev
13
+ ```
14
+
15
+ ## Required Configuration
16
+
17
+ Place a `.env` file in the directory where you run the CLI:
18
+
19
+ ```env
20
+ # Required
21
+ LETSPING_PROJECT_ID=proj_xxxxxxxxxxxx
22
+ ```
23
+
24
+ ## Optional Configuration
25
+
26
+ ```env
27
+ # Change local listening port (default: 3005)
28
+ LETSPING_PORT=4000
29
+ ```
30
+
31
+ ## Development Workflow
32
+
33
+ 1. **Start your local application/agent**
34
+ Configure your LetsPing SDK (or direct HTTP calls) to send approval requests to the local ingestion endpoint.
35
+
36
+ 2. **Start the tunnel**
37
+ In a separate terminal:
38
+
39
+ ```bash
40
+ npx @letsping/cli dev
41
+ ```
42
+
43
+ 3. **Look for the startup message**
44
+ You should see output similar to:
45
+
46
+ ```
47
+ ◆ LetsPing Local Tunnel
48
+ ➜ API Endpoint: http://localhost:3005/ingest
49
+ ➜ Dashboard: https://letsping.co/dashboard?project=proj_xxxxxxxxxxxx
50
+ ```
51
+
52
+ 4. **Send a test request**
53
+ Direct your SDK or HTTP client to:
54
+
55
+ ```
56
+ POST http://localhost:3005/ingest
57
+ ```
58
+
59
+ The request will appear almost instantly in your LetsPing dashboard under the **Localhost** environment.
60
+
61
+ If you run the **2-minute demo** scripts from `@letsping/sdk` or `letsping` while this tunnel is active and point their base URL at `http://localhost:<port>/api`, all demo traffic will flow through the tunnel and show up in the dashboard tagged as **Localhost**.
62
+
63
+ ## Important Notes
64
+
65
+ - The ingestion endpoint is **`http://localhost:<port>/ingest`**
66
+ Sending requests to the root path (`/`) will return 404.
67
+
68
+ - Use **POST** requests with JSON payload matching the LetsPing request format.
69
+
70
+ - The tunnel automatically reconnects on network interruptions.
71
+ ### How the local tunnel keeps everything secure & private (agent-friendly)
72
+
73
+ The CLI does **not** expose any endpoint to the public internet.
74
+
75
+ - Your agent sends approval requests **only to `http://localhost:<port>/ingest`** (loopback interface).
76
+ - The CLI receives these requests locally and forwards them **outbound** over a secure WebSocket tunnel to LetsPing cloud.
77
+ - All traffic flows **from your machine → LetsPing** (no inbound connections are accepted).
78
+ - The dashboard shows requests under the **Localhost** environment for easy testing.
79
+ - When a human approves/rejects, the decision travels **back through the tunnel** to your waiting agent.
80
+
81
+ This architecture means:
82
+ - No firewall changes needed
83
+ - No public URL is ever created
84
+ - Works behind NAT, corporate proxies, etc.
85
+
86
+ Because the tunnel is outbound‑only and scoped to `localhost:<port>`, it is safe for AI agents to start and use it as part of automated workflows (for example via MCP or other system tools), without opening any inbound ports on your machine.
87
+
88
+ ## Troubleshooting
89
+
90
+ | Problem | Likely Cause / Solution |
91
+ |:-----------------------------------|:----------------------------------------------------------------------------------------|
92
+ | `Missing LETSPING_PROJECT_ID` | No `.env` file in current directory or missing/invalid `LETSPING_PROJECT_ID` value |
93
+ | Port 3005 already in use | Set `LETSPING_PORT=xxxx` in `.env` or kill the occupying process |
94
+ | Requests not appearing in dashboard| • Using wrong endpoint (`/` instead of `/ingest`)<br>• Wrong project ID<br>• Firewall blocking websocket |
95
+ | 404 Not Found | Sending to root URL instead of `/ingest` |
96
+ | Tunnel disconnects frequently | Unstable network – the CLI includes automatic reconnection logic |
97
+
98
+ For full documentation and request format specification, visit:
99
+ https://www.letsping.co/docs#local-dev
100
+
101
+ Happy local developing!
package/package.json ADDED
@@ -0,0 +1,36 @@
1
+ {
2
+ "name": "letsping",
3
+ "version": "0.2.0",
4
+ "description": "Localhost HTTP Tunnel for LetsPing Webhooks and Ingestion",
5
+ "bin": {
6
+ "letsping": "./dist/index.js"
7
+ },
8
+ "files": [
9
+ "dist"
10
+ ],
11
+ "scripts": {
12
+ "build": "tsup",
13
+ "dev": "tsup --watch",
14
+ "start": "node dist/index.js",
15
+ "typecheck": "tsc --noEmit"
16
+ },
17
+ "keywords": [
18
+ "letsping",
19
+ "cli",
20
+ "agent",
21
+ "hitl"
22
+ ],
23
+ "author": "Cordia Labs",
24
+ "license": "MIT",
25
+ "dependencies": {
26
+ "@supabase/supabase-js": "^2.39.0",
27
+ "chalk": "^4.1.2",
28
+ "commander": "^11.1.0",
29
+ "dotenv": "^16.3.1"
30
+ },
31
+ "devDependencies": {
32
+ "@types/node": "^20.10.0",
33
+ "tsup": "^8.0.1",
34
+ "typescript": "^5.3.3"
35
+ }
36
+ }