private-connect 0.5.7 → 0.5.9

package/README.md

@@ -2,6 +2,15 @@
 
 Zero-friction connectivity tools. No signup required.
 
+## Installation
+
+```bash
+npm i private-connect          # add to your project
+npm i -g private-connect       # install globally
+```
+
+**Run it:** after a global install use `private-connect`; after a local install use `npx private-connect`. Or run without installing: `npx private-connect <command>`.
+
 ## Quick Start
 
 ```bash
@@ -10,6 +19,10 @@ npx private-connect test db.internal:5432
 
 # Create a temporary public tunnel
 npx private-connect tunnel 3000
+
+# Test webhooks locally (Polar, Stripe, GitHub, or any provider)
+npx private-connect polar 3000
+npx private-connect stripe 3000
 ```
 
 ## Commands
@@ -53,7 +66,7 @@ Private Connect - Temporary Tunnel
 ────────────────────────────────────
 
   Local:   localhost:3000
-  Public:  https://privateconnect.co/w/abc12345
+  Public:  https://abc12345.privateconnect.co
            Anyone can access this URL
   Inspector: https://privateconnect.co/debug/s-xyz789
            Live traffic monitoring & request replay
@@ -64,6 +77,20 @@ Private Connect - Temporary Tunnel
   Press Ctrl+C to stop
 ```
 
+**TCP/UDP Tunnels:**
+```bash
+npx private-connect tunnel 5432 --tcp    # TCP tunnel (databases, etc.)
+npx private-connect tunnel 27015 --udp   # UDP tunnel (game servers, etc.)
+```
+
+TCP/UDP output shows connection details:
+```
+  Local:   localhost:5432
+  Public:  tcp://api.privateconnect.co:40001
+  Connect: api.privateconnect.co:40001
+  Expires: 120 minutes
+```
+
 **Sharing:**
 - The public URL shows your actual website (like ngrok)
 - Perfect for demos, testing, and sharing with teammates
@@ -73,9 +100,33 @@ Private Connect - Temporary Tunnel
 - No signup or account required
 - Auto-expires in 2 hours
 - Real-time request logging
-- Works with any HTTP service
+- Works with HTTP, TCP, and UDP services
 - **Shareable URLs** - The public URL shows your actual website, perfect for demos and testing
 
+### `<provider> <port>` - Webhook tunnel with provider setup
+
+```bash
+npx private-connect <provider> <port>
+```
+
+Create a tunnel and get provider-specific webhook setup instructions.
+
+**Known providers** (with tailored instructions):
+- `polar` — [Polar](https://polar.sh) webhooks
+- `stripe` — [Stripe](https://stripe.com) webhooks
+- `github` — [GitHub](https://github.com) webhooks
+- `shopify` — [Shopify](https://shopify.dev) webhooks
+
+**Any provider name works** — unknown names get generic webhook guidance.
+
+**Examples:**
+```bash
+npx private-connect polar 3000              # Polar webhooks → localhost:3000
+npx private-connect stripe 3000             # Stripe webhooks → localhost:3000
+npx private-connect github 8080             # GitHub webhooks → localhost:8080
+npx private-connect myapp 3000              # Generic webhooks → localhost:3000
+```
+
 ### `setup-openclaw` - One-command OpenClaw setup
 
 ```bash

package/dist/index.js

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const net = require("net");
+const dgram = require("dgram");
 const tls = require("tls");
 const https = require("https");
 const http = require("http");
@@ -248,6 +249,7 @@ ${c.bold}Commands:${c.reset}
   check <target>     Test connectivity to any service
   test <target>      Alias for check
   tunnel <port>      Create a temporary public tunnel
+  <provider> <port>  Webhook tunnel with provider-specific setup
   list               List all active tunnels
   close <id>         Close a tunnel by ID
   close --all        Close all active tunnels
@@ -260,6 +262,11 @@ ${c.bold}Examples:${c.reset}
   npx private-connect tunnel 3000
   npx private-connect tunnel localhost:8080
   npx private-connect tunnel 4096 --tcp
+  npx private-connect tunnel 27015 --udp
+  npx private-connect polar 3000
+  npx private-connect stripe 3000
+  npx private-connect github 8080
+  npx private-connect myapp 3000
   npx private-connect list
   npx private-connect close abc123
   npx private-connect setup-openclaw
@@ -268,7 +275,12 @@ ${c.bold}Examples:${c.reset}
 ${c.bold}Tunnel:${c.reset}
   • No signup required
   • Auto-expires in 2 hours
-  • HTTP or raw TCP (--tcp flag)
+  • HTTP, TCP (--tcp), or UDP (--udp)
+
+${c.bold}Webhooks:${c.reset}
+  • Use any provider name: polar, stripe, github, shopify, or your own
+  • Known providers get tailored setup instructions
+  • Unknown providers get generic webhook guidance
 
 ${c.bold}Test:${c.reset}
   • TCP reachability
@@ -284,30 +296,112 @@ ${c.bold}OpenClaw:${c.reset}
 ${c.dim}For permanent tunnels: https://privateconnect.co${c.reset}
 `);
 }
+const WEBHOOK_PROVIDERS = {
+    polar: {
+        name: 'Polar',
+        dashboardUrl: 'https://polar.sh',
+        docsUrl: 'https://polar.sh/docs/integrate/webhooks',
+        secretEnvVar: 'POLAR_WEBHOOK_SECRET',
+        instructions: [
+            'Go to ${dashboardUrl} → Settings → Webhooks',
+            'Add the public URL above as your webhook endpoint',
+            'Copy the signing secret and set it as ${secretEnvVar}',
+            'Docs: ${docsUrl}',
+        ],
+    },
+    stripe: {
+        name: 'Stripe',
+        dashboardUrl: 'https://dashboard.stripe.com',
+        docsUrl: 'https://docs.stripe.com/webhooks',
+        secretEnvVar: 'STRIPE_WEBHOOK_SECRET',
+        instructions: [
+            'Go to ${dashboardUrl} → Developers → Webhooks',
+            'Add the public URL above as your webhook endpoint',
+            'Copy the signing secret (whsec_...) and set it as ${secretEnvVar}',
+            'Docs: ${docsUrl}',
+        ],
+    },
+    github: {
+        name: 'GitHub',
+        dashboardUrl: 'https://github.com',
+        docsUrl: 'https://docs.github.com/en/webhooks',
+        secretEnvVar: 'GITHUB_WEBHOOK_SECRET',
+        instructions: [
+            'Go to your repo → Settings → Webhooks → Add webhook',
+            'Set the Payload URL to the public URL above',
+            'Set a secret and store it as ${secretEnvVar}',
+            'Docs: ${docsUrl}',
+        ],
+    },
+    shopify: {
+        name: 'Shopify',
+        dashboardUrl: 'https://admin.shopify.com',
+        docsUrl: 'https://shopify.dev/docs/apps/build/webhooks',
+        secretEnvVar: 'SHOPIFY_WEBHOOK_SECRET',
+        instructions: [
+            'Go to ${dashboardUrl} → Settings → Notifications → Webhooks',
+            'Add the public URL above as your webhook endpoint',
+            'Use the signing secret from your app settings as ${secretEnvVar}',
+            'Docs: ${docsUrl}',
+        ],
+    },
+};
+// Reserved CLI commands that should NOT be treated as provider names
+const RESERVED_COMMANDS = ['test', 'check', 'tunnel', 'list', 'ls', 'close', 'kill', 'setup-openclaw', 'openclaw-setup', 'setup-moltbot', 'moltbot-setup', 'pair', 'qr', '--help', '-h'];
+function getProviderInstructions(provider) {
+    return provider.instructions.map(line => line
+        .replace('${dashboardUrl}', provider.dashboardUrl)
+        .replace('${docsUrl}', provider.docsUrl)
+        .replace('${secretEnvVar}', provider.secretEnvVar || 'WEBHOOK_SECRET'));
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Temporary Tunnel
 // ─────────────────────────────────────────────────────────────────────────────
 const HUB_URL = process.env.CONNECT_HUB_URL || 'https://api.privateconnect.co';
 const TUNNEL_DOMAIN = process.env.CONNECT_TUNNEL_DOMAIN || 'tunnel.privateconnect.co';
 async function createTemporaryTunnel(options) {
-    const { host, port, ttl = 120, tcp = false } = options;
-    const tunnelType = tcp ? 'tcp' : 'http';
+    const { host, port, ttl = 120, tcp = false, udp = false, provider: providerName } = options;
+    const tunnelType = udp ? 'udp' : (tcp ? 'tcp' : 'http');
+    const provider = providerName ? WEBHOOK_PROVIDERS[providerName.toLowerCase()] : undefined;
     console.log();
-    console.log(`${c.bold}Private Connect${c.reset} - Temporary ${tcp ? 'TCP ' : ''}Tunnel`);
+    if (provider) {
+        console.log(`${c.bold}Private Connect${c.reset} - ${provider.name} Webhooks → localhost:${port}`);
+    }
+    else if (providerName) {
+        // Unknown provider — generic webhook mode
+        console.log(`${c.bold}Private Connect${c.reset} - ${providerName} Webhooks → localhost:${port}`);
+    }
+    else {
+        console.log(`${c.bold}Private Connect${c.reset} - Temporary ${udp ? 'UDP ' : tcp ? 'TCP ' : ''}Tunnel`);
+    }
     console.log(`${c.gray}────────────────────────────────────${c.reset}`);
     console.log();
     // Check if local service is running
     process.stdout.write(`  Checking ${c.cyan}${host}:${port}${c.reset}... `);
-    const localCheck = await testTcp(host, port, 2000);
-    if (!localCheck.ok) {
-        console.log(`${fail}`);
-        console.log();
-        console.log(`  ${c.red}Cannot connect to ${host}:${port}${c.reset}`);
-        console.log(`  ${c.gray}Make sure your service is running${c.reset}`);
-        console.log();
-        process.exit(1);
+    if (udp) {
+        // For UDP, we can't really test connectivity without sending data
+        // Just verify it's a valid port
+        if (port < 1 || port > 65535) {
+            console.log(`${fail}`);
+            console.log();
+            console.log(`  ${c.red}Invalid port: ${port}${c.reset}`);
+            console.log();
+            process.exit(1);
+        }
+        console.log(`${ok} ${c.dim}(UDP - assuming service is ready)${c.reset}`);
+    }
+    else {
+        const localCheck = await testTcp(host, port, 2000);
+        if (!localCheck.ok) {
+            console.log(`${fail}`);
+            console.log();
+            console.log(`  ${c.red}Cannot connect to ${host}:${port}${c.reset}`);
+            console.log(`  ${c.gray}Make sure your service is running${c.reset}`);
+            console.log();
+            process.exit(1);
+        }
+        console.log(`${ok}`);
     }
-    console.log(`${ok}`);
     // Generate a temporary tunnel ID
     const tunnelId = (0, crypto_1.randomBytes)(6).toString('hex');
     // Request tunnel from hub
@@ -388,14 +482,46 @@ async function createTemporaryTunnel(options) {
         if (data.tunnel.type === 'tcp' && data.tunnel.tcpHost && data.tunnel.tcpPort) {
             console.log(`  ${c.bold}Connect:${c.reset} ${c.cyan}${data.tunnel.tcpHost}:${data.tunnel.tcpPort}${c.reset}`);
         }
+        if (data.tunnel.type === 'udp' && data.tunnel.udpHost && data.tunnel.udpPort) {
+            console.log(`  ${c.bold}Connect:${c.reset} ${c.cyan}${data.tunnel.udpHost}:${data.tunnel.udpPort}${c.reset} ${c.dim}(UDP)${c.reset}`);
+        }
         console.log(`  ${c.bold}Expires:${c.reset} ${data.tunnel.ttlMinutes} minutes`);
+        // Show provider-specific webhook instructions
+        if (provider) {
+            console.log();
+            console.log(`${c.gray}────────────────────────────────────${c.reset}`);
+            console.log();
+            console.log(`  ${c.bold}${provider.name} Setup:${c.reset}`);
+            const lines = getProviderInstructions(provider);
+            lines.forEach((line, i) => {
+                console.log(`  ${c.dim}${i + 1}.${c.reset} ${line}`);
+            });
+        }
+        else if (providerName) {
+            // Generic webhook instructions for unknown providers
+            console.log();
+            console.log(`${c.gray}────────────────────────────────────${c.reset}`);
+            console.log();
+            console.log(`  ${c.bold}Webhook Setup:${c.reset}`);
+            console.log(`  ${c.dim}1.${c.reset} Add the public URL above as your webhook endpoint in ${providerName}`);
+            console.log(`  ${c.dim}2.${c.reset} Copy the signing secret from your ${providerName} dashboard`);
+            console.log(`  ${c.dim}3.${c.reset} Verify webhook signatures in your local handler`);
+        }
         console.log();
         console.log(`${c.gray}────────────────────────────────────${c.reset}`);
         console.log();
-        console.log(`  ${c.dim}Press Ctrl+C to stop${c.reset}`);
+        if (providerName) {
+            console.log(`  ${c.dim}Waiting for webhooks... Press Ctrl+C to stop${c.reset}`);
+        }
+        else {
+            console.log(`  ${c.dim}Press Ctrl+C to stop${c.reset}`);
+        }
         console.log();
         // Keep connection alive and handle incoming requests
-        if (data.tunnel.type === 'tcp') {
+        if (data.tunnel.type === 'udp') {
+            await runUdpTunnelProxy(data.tunnel.tunnelId, wsUrl, host, port);
+        }
+        else if (data.tunnel.type === 'tcp') {
             await runTcpTunnelProxy(data.tunnel.tunnelId, wsUrl, host, port);
         }
         else {
@@ -698,6 +824,106 @@ async function runTcpTunnelProxy(tunnelId, wsUrl, localHost, localPort) {
         });
     });
 }
+/**
+ * Run UDP tunnel proxy - forward UDP datagrams
+ */
+async function runUdpTunnelProxy(tunnelId, wsUrl, localHost, localPort) {
+    return new Promise((resolve) => {
+        const url = new url_1.URL(wsUrl.replace('ws://', 'http://').replace('wss://', 'https://'));
+        const baseUrl = `${url.protocol}//${url.host}`;
+        const namespace = url.pathname || '/temp-tunnel';
+        const socket = (0, socket_io_client_1.io)(`${baseUrl}${namespace}`, {
+            transports: ['websocket'],
+            reconnection: true,
+            reconnectionAttempts: 10,
+            reconnectionDelay: 1000,
+        });
+        // Create local UDP socket for forwarding to local service
+        const localUdpSocket = dgram.createSocket('udp4');
+        // Track UDP "sessions" by remote address for response routing
+        // sessionId -> { remoteInfo from server }
+        const sessions = new Map();
+        let packetCount = 0;
+        socket.on('connect', () => {
+            socket.emit('register', { tunnelId }, (response) => {
+                if (!response.success) {
+                    console.log(`  ${c.red}Failed to register: ${response.error}${c.reset}`);
+                    socket.disconnect();
+                    resolve();
+                }
+            });
+        });
+        socket.on('disconnect', (reason) => {
+            localUdpSocket.close();
+            if (reason === 'io server disconnect') {
+                console.log(`  ${c.yellow}Tunnel expired or closed by server${c.reset}`);
+            }
+        });
+        socket.on('tunnel_expired', () => {
+            console.log();
+            console.log(`  ${c.yellow}Tunnel expired${c.reset}`);
+            console.log();
+            localUdpSocket.close();
+            socket.disconnect();
+            resolve();
+        });
+        socket.on('server_shutdown', (data) => {
+            console.log();
+            console.log(`  ${c.yellow}⚠ Server shutting down${c.reset}`);
+            if (data.message) {
+                console.log(`  ${c.dim}${data.message}${c.reset}`);
+            }
+            if (data.reconnectIn) {
+                console.log(`  ${c.dim}Reconnect in ${data.reconnectIn} seconds...${c.reset}`);
+            }
+            console.log();
+        });
+        // Handle incoming UDP datagram from server (from remote client)
+        socket.on('udp_datagram', (data) => {
+            packetCount++;
+            const timestamp = new Date().toLocaleTimeString();
+            console.log(`  ${c.gray}[${timestamp}]${c.reset} ${c.cyan}UDP${c.reset} ← ${data.remoteAddress}:${data.remotePort} (${Buffer.from(data.data, 'base64').length} bytes)`);
+            // Store session info for response routing
+            sessions.set(data.sessionId, { address: data.remoteAddress, port: data.remotePort });
+            // Forward to local UDP service
+            const buffer = Buffer.from(data.data, 'base64');
+            localUdpSocket.send(buffer, localPort, localHost, (err) => {
+                if (err) {
+                    console.log(`  ${c.red}UDP send error: ${err.message}${c.reset}`);
+                }
+            });
+        });
+        // Handle response from local UDP service
+        localUdpSocket.on('message', (msg, rinfo) => {
+            const timestamp = new Date().toLocaleTimeString();
+            console.log(`  ${c.gray}[${timestamp}]${c.reset} ${c.cyan}UDP${c.reset} → response (${msg.length} bytes)`);
+            // Find the most recent session to send response to
+            // In practice, you might need more sophisticated session tracking
+            const lastSession = Array.from(sessions.entries()).pop();
+            if (lastSession) {
+                socket.emit('udp_response', {
+                    sessionId: lastSession[0],
+                    data: msg.toString('base64'),
+                });
+            }
+        });
+        localUdpSocket.on('error', (err) => {
+            console.log(`  ${c.red}Local UDP socket error: ${err.message}${c.reset}`);
+        });
+        // Bind local socket to receive responses
+        localUdpSocket.bind();
+        // Handle shutdown
+        process.on('SIGINT', () => {
+            console.log();
+            console.log(`  ${c.yellow}Tunnel closed${c.reset}`);
+            console.log(`  ${c.gray}Handled ${packetCount} UDP packets${c.reset}`);
+            console.log();
+            localUdpSocket.close();
+            socket.disconnect();
+            resolve();
+        });
+    });
+}
 function parseTunnelTarget(target) {
     // Handle just port number
     if (/^\d+$/.test(target)) {
@@ -989,11 +1215,17 @@ else if (args[0] === 'tunnel') {
         console.error(`Usage: npx private-connect tunnel <port>`);
         console.error(`       npx private-connect tunnel localhost:3000`);
         console.error(`       npx private-connect tunnel 4096 --tcp`);
+        console.error(`       npx private-connect tunnel 27015 --udp`);
         process.exit(1);
     }
     const { host, port } = parseTunnelTarget(args[1]);
     const tcp = args.includes('--tcp') || args.includes('-t');
-    createTemporaryTunnel({ host, port, tcp }).catch(console.error);
+    const udp = args.includes('--udp') || args.includes('-u');
+    if (tcp && udp) {
+        console.error(`${c.red}Error: Cannot use both --tcp and --udp${c.reset}`);
+        process.exit(1);
+    }
+    createTemporaryTunnel({ host, port, tcp, udp }).catch(console.error);
 }
 else if (args[0] === 'list' || args[0] === 'ls') {
     listTunnels().catch(console.error);
@@ -1018,6 +1250,12 @@ else if (args[0] === 'setup-openclaw' || args[0] === 'openclaw-setup' || args[0]
 else if (args[0] === 'pair' || args[0] === 'qr') {
     showPairingQR().catch(console.error);
 }
+else if (!RESERVED_COMMANDS.includes(args[0]) && args[1] && /^\d+$/.test(args[1].split(':').pop() || '')) {
+    // <product-name> <port|host:port> — webhook tunnel for a specific provider
+    const providerName = args[0];
+    const { host, port } = parseTunnelTarget(args[1]);
+    createTemporaryTunnel({ host, port, provider: providerName }).catch(console.error);
+}
 else {
     // Default to test if just a target is provided
     runTest(args[0]).catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "private-connect",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Access private services by name from anywhere. No VPN setup, no firewall rules. Open source alternative to ngrok and Tailscale for service-level connectivity.",
   "bin": {
     "private-connect": "./dist/index.js"